跳到主要内容
版本：v7

ion-range

shadow

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

默认情况下，范围滑块的最小值为 0，最大值为 100。这可以通过 min 和 max 属性进行配置。

标签​

标签应用于描述范围。它们可以在视觉上使用，当用户聚焦范围时，屏幕阅读器也会将其读出。这使用户能够轻松理解范围的用途。范围有几种分配标签的方式：

  • label 属性：用于纯文本标签
  • label 插槽：用于自定义 HTML 标签
  • aria-label：用于为屏幕阅读器提供标签，但不添加可见标签

标签位置​

下面的演示展示了如何使用 labelPlacement 属性更改标签相对于范围的位置。虽然这里使用了 label 属性，但 labelPlacement 也可以与 label 插槽一起使用。

标签插槽​

虽然纯文本标签应通过 label 属性传递，但如果需要自定义 HTML，可以通过 label 插槽传递。

无可见标签​

如果不需要可见标签，开发者仍应提供 aria-label，以便屏幕阅读器可以访问范围。

装饰​

装饰元素可以传递到范围的 start 或 end 插槽中。这对于添加图标（如低音量或高音量图标）非常有用。由于这些元素是装饰性的，因此不应由屏幕阅读器等辅助技术宣读。

如果文档的方向设置为从左到右，则放置在 start 插槽的内容将显示在范围的左侧，而放置在 end 插槽的内容将显示在范围的右侧。在从右到左（rtl）方向上，放置在 start 插槽的内容将显示在范围的右侧，而放置在 end 插槽的内容将显示在范围的左侧。

双旋钮​

双旋钮引入两个旋钮控件，用户可以使用它们在下限和上限选择一个值。选中时，范围将发出一个带有 RangeValue 的 ionChange 事件，包含选中的上限和下限值。

固定值显示​

pin 属性将在拖动时在旋钮上方显示范围的值。这允许用户选择范围内的特定值。

使用 pinFormatter 函数，开发者可以自定义范围值的格式化方式。

吸附和刻度​

刻度显示范围内每个可用值的指示。为了使用刻度，开发者必须将 snaps 和 ticks 属性都设置为 true。

启用吸附后，范围旋钮在拖动和释放时将吸附到最近的可用值。

事件处理​

使用 ionChange​

ionChange 事件在范围旋钮值变化时发出。

控制台
控制台消息将在上方示例中调用 console.log 时显示在此处。

使用 ionKnobMoveStart 和 ionKnobMoveEnd​

ionKnobMoveStart 事件在范围旋钮开始拖动时发出，无论是通过鼠标拖动、触摸手势还是键盘交互。相反，ionKnobMoveEnd 在范围旋钮释放时发出。两个事件都以 RangeValue 类型发出，并与 dualKnobs 属性配合使用。

控制台
控制台消息将在上方示例中调用 console.log 时显示在此处。

主题​

CSS 自定义属性​

Range 包含 CSS 变量，可快速主题化和自定义 Range 组件的外观，以匹配你的应用设计。

CSS 阴影部分​

Range 包含 CSS 阴影部分，允许完全自定义 Range 组件内的特定元素节点。CSS 阴影部分提供最大的自定义能力，是需要在 Range 组件中进行高级样式设置时的推荐方法。

从旧版范围语法迁移​

Ionic 7.0 引入了更简单的范围语法。这种新语法减少了设置范围所需的样板代码，解决了无障碍访问问题，并改善了开发者体验。

开发者可以逐个迁移每个范围。虽然开发者可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法​

使用现代语法需要移除 ion-label 并使用 label 属性将标签传递给 ion-range。标签的位置可以使用 labelPlacement 属性进行配置。

如果需要为标签使用自定义 HTML，可以通过 label 插槽直接传递到 ion-range 内部。

<!-- 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-item 是 ion-range 正常运行所必需的。从 Ionic 7.0 开始，仅当项目放置在 ion-list 中时，才应在 ion-item 中使用 ion-range。此外，ion-range 的正常运行不再需要 ion-item。

使用旧版语法​

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

接口​

RangeChangeEventDetail​

interface RangeChangeEventDetail {
  value: RangeValue;
}

RangeKnobMoveStartEventDetail​

interface RangeKnobMoveStartEventDetail {
  value: RangeValue;
}

RangeKnobMoveEndEventDetail​

interface RangeKnobMoveEndEventDetail {
  value: RangeValue;
}

RangeCustomEvent​

虽然不是必需的，但此接口可以替代 CustomEvent 接口，为此组件发出的 Ionic 事件提供更强的类型支持。

interface RangeCustomEvent extends CustomEvent {
  detail: RangeChangeEventDetail;
  target: HTMLIonRangeElement;
}

类型​

RangeValue​

type RangeValue = number | { lower: number; upper: number };

属性​

activeBarStart​

说明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.
属性active-bar-start
类型number ｜ undefined
默认值undefined

color​

说明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.
属性color
类型"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认值undefined

debounce​

说明How long, in milliseconds, to wait to trigger the ionInput event after each change in the range value.
属性debounce
类型number ｜ undefined
默认值undefined

disabled​

说明If true, the user cannot interact with the range.
属性disabled
类型boolean
默认值false

dualKnobs​

说明Show two knobs.
属性dual-knobs
类型boolean
默认值false

label​

说明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.
属性label
类型string ｜ undefined
默认值undefined

labelPlacement​

说明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.
属性label-placement
类型"end" ｜ "fixed" ｜ "stacked" ｜ "start"
默认值'start'

legacy​

说明Set the legacy property to true to forcibly use the legacy form control markup. Ionic will only opt components in to the modern form markup when they are using either the aria-label attribute or the label property. As a result, the legacy property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior. Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
属性legacy
类型boolean ｜ undefined
默认值undefined

max​

说明Maximum integer value of the range.
属性max
类型number
默认值100

min​

说明Minimum integer value of the range.

这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性min
类型number
默认值0

mode​

说明The mode determines which platform styles to use.

这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性mode
类型"ios" ｜ "md"
默认值undefined

name​

说明The name of the control, which is submitted with the form data.
属性name
类型string
默认值this.rangeId

pin​

说明If true, a pin with integer value is shown when the knob is pressed.
属性pin
类型boolean
默认值false

pinFormatter​

说明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.
属性undefined
类型(value: number) => string ｜ number
默认值(value: number): number => Math.round(value)

snaps​

说明If true, the knob snaps to tick marks evenly spaced based on the step property value.
属性snaps
类型boolean
默认值false

step​

说明Specifies the value granularity.
属性step
类型number
默认值1

ticks​

说明If true, tick marks are displayed based on the step value. Only applies when snaps is true.
属性ticks
类型boolean
默认值true

value​

说明the value of the range.
属性value
类型number ｜ { lower: number; upper: number; }
默认值0

事件​

Name说明冒泡
ionBlurEmitted when the range loses focus.true
ionChangeThe 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

ionChange is not fired when the value is changed programmatically.		true
ionFocusEmitted when the range has focus.true
ionInputThe 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
ionKnobMoveEndEmitted when the user finishes moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction.true
ionKnobMoveStartEmitted when the user starts moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction.true

方法​

该组件没有可用的公共方法。

CSS 阴影部分​

Name说明
barThe inactive part of the bar.
bar-activeThe active part of the bar.
knobThe handle that is used to drag the range.
labelThe label text describing the range.
pinThe counter that appears above a knob.
tickAn inactive tick mark.
tick-activeAn active tick mark.

CSS 自定义属性​

Name说明
--bar-backgroundBackground of the range bar
--bar-background-activeBackground of the active range bar
--bar-border-radiusBorder radius of the range bar
--bar-heightHeight of the range bar
--heightHeight of the range
--knob-backgroundBackground of the range knob
--knob-border-radiusBorder radius of the range knob
--knob-box-shadowBox shadow of the range knob
--knob-sizeSize of the range knob
--pin-backgroundBackground of the range pin (only available in MD mode)
--pin-colorColor of the range pin (only available in MD mode)

插槽​

Name说明
endContent is placed to the right of the range slider in LTR, and to the left in RTL.
labelThe label text to associate with the range. Use the "labelPlacement" property to control where the label is placed relative to the range.
startContent is placed to the left of the range slider in LTR, and to the right in RTL.

目录

编辑此页