ion-range
范围滑块允许用户通过移动滑块旋钮从一系列数值中进行选择。默认情况下，一个旋钮控制范围的数值。此行为可以使用双旋钮进行自定义。
🌐 The Range slider lets users select from a range of values by moving the slider knob. By default one knob controls the value of the range. This behavior can be customized using dual knobs.
默认情况下，范围滑块的最小值为 0，最大值为 100。可以通过 min 和 max 属性进行配置。
🌐 By default the Range slider has a minimum value of 0 and a maximum value of 100. This can be configured with the min and max properties.
标签
🌐 Labels
标签应用于描述范围。它们可以用于视觉显示，当用户聚焦于范围时，屏幕阅读器也会朗读它们。这使用户能够轻松理解范围的意图。范围有几种方式来分配标签：
🌐 Labels should be used to describe the range. They can be used visually, and they will also be read out by screen readers when the user is focused on the range. This makes it easy for the user to understand the intent of the range. Range has several ways to assign a label:
label属性：用于明文标签label插槽：用于自定义 HTML 标签aria-label：用于为屏幕阅读器提供标签，但不添加可见标签
标签放置
🌐 Label Placement
下面的演示显示了如何使用 labelPlacement 属性更改标签相对于范围的位置。虽然这里使用了 label 属性，但 labelPlacement 也可以与 label 插槽一起使用。
🌐 The below demo shows how to use the labelPlacement property to change the position of the label relative to the range. While the label property is used here, labelPlacement can also be used with the label slot.
标签槽
🌐 Label Slot
虽然明文标签应通过 label 属性传入，但如果需要自定义 HTML，则可以通过 label 插槽传入。
🌐 While plaintext labels should be passed in via the label property, if custom HTML is needed, it can be passed through the label slot instead.
无可见标签
🌐 No Visible Label
即使不需要可见标签，开发者仍应提供一个 aria-label，以便屏幕阅读器可以访问该范围。
🌐 If no visible label is needed, developers should still supply an aria-label so the range is accessible to screen readers.
装饰
🌐 Decorations
装饰元素可以传入范围的 start 或 end 插槽中。这对于添加低音量或高音量图标等图标很有用。由于这些元素是装饰性的，因此辅助技术（如屏幕阅读器）不应朗读它们。
🌐 Decorative elements can be passed into the start or end slots of the range. This is useful for adding icons such as low volume or high volume icons. Since these elements are decorative, they should not be announced by assistive technology such as screen readers.
如果文档的方向设置为从左到右，插入到 start 位置的内容将显示在范围的左侧，而插入到 end 位置的内容将显示在范围的右侧。在从右到左（rtl）的方向下，插入到 start 位置的内容将显示在范围的右侧，而插入到 end 位置的内容将显示在范围的左侧。
🌐 If the directionality of the document is set to left to right, the contents slotted to the start position will display to the left of the range, where as contents slotted to the end position will display to the right of the range. In right to left (rtl) directionality, the contents slotted to the start position will display to the right of the range, where as contents slotted to the end position will display to the left of the range.
双旋钮
🌐 Dual Knobs
双旋钮引入了两个旋钮控件，用户可以使用它们选择下限和上限的值。选定后，该范围将发出一个带有 RangeValue 的 ionChange 事件，其中包含所选的上限和下限值。
🌐 Dual knobs introduce two knob controls that users can use to select a value at a lower and upper bounds. When selected, the Range will emit an ionChange event with a RangeValue, containing the upper and lower values selected.
针脚
🌐 Pins
pin 属性将在拖动旋钮时显示范围之上的值。这允许用户在范围内选择特定的值。
🌐 The pin attribute will display the value of the Range above the knob when dragged. This allows users to select a specific value within the Range.
使用 pinFormatter 函数，开发者可以将范围值的格式自定义为用户所需的样式。
🌐 With the pinFormatter function, developers can customize the formatting of the range value to the user.
折断和滴答
🌐 Snapping & Ticks
刻度显示范围内每个可用值的指示。为了使用刻度，开发者必须将 snaps 和 ticks 属性都设置为 true。
🌐 Ticks show indications for each available value on the Range. In order to use ticks, developers must set both snaps and the ticks property to true.
启用捕捉后，范围旋钮将在拖动并释放旋钮时捕捉到最接近的可用值。
🌐 With snapping enabled, the Range knob will snap to the nearest available value as the knob is dragged and released.
事件处理
🌐 Event Handling
使用 ionChange
🌐 Using ionChange
ionChange 事件会在范围旋钮值变化时触发。
🌐 The ionChange event emits as the Range knob value changes.
ConsoleConsole messages will appear here when logged from the example above.使用 ionKnobMoveStart 和 ionKnobMoveEnd
🌐 Using ionKnobMoveStart and ionKnobMoveEnd
ionKnobMoveStart 事件在拖动范围旋钮开始时触发，无论是通过鼠标拖动、触摸手势还是键盘交互。相反，ionKnobMoveEnd 在释放范围旋钮时触发。两个事件都以 RangeValue 类型触发，并与 dualKnobs 属性结合使用。
🌐 The ionKnobMoveStart event emits when the Range knob begins dragging, whether through mouse drag, touch gesture or keyboard interaction. Inversely, ionKnobMoveEnd emits when the Range knob is released. Both events emit with the RangeValue type and work in combination with the dualKnobs property.
ConsoleConsole messages will appear here when logged from the example above.主题化
🌐 Theming
CSS 自定义属性
🌐 CSS Custom Properties
范围包括CSS 变量，可快速为 Range 组件设置主题和自定义外观，以匹配你的应用设计。
🌐 Range includes CSS Variables to quickly theme and customize the appearance of the Range component to match your application's design.
CSS 阴影部分
🌐 CSS Shadow Parts
范围包括 CSS Shadow Parts，允许对 Range 组件内的特定元素节点进行完全自定义。CSS Shadow Parts 提供了最强的自定义能力，并且在需要对 Range 组件进行高级样式设置时是推荐的方法。
🌐 Range includes CSS Shadow Parts to allow complete customization of specific element nodes within the Range component. CSS Shadow Parts offer the most customization capabilities and are the recommended approach when requiring advance styling with the Range component.
当启用 dualKnobs 时，会显示额外的阴影部分，以便每个旋钮可以独立设置样式。这些部分有两种形式：静态身份部分（A 和 B）和 动态位置部分（lower 和 upper）。A 和 B 部分始终指相同的物理旋钮，即使旋钮交叉也是如此。相反，lower 和 upper 部分反映当前的值位置，并在旋钮交叉时自动交换。这允许通过一致的身份或范围内的相对值来设置样式。
🌐 When dualKnobs is enabled, additional Shadow Parts are exposed to allow each knob to be styled independently. These are available in two forms: static identity parts (A and B) and dynamic position parts (lower and upper). The A and B parts always refer to the same physical knobs, even if the knobs cross. In contrast, the lower and upper parts reflect the current value position and automatically swap if the knobs cross. This allows styling by consistent identity or by relative value within the range.
接口
🌐 Interfaces
RangeChangeEventDetail
interface RangeChangeEventDetail {
value: RangeValue;
}
RangeKnobMoveStartEventDetail
interface RangeKnobMoveStartEventDetail {
value: RangeValue;
}
RangeKnobMoveEndEventDetail
interface RangeKnobMoveEndEventDetail {
value: RangeValue;
}
RangeCustomEvent
虽然不是必需的，但可以使用此接口替代 CustomEvent 接口，以便对从此组件发出的 Ionic 事件进行更强类型的处理。
🌐 While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.
interface RangeCustomEvent extends CustomEvent {
detail: RangeChangeEventDetail;
target: HTMLIonRangeElement;
}
类型
🌐 Types
RangeValue
type RangeValue = number | { lower: number, upper: number };
属性
🌐 Properties
activeBarStart
| Description | The start position of the range active bar. This feature is only available with a single knob (dualKnobs="false"). Valid values are greater than or equal to the min value and less than or equal to the max value. |
| Attribute | active-bar-start |
| Type | number ｜ undefined |
| Default | undefined |
color
| Description | The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming. |
| Attribute | color |
| Type | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| Default | undefined |
debounce
| Description | How long, in milliseconds, to wait to trigger the ionInput event after each change in the range value. |
| Attribute | debounce |
| Type | number ｜ undefined |
| Default | undefined |
disabled
| Description | If true, the user cannot interact with the range. |
| Attribute | disabled |
| Type | boolean |
| Default | false |
dualKnobs
| Description | Show two knobs. |
| Attribute | dual-knobs |
| Type | boolean |
| Default | false |
label
| Description | The text to display as the control's label. Use this over the label slot if you only need plain text. The label property will take priority over the label slot if both are used. |
| Attribute | label |
| Type | string ｜ undefined |
| Default | undefined |
labelPlacement
| Description | Where to place the label relative to the range. "start": The label will appear to the left of the range in LTR and to the right in RTL. "end": The label will appear to the right of the range in LTR and to the left in RTL. "fixed": The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). "stacked": The label will appear above the range regardless of the direction. |
| Attribute | label-placement |
| Type | "end" ｜ "fixed" ｜ "stacked" ｜ "start" |
| Default | 'start' |
max
| Description | Maximum integer value of the range. |
| Attribute | max |
| Type | number |
| Default | 100 |
min
| Description | Minimum integer value of the range. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render. |
| Attribute | min |
| Type | number |
| Default | 0 |
mode
| Description | The mode determines which platform styles to use. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render. |
| Attribute | mode |
| Type | "ios" ｜ "md" |
| Default | undefined |
name
| Description | The name of the control, which is submitted with the form data. |
| Attribute | name |
| Type | string |
| Default | this.rangeId |
pin
| Description | If true, a pin with integer value is shown when the knob is pressed. |
| Attribute | pin |
| Type | boolean |
| Default | false |
pinFormatter
| Description | A callback used to format the pin text. By default the pin text is set to Math.round(value).See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access this from within the callback. |
| Attribute | undefined |
| Type | (value: number) => string ｜ number |
| Default | (value: number): number => Math.round(value) |
snaps
| Description | If true, the knob snaps to tick marks evenly spaced based on the step property value. |
| Attribute | snaps |
| Type | boolean |
| Default | false |
step
| Description | Specifies the value granularity. |
| Attribute | step |
| Type | number |
| Default | 1 |
ticks
| Description | If true, tick marks are displayed based on the step value. Only applies when snaps is true. |
| Attribute | ticks |
| Type | boolean |
| Default | true |
value
| Description | the value of the range. |
| Attribute | value |
| Type | number ｜ { lower: number; upper: number; } |
| Default | 0 |
事件
🌐 Events
| Name | Description | Bubbles |
|---|---|---|
ionBlur | Emitted when the range loses focus. | true |
ionChange | The ionChange event is fired for <ion-range> elements when the user modifies the element's value: - When the user releases the knob after dragging; - When the user moves the knob with keyboard arrowsThis event will not emit when programmatically setting the value property. | true |
ionFocus | Emitted when the range has focus. | true |
ionInput | The ionInput event is fired for <ion-range> elements when the value is modified. Unlike ionChange, ionInput is fired continuously while the user is dragging the knob. | true |
ionKnobMoveEnd | Emitted when the user finishes moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction. | true |
ionKnobMoveStart | Emitted when the user starts moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction. | true |
方法
🌐 Methods
No public methods available for this component.
CSS 阴影部分
🌐 CSS Shadow Parts
| Name | Description |
|---|---|
activated | Added to the knob-handle, knob, and pin when the knob is active. Only one set has this part at a time when dualKnobs is true. |
bar | The inactive part of the bar. |
bar-active | The active part of the bar. |
focused | Added to the knob-handle, knob, and pin that currently has focus. Only one set has this part at a time when dualKnobs is true. |
hover | Added to the knob-handle, knob, and pin when the knob has hover. Only one set has this part at a time when dualKnobs is true. |
knob | The visual knob element on the range track. |
knob-a | The visual knob for the static A identity when dualKnobs is true. This identity does not change, even if the knobs cross and swap which one represents the lower or upper value. |
knob-b | The visual knob for the static B identity when dualKnobs is true. This identity does not change, even if the knobs cross and swap which one represents the lower or upper value. |
knob-handle | The container that wraps the knob and handles drag interactions. |
knob-handle-a | The container for the knob with the static A identity when dualKnobs is true. This identity does not change, even if the knobs cross and swap which one represents the lower or upper value. |
knob-handle-b | The container for the knob with the static B identity when dualKnobs is true. This identity does not change, even if the knobs cross and swap which one represents the lower or upper value. |
knob-handle-lower | The container for the knob whose current value is lower when dualKnobs is true. The lower and upper parts swap which knob handle they refer to when the knobs cross. |
knob-handle-upper | The container for the knob whose current value is upper when dualKnobs is true. The lower and upper parts swap which knob handle they refer to when the knobs cross. |
knob-lower | The visual knob whose current value is lower when dualKnobs is true. The lower and upper parts swap which knob they refer to when the knobs cross. |
knob-upper | The visual knob whose current value is upper when dualKnobs is true. The lower and upper parts swap which knob they refer to when the knobs cross. |
label | The label text describing the range. |
pin | The value indicator displayed above a knob. |
pin-a | The value indicator above the knob with the static A identity when dualKnobs is true. This identity does not change, even if the knobs cross and swap which one represents the lower or upper value. |
pin-b | The value indicator above the knob with the static B identity when dualKnobs is true. This identity does not change, even if the knobs cross and swap which one represents the lower or upper value. |
pin-lower | The value indicator above the knob whose current value is lower when dualKnobs is true. The lower and upper parts swap which pin they refer to when the knobs cross. |
pin-upper | The value indicator above the knob whose current value is upper when dualKnobs is true. The lower and upper parts swap which pin they refer to when the knobs cross. |
pressed | Added to the knob-handle, knob, and pin that is currently being pressed to drag. Only one set has this part at a time when dualKnobs is true. |
tick | An inactive tick mark. |
tick-active | An active tick mark. |
CSS 自定义属性
🌐 CSS Custom Properties
- iOS
- MD
| Name | Description |
|---|---|
--bar-background | Background of the range bar |
--bar-background-active | Background of the active range bar |
--bar-border-radius | Border radius of the range bar |
--bar-height | Height of the range bar |
--height | Height of the range |
--knob-background | Background of the range knob |
--knob-border-radius | Border radius of the range knob |
--knob-box-shadow | Box shadow of the range knob |
--knob-size | Size of the range knob |
--pin-background | Background of the range pin (only available in MD mode) |
--pin-color | Color of the range pin (only available in MD mode) |
| Name | Description |
|---|---|
--bar-background | Background of the range bar |
--bar-background-active | Background of the active range bar |
--bar-border-radius | Border radius of the range bar |
--bar-height | Height of the range bar |
--height | Height of the range |
--knob-background | Background of the range knob |
--knob-border-radius | Border radius of the range knob |
--knob-box-shadow | Box shadow of the range knob |
--knob-size | Size of the range knob |
--pin-background | Background of the range pin (only available in MD mode) |
--pin-color | Color of the range pin (only available in MD mode) |
插槽
🌐 Slots
| Name | Description |
|---|---|
end | Content is placed to the right of the range slider in LTR, and to the left in RTL. |
label | The label text to associate with the range. Use the "labelPlacement" property to control where the label is placed relative to the range. |
start | Content is placed to the left of the range slider in LTR, and to the right in RTL. |