mirror of
https://github.com/angular/angular.git
synced 2026-09-14 13:54:52 +08:00
docs(slider): additional documentation (#2068)
This commit is contained in:
mmalerba
+109
-45
@@ -1,86 +1,150 @@
|
||||
# md-slider
|
||||
|
||||
`MdSlider` is a component that allows users to select from a range of values by moving the slider
|
||||
thumb.
|
||||
You can read more about the slider in the
|
||||
[Material Design spec](https://material.google.com/components/sliders.html).
|
||||
|
||||
## Not Yet Implemented
|
||||
|
||||
* Thumb Label
|
||||
* Color
|
||||
* Invert
|
||||
* NgModel
|
||||
* Keyboard Movement
|
||||
* Focus Ring
|
||||
* Smaller/grey thumb at minimum value
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
|
||||
`md-slider` can be used on its own as a slider with a min of `0`, a max of `100`, and a step of `1`.
|
||||
`md-slider` is a component that allows users to select from a range of values by moving the slider
|
||||
thumb. It is similar in behavior to the native `<input type="range">` element. You can read more
|
||||
about the slider in the [Material Design spec](https://material.google.com/components/sliders.html).
|
||||
|
||||
Simple example:
|
||||
```html
|
||||
<md-slider></md-slider>
|
||||
```
|
||||
|
||||
### Slider with Minimum and Maximum Values
|
||||
## Usage
|
||||
|
||||
The min and max on a `md-slider` can be set to give a different range of values.
|
||||
These can be set individually and do not need to both be set.
|
||||
### Changing the min, max, step, and initial value
|
||||
|
||||
By default the minimum value of the slider is `0`, the maximum value is `100`, and the thumb moves
|
||||
in increments of `1`. These values can be changed by setting the `min`, `max`, and `step` attributes
|
||||
respectively. The initial value is set to the minimum value unless otherwise specified.
|
||||
|
||||
```html
|
||||
<md-slider min="1" max="5"></md-slider>
|
||||
<md-slider min="1" max="5" step="0.5" value="1.5"></md-slider>
|
||||
```
|
||||
|
||||
### Disabled Slider
|
||||
### Setting the orientation
|
||||
|
||||
`md-slider` can be disabled so that the value cannot be changed and the thumb cannot be moved.
|
||||
By default sliders are horizontal with the minimum value on the left and the maximum value on the
|
||||
right. The `vertical` attribute can be added to a slider to make it vertical with the minimum value
|
||||
on bottom and the maximum value on top.
|
||||
|
||||
```html
|
||||
<md-slider disabled></md-slider>
|
||||
<md-slider vertical></md-slider>
|
||||
```
|
||||
|
||||
### Slider with Value
|
||||
|
||||
`md-slider` can have a value defined so that it starts at a specific value on the slider.
|
||||
An `invert` attribute is also available which can be specified to flip the axis that the thumb moves
|
||||
along. An inverted horizontal slider will have the minimum value on the right and the maximum value
|
||||
on the left, while an inverted vertical slider will have the minimum value on top and the maximum
|
||||
value on bottom.
|
||||
|
||||
```html
|
||||
<md-slider value="24"></md-slider>
|
||||
<md-slider invert></md-slider>
|
||||
```
|
||||
|
||||
### Slider with Step
|
||||
### Adding a thumb label
|
||||
|
||||
`md-slider` can have the step defined which declares where the thumb can snap to.
|
||||
By default the exact selected value of a slider is not visible to the user. However, this value can
|
||||
be added to the thumb by adding the `thumb-label` attribute.
|
||||
|
||||
The [material design spec](https://material.google.com/components/sliders.html) recommends using the
|
||||
`thumb-label` attribute (along with `tick-interval="1"`) only for sliders that are used to display a
|
||||
discrete value (such as a 1-5 rating).
|
||||
|
||||
```html
|
||||
<md-slider step="5"></md-slider>
|
||||
<md-slider thumb-label tick-interval="1"></md-slider>
|
||||
```
|
||||
|
||||
### Slider with Tick Interval
|
||||
### Adding ticks
|
||||
|
||||
`md-slider` can have a tick interval set to a number or to `auto`.
|
||||
`auto` will automatically draw tick marks on steps that are at least 30px apart and will always draw
|
||||
tick marks at the beginning and end of the slider.
|
||||
Setting `tick-interval` to a number will draw a tick mark at every `tick-interval` steps. An example
|
||||
of this is a `tick-interval` of `3` with a `step` of `4` will draw tick marks at every `3` steps,
|
||||
which is the same as every `12` values.
|
||||
By default a sliders do not show tick marks along the thumb track. They can be enabled using the
|
||||
`tick-interval` attribute. The value of `tick-interval` should be a number representing the number
|
||||
of steps between between ticks. For example a `tick-interval` of `3` with a `step` of `4` will draw
|
||||
tick marks at every `3` steps, which is the same as every `12` values.
|
||||
|
||||
```html
|
||||
<md-slider step="4" tick-interval="3"></md-slider>
|
||||
```
|
||||
|
||||
The `tick-interval` can also be set to `auto` which will automatically choose the number of steps
|
||||
such that there is at least `30px` of space between ticks.
|
||||
|
||||
```html
|
||||
<md-slider tick-interval="auto"></md-slider>
|
||||
<md-slider tick-interval="3" step="4"></md-slider>
|
||||
```
|
||||
|
||||
The slider will always show a tick at the beginning and end of the track. If the remaining space
|
||||
doesn't add up perfectly the last interval will be shortened or lengthened so that the tick can be
|
||||
shown at the end of the track.
|
||||
|
||||
The [material design spec](https://material.google.com/components/sliders.html) recommends using the
|
||||
`tick-interval` attribute (set to `1` along with the `thumb-label` attribute) only for sliders that
|
||||
are used to display a discrete value (such as a 1-5 rating).
|
||||
|
||||
### Disabling the slider
|
||||
|
||||
The `disabled` attribute can be used to disable the slider, preventing the user from changing the
|
||||
value.
|
||||
|
||||
```html
|
||||
<md-slider disabled value="5"></md-slider>
|
||||
```
|
||||
|
||||
## `<md-slider>`
|
||||
### Value binding
|
||||
|
||||
### Bound Properties
|
||||
`md-slider` supports both 1-way binding and 2-way binding via `ngModel`. It also emits a `change`
|
||||
event when the value changes due to user interaction.
|
||||
|
||||
```html
|
||||
<md-slider [value]="myValue" (change)="onChange()"></md-slider>
|
||||
```
|
||||
|
||||
```html
|
||||
<md-slider [(ngModel)]="myValue"></md-slider>
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
The slider has the following keyboard bindings:
|
||||
|
||||
| Key | Action |
|
||||
| --- | --- |
|
||||
| Right arrow | Increment the slider value by one step. (Decrement in right-to-left-languages). |
|
||||
| Up arrow | Increment the slider value by one step. |
|
||||
| Left arrow | Decrement the slider value by one step. (Increment in right-to-left-languages). |
|
||||
| Down arrow | Decrement the slider value by one step. |
|
||||
| Page up | Increment the slider value by 10 steps. |
|
||||
| Page down | Decrement the slider value by 10 steps. |
|
||||
| End | Set the value to the maximum possible. |
|
||||
| Home | Set the value to the minimum possible. |
|
||||
|
||||
## Internationalization
|
||||
|
||||
In right-to-left languages the horizontal slider has the minimum value on the right and the maximum
|
||||
value on the left by default. The meaning of the left and right arrow keys is also swapped in
|
||||
right-to-left languages.
|
||||
|
||||
## API Summary
|
||||
|
||||
### Inputs
|
||||
|
||||
| Name | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `min` | number | Optional, the minimum number for the slider. Default = `0`. |
|
||||
| `max` | number | Optional, the maximum number for the slider. Default = `100`. |
|
||||
| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. |
|
||||
| `value` | number | Optional, the value to start the slider at. |
|
||||
| `tick-interval` | `"auto" | number` | Optional, how many steps between tick marks. |
|
||||
| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. |
|
||||
| `invert` | boolean | Optional, whether to invert the axis the thumb moves along. |
|
||||
| `vertical` | boolean | Optional, whether the slider should be oriented vertically. |
|
||||
| `disabled` | boolean | Optional, whether or not the slider is disabled. Default = `false`. |
|
||||
|
||||
### Outputs
|
||||
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
| `change` | Emitted when the value changes due to user interaction. |
|
||||
|
||||
|
||||
## Future work & open questions
|
||||
|
||||
* Update focused, disabled, and `value=min` states to match spec.
|
||||
* Should there be an option to not force the end tick to be shown?
|
||||
|
||||
Reference in New Issue
Block a user