ion-range

shadow

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

默认情况下，范围滑块的最小值为 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 位置的内容将显示在范围滑块的左侧。

双旋钮

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

数值提示

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

通过 pinFormatter 函数，开发者可以自定义范围滑块值的显示格式。

吸附与刻度

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

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

事件处理

使用 ionChange

ionChange 事件在范围滑块旋钮值更改时发出。

Console

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

使用 ionKnobMoveStart 和 ionKnobMoveEnd

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

Console

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

主题定制

CSS 自定义属性

范围滑块包含 CSS 变量，用于快速主题化和自定义范围滑块组件的外观，以匹配您的应用程序设计。

CSS Shadow Parts

范围滑块包含 CSS Shadow Parts，以允许完全自定义范围滑块组件内的特定元素节点。CSS Shadow Parts 提供了最多的自定义功能，是需要对范围滑块组件进行高级样式设置时的推荐方法。

从旧版范围滑块语法迁移

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

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

使用现代语法

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

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

JavaScript

<!-- 基础用法 -->

<!-- 之前 -->
<ion-item>
  <ion-label>通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label="通知"></ion-range>
</ion-item>

<!-- 固定标签 -->

<!-- 之前 -->
<ion-item>
  <ion-label position="fixed">通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label-placement="fixed" label="通知"></ion-range>
</ion-item>

<!-- 范围在行首，标签在行尾 -->

<!-- 之前 -->
<ion-item>
  <ion-label slot="end">通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label-placement="end" label="通知"></ion-range>
</ion-item>

<!-- 自定义 HTML 标签 -->

<!-- 之前 -->
<ion-item>
  <ion-label>
    <div class="custom-label">通知</div>
  </ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range>
    <div slot="label" class="custom-label">通知</div>
  </ion-range>
</ion-item>

Angular

<!-- 基础用法 -->

<!-- 之前 -->
<ion-item>
  <ion-label>通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label="通知"></ion-range>
</ion-item>

<!-- 固定标签 -->

<!-- 之前 -->
<ion-item>
  <ion-label position="fixed">通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range labelPlacement="fixed" label="通知"></ion-range>
</ion-item>

<!-- 范围在行首，标签在行尾 -->

<!-- 之前 -->
<ion-item>
  <ion-label slot="end">通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range labelPlacement="end" label="通知"></ion-range>
</ion-item>

<!-- 自定义 HTML 标签 -->

<!-- 之前 -->
<ion-item>
  <ion-label>
    <div class="custom-label">通知</div>
  </ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range>
    <div slot="label" class="custom-label">通知</div>
  </ion-range>
</ion-item>

React

{/* 基础用法 */}

{/* 之前 */}
<IonItem>
  <IonLabel>通知</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* 之后 */}
<IonItem>
  <IonRange label="通知"></IonRange>
</IonItem>

{/* 固定标签 */}

{/* 之前 */}
<IonItem>
  <IonLabel position="fixed">通知</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* 之后 */}
<IonItem>
  <IonRange labelPlacement="fixed" label="通知"></IonRange>
</IonItem>

{/* 范围在行首，标签在行尾 */}

{/* 之前 */}
<IonItem>
  <IonLabel slot="end">通知</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* 之后 */}
<IonItem>
  <IonRange labelPlacement="end" label="通知"></IonRange>
</IonItem>

{/* 自定义 HTML 标签 */}

{/* 之前 */}
<IonItem>
  <IonLabel>
    <div className="custom-label">通知</div>
  </IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* 之后 */}
<IonItem>
  <IonRange>
    <div slot="label" className="custom-label">通知</div>
  </IonRange>
</IonItem>

Vue

<!-- 基础用法 -->

<!-- 之前 -->
<ion-item>
  <ion-label>通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label="通知"></ion-range>
</ion-item>

<!-- 固定标签 -->

<!-- 之前 -->
<ion-item>
  <ion-label position="fixed">通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label-placement="fixed" label="通知"></ion-range>
</ion-item>

<!-- 范围在行首，标签在行尾 -->

<!-- 之前 -->
<ion-item>
  <ion-label slot="end">通知</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range label-placement="end" label="通知"></ion-range>
</ion-item>

<!-- 自定义 HTML 标签 -->

<!-- 之前 -->
<ion-item>
  <ion-label>
    <div class="custom-label">通知</div>
  </ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-range>
    <div slot="label" class="custom-label">通知</div>
  </ion-range>
</ion-item>

备注

在 Ionic 的早期版本中，ion-range 需要 ion-item 才能正常工作。从 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

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'

legacy

Description	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.
Attribute	legacy
Type	boolean ｜ undefined
Default	undefined

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

事件

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 ionChange is not fired when the value is changed programmatically.	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

方法

No public methods available for this component.

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 自定义属性

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