ion-range

shadow

范围滑块允许用户通过移动滑块旋钮从一系列值中进行选择。默认情况下，一个旋钮控制范围值。可以使用双旋钮自定义此行为。

¥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.

label 属性：用于纯文本标签

¥label property: used for plaintext labels
label 插槽：用于自定义 HTML 标签

¥label slot: used for custom HTML labels
aria-label：用于为屏幕阅读器提供标签，但不添加可见标签

¥aria-label: used to provide a label for screen readers but adds no visible 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

双旋钮引入了两个旋钮控件，用户可以使用它们来选择下限和上限的值。选择后，范围将发出 ionChange 事件和 RangeValue，其中包含所选的上限和下限值。

¥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.

Console

Console 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.

Console

Console messages will appear here when logged from the example above.

主题化

¥Theming

CSS 自定义属性

¥CSS Custom Properties

Range 包括 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

Range 包括 CSS 阴影部分，以允许完全自定义 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.

从旧范围语法迁移

¥Migrating from Legacy Range Syntax

Ionic 7.0 中引入了更简单的范围语法。这种新语法减少了设置范围所需的样板文件，解决了可访问性问题，并改善了开发者体验。

¥A simpler range syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an range, resolves accessibility issues, and improves the developer experience.

开发者可以一次在一个范围内执行此迁移。虽然开发者可以继续使用旧语法，但我们建议尽快迁移。

¥Developers can perform this migration one range at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

使用现代语法

¥Using the Modern Syntax

使用现代语法涉及删除 ion-label 并使用 label 属性将标签传递给 ion-range。可以使用 labelPlacement 属性配置标签的位置。

¥Using the modern syntax involves removing the ion-label and passing the label to ion-range using the label property. The placement of the label can be configured using the labelPlacement property.

如果标签需要自定义 HTML，则可以使用 label 槽直接在 ion-range 内部传递。

¥If custom HTML is needed for the label, it can be passed directly inside the ion-range using the label slot instead.

JavaScript
Angular
React
Vue

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label="Notifications"></ion-range>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="fixed" label="Notifications"></ion-range>
</ion-item>

<!-- Range at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="end" label="Notifications"></ion-range>
</ion-item>

<!-- Custom HTML label -->

<!-- Before -->
<ion-item>
  <ion-label>
    <div class="custom-label">Notifications</div>
  </ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range>
    <div slot="label" class="custom-label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label="Notifications"></ion-range>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range labelPlacement="fixed" label="Notifications"></ion-range>
</ion-item>

<!-- Range at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range labelPlacement="end" label="Notifications"></ion-range>
</ion-item>

<!-- Custom HTML label -->

<!-- Before -->
<ion-item>
  <ion-label>
    <div class="custom-label">Notifications</div>
  </ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range>
    <div slot="label" class="custom-label">Notifications</div>
  </ion-range>
</ion-item>

{/* Basic */}

{/* Before */}
<IonItem>
  <IonLabel>Notifications</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* After */}
<IonItem>
  <IonRange label="Notifications"></IonRange>
</IonItem>

{/* Fixed Labels */}

{/* Before */}
<IonItem>
  <IonLabel position="fixed">Notifications</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* After */}
<IonItem>
  <IonRange labelPlacement="fixed" label="Notifications"></IonRange>
</IonItem>

{/* Range at the start of line, Label at the end of line */}

{/* Before */}
<IonItem>
  <IonLabel slot="end">Notifications</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* After */}
<IonItem>
  <IonRange labelPlacement="end" label="Notifications"></IonRange>
</IonItem>

{/* Custom HTML label */}

{/* Before */}
<IonItem>
  <IonLabel>
    <div className="custom-label">Notifications</div>
  </IonLabel>
  <IonRange></IonRange>
</IonItem>

<!-- After -->
<IonItem>
  <IonRange>
    <div slot="label" className="custom-label">Notifications</div>
  </IonRange>
</IonItem>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label="Notifications"></ion-range>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="fixed" label="Notifications"></ion-range>
</ion-item>

<!-- Range at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="end" label="Notifications"></ion-range>
</ion-item>

<!-- Custom HTML label -->

<!-- Before -->
<ion-item>
  <ion-label>
    <div class="custom-label">Notifications</div>
  </ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range>
    <div slot="label" class="custom-label">Notifications</div>
  </ion-range>
</ion-item>

注意

在 Ionic 的过去版本中，ion-range 需要 ion-item 才能正常运行。从 Ionic 7.0 开始，当项目放置在 ion-list 中时，ion-range 只能在 ion-item 中使用。此外，ion-range 正常运行不再需要 ion-item。

¥In past versions of Ionic, ion-item was required for ion-range to function properly. Starting in Ionic 7.0, ion-range should only be used in an ion-item when the item is placed in an ion-list. Additionally, ion-item is no longer required for ion-range to function properly.

使用旧语法

¥Using the Legacy Syntax

Ionic 使用启发式方法来检测应用是否使用现代范围语法。在某些情况下，最好继续使用旧语法。开发者可以将 ion-range 上的 legacy 属性设置为 true，以强制该范围的实例使用旧语法。

¥Ionic uses heuristics to detect if an app is using the modern range syntax. In some instances, it may be preferable to continue using the legacy syntax. Developers can set the legacy property on ion-range to true to force that instance of the range to use the legacy syntax.

接口

¥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.
Attribute	`min`
Type	`number`
Default	`0`

mode

Description	The mode determines which platform styles to use.
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`

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 arrows This 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
`bar`	The inactive part of the bar.
`bar-active`	The active part of the bar.
`knob`	The handle that is used to drag the range.
`label`	The label text describing the range.
`pin`	The counter that appears above a knob.
`tick`	An inactive tick mark.
`tick-active`	An active tick mark.

CSS 自定义属性

¥CSS Custom Properties

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.

标签​

标签放置​

标签槽​

无可见标签​

装饰​

双旋钮​

针脚​

折断和滴答​

事件处理​

使用 ionChange​

使用 ionKnobMoveStart 和 ionKnobMoveEnd​

主题化​

CSS 自定义属性​

CSS 阴影部分​

从旧范围语法迁移​

使用现代语法​

使用旧语法​

接口​

RangeChangeEventDetail​

RangeKnobMoveStartEventDetail​

RangeKnobMoveEndEventDetail​

RangeCustomEvent​

类型​

RangeValue​

属性​

activeBarStart​

color​

debounce​

disabled​

dualKnobs​

label​

labelPlacement​

max​

min​

mode​

name​

pin​

pinFormatter​

snaps​

step​

ticks​

value​

事件​

方法​

CSS 阴影部分​

CSS 自定义属性​

插槽​

目录

标签

标签放置

标签槽

无可见标签

装饰

双旋钮

针脚

折断和滴答

事件处理

使用 `ionChange`

使用 `ionKnobMoveStart` 和 `ionKnobMoveEnd`

主题化

CSS 自定义属性

CSS 阴影部分

从旧范围语法迁移

使用现代语法

使用旧语法

接口

RangeChangeEventDetail

RangeKnobMoveStartEventDetail

RangeKnobMoveEndEventDetail

RangeCustomEvent

类型

RangeValue

属性

activeBarStart

color

debounce

disabled

dualKnobs

label

labelPlacement

max

min

mode

name

pin

pinFormatter

snaps

step

ticks

value

事件

方法

CSS 阴影部分

CSS 自定义属性

插槽