跳至主要内容
版本: v8

ion-range

阴影

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

默认情况下，范围滑块的最小值为 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 事件在范围旋钮值更改时发出。

控制台
从上面的示例中记录的控制台消息将显示在此处。

使用 ionKnobMoveStart 和 ionKnobMoveEnd​

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

控制台
从上面的示例中记录的控制台消息将显示在此处。

主题​

CSS 自定义属性​

范围包含 CSS 变量，以便快速地对范围组件的外观进行主题化和自定义，以匹配应用程序的设计。

CSS 阴影部分​

范围包含 CSS 阴影部分，以允许完全自定义范围组件中的特定元素节点。CSS 阴影部分提供了最强大的自定义功能，并且是在需要对范围组件进行高级样式化时推荐的方法。

从旧版范围语法迁移​

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

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

使用现代语法​

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

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

<!-- 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-range 应该只在将项目放入 ion-list 时才在 ion-item 中使用。此外，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​

描述范围活动栏的起始位置。此功能仅适用于单个旋钮 (dualKnobs="false")。有效值大于或等于最小值，小于或等于最大值。
属性active-bar-start
类型number ｜ undefined
默认undefined

color​

描述要从应用程序的颜色调色板中使用的颜色。默认选项是："primary"、"secondary"、"tertiary"、"success"、"warning"、"danger"、"light"、"medium" 和 "dark"。有关颜色的更多信息，请参阅 主题。
属性color
类型"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认undefined

debounce​

描述每次范围值发生变化后等待多长时间（以毫秒为单位），才能触发 ionInput 事件。
属性debounce
类型number ｜ undefined
默认undefined

disabled​

描述如果为 true，则用户无法与范围交互。
属性disabled
类型boolean
默认false

dualKnobs​

描述显示两个旋钮。
属性dual-knobs
类型boolean
默认false

label​

描述要显示为控件标签的文本。如果您只需要纯文本，请使用 label 槽。如果同时使用 label 属性和 label 槽，则 label 属性优先级更高。
属性label
类型string ｜ undefined
默认undefined

labelPlacement​

描述将标签相对于范围放置的位置。"start"：标签将在 LTR 中的范围左侧显示，在 RTL 中的右侧显示。"end"：标签将在 LTR 中的范围右侧显示，在 RTL 中的左侧显示。"fixed"：标签的行为与 "start" 相同，只是它还具有固定宽度。长文本将使用省略号 ("...") 缩短。"stacked"：标签将始终显示在范围上方，与方向无关。
属性label-placement
类型"end" ｜ "fixed" ｜ "stacked" ｜ "start"
默认'start'

max​

描述范围的最大整数值。
属性max
类型number
默认100

min​

描述范围的最小整数值。
属性min
类型number
默认0

mode​

描述模式决定使用哪个平台样式。
属性mode
类型"ios" ｜ "md"
默认undefined

name​

描述控件的名称，它将与表单数据一起提交。
属性name
类型string
默认this.rangeId

pin​

描述如果为 true，则在按下旋钮时会显示一个带有整数值的别针。
属性pin
类型boolean
默认false

pinFormatter​

描述用于格式化别针文本的回调。默认情况下，别针文本设置为 Math.round(value)。

如果您需要从回调中访问 this，请参阅 https://ionic.js.cn/docs/troubleshooting/runtime#accessing-this。
属性undefined
类型(value: number) => string ｜ number
默认(value: number): number => Math.round(value)

snaps​

描述如果为 true，则旋钮会根据步骤属性值均匀间隔的刻度标记捕捉。
属性snaps
类型boolean
默认false

step​

描述指定值粒度。
属性step
类型number
默认1

ticks​

描述如果为 true，则会根据步骤值显示刻度标记。仅在 snaps 为 true 时适用。
属性ticks
类型boolean
默认true

value​

描述范围的值。
属性value
类型number ｜ { lower: number; upper: number; }
默认0

事件​

名称描述冒泡
ionBlur当范围失去焦点时发出。true
ionChange当用户修改元素的值时，会为 <ion-range> 元素触发 ionChange 事件：- 当用户在拖动后释放旋钮时；- 当用户使用键盘箭头移动旋钮时

如果以编程方式设置 value 属性，则此事件不会发出。		true
ionFocus当范围获得焦点时发出。true
ionInput当值修改时，会为 <ion-range> 元素触发 ionInput 事件。与 ionChange 不同，ionInput 在用户拖动旋钮时会持续触发。true
ionKnobMoveEnd当用户完成移动范围旋钮时发出，无论是通过鼠标拖动、触摸手势还是键盘交互。true
ionKnobMoveStart当用户开始移动范围旋钮时发出，无论是通过鼠标拖动、触摸手势还是键盘交互。true

方法​

此组件没有公开方法可用。

CSS 阴影部分​

名称描述
bar栏的非活动部分。
bar-active栏的活动部分。
knob用于拖动范围的句柄。
label描述范围的标签文本。
pin显示在旋钮上方的计数器。
tick非活动刻度标记。
tick-active活动刻度标记。

CSS 自定义属性​

名称描述
--bar-background范围栏的背景
--bar-background-active活动范围栏的背景
--bar-border-radius范围栏的边框半径
--bar-height范围栏的高度
--height范围的高度
--knob-background范围旋钮的背景
--knob-border-radius范围旋钮的边框半径
--knob-box-shadow范围旋钮的盒阴影
--knob-size范围旋钮的大小
--pin-background范围别针的背景（仅在 MD 模式下可用）
--pin-color范围别针的颜色（仅在 MD 模式下可用）

插槽​

名称描述
end内容将放置在 LTR 中的范围滑块右侧，在 RTL 中的左侧。
label与范围关联的标签文本。使用 "labelPlacement" 属性控制标签相对于范围的放置位置。
start内容将放置在 LTR 中的范围滑块左侧，在 RTL 中的右侧。

内容

编辑此页面