Version: v8

ion-range

Rangeスライダは、スライダノブを動かして、ユーザーが値の範囲を選択できるようにするものです。デフォルトでは、1つのノブがレンジの値を制御します。この動作は dual knobs を使ってカスタマイズすることができます。

デフォルトでは、Rangeスライダーの最小値は0、最大値は100です。これは min と max プロパティで設定することができます。

Labels

ラベルは、範囲を説明するために使用されるべきです。それらは視覚的に使用することができ、また、ユーザーがRangeをフォーカスしてるときに、スクリーンリーダーによって読み上げられます。これにより、ユーザーは範囲の意図を理解しやすくなります。範囲にはラベルを割り当てるいくつかの方法があります：

labelプロパティ：プレーンテキストのラベルに使用する。
labelスロット：カスタム HTML ラベルに使用する。
aria-label: スクリーンリーダー用のラベルとして使用されるが、ラベルは表示されない。

Label Placement

以下のデモでは、labelPlacement プロパティを使用して、範囲に対するラベルの位置を変更しています。ここでは label プロパティを使用しているが、labelPlacement は label スロットでも使用できます。

Label Slot

プレーンテキストのラベルは label プロパティで渡すべきであるが、カスタムHTMLが必要な場合は、代わりに label スロットで渡すことができます。

No Visible Label

もし表示するラベルが必要ない場合でも、開発者はaria-labelを与えるべきです。

Decorations

装飾的な要素は、範囲の start または end スロットに渡すことができます。これは、音量の小さいアイコンや大きいアイコンのようなアイコンを追加するのに便利です。これらの要素は装飾的なものなので、スクリーンリーダーのような支援技術によってアナウンスされるべきではありません。

ドキュメントの方向性が左から右に設定されている場合、start位置にスロットされたコンテンツは範囲の左に表示され、end位置にスロットされたコンテンツは範囲の右に表示されます。右から左(rtl)の方向性の場合、start位置にスロットされたコンテンツは範囲の右側に表示され、end位置にスロットされたコンテンツは範囲の左側に表示されます。

Dual Knobs

Dual knobs はユーザーが下限と上限の値を選択するために使用できる2つのknobsコントロールを導入しています。選択されると、Range は選択された上下限の値を含む RangeValue を持つ ionChange イベントを発信します。

ピン

pin 属性は、ドラッグしたときにノブの上にレンジの値を表示します。これにより、ユーザはRange内の特定の値を選択することができます。

pinFormatter 関数を使用すると、開発者はユーザーに対してレンジの値のフォーマットをカスタマイズすることができます。

Snapping & Ticks

TicksはRange 上で利用可能な各値のインジケータを表示します。Ticksを使用するためには、開発者は snaps と ticks プロパティの両方を true に設定する必要があります。

snapsを有効にし、knobをドラッグして放すと、Range knobは最も近い利用可能な値にスナップします。

イベントハンドリング

Using `ionChange`

ionChange イベントはRange knobの値の変更を監視します。

Console

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

`ionKnobMoveStart` と `ionKnobMoveEnd` を使う

マウスドラッグ、タッチジェスチャー、キーボード操作のいずれであっても、Range knobのドラッグが開始されると ionKnobMoveStart イベントが発行されます。逆に、ionKnobMoveEndはRange knobがリリースされたときに発生します。両イベントは RangeValue タイプで発生し、dualKnobs プロパティと組み合わせて動作します。

Console

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

テーマ

CSSカスタムプロパティ

Rangeには、アプリケーションのデザインに合わせてRangeコンポーネントの外観を素早くテーマ化してカスタマイズするためのCSS Variablesが含まれています。

CSS Shadow Parts

Rangeには CSS Shadow Parts があり、Rangeコンポーネント内の特定の要素ノードを完全にカスタマイズすることができます。CSS Shadow Partsは最も多くのカスタマイズ機能を提供し、Rangeコンポーネントで高度なスタイリングが必要な場合に推奨されるアプローチです。

レガシーな範囲構文からの移行

Ionic 7.0では、よりシンプルな範囲構文が導入されました。この新しい構文は、範囲を設定するために必要な定型文を減らし、アクセシビリティの問題を解決し、開発者のエクスペリエンスを向上させます。

開発者はこの移行を範囲ごとに実行できます。開発者は従来の構文を使い続けることもできますが、できるだけ早く移行することをお勧めします。

最新の構文の使い方

最新の構文を使用するには、ion-label を削除し、label プロパティを使用して ion-range にラベルを渡します。ラベルの配置は labelPlacement プロパティを使用して設定することができます。

ラベルにカスタム HTML が必要な場合は、代わりに label スロットを使用して ion-range 内に直接渡すことができる。

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>

note

Ionic の過去のバージョンでは、ion-range が正しく機能するためには ion-item が必要でした。Ionic 7.0 以降では、ion-range は ion-item 内でアイテムを ion-list に配置する場合にのみ使用します。また、ion-range が正しく機能するためには、ion-item は不要になりました。

レガシー構文の使用

Ionicは、アプリが最新の範囲構文を使用しているかどうかをヒューリスティックで検出します。場合によっては、レガシー構文を使い続けた方が望ましいこともあります。開発者は ion-range の legacy プロパティを true に設定することで、そのインスタンスにレガシー構文を使用させることができます。

Interfaces

RangeChangeEventDetail

interface RangeChangeEventDetail {
  value: RangeValue;
}

RangeKnobMoveStartEventDetail

interface RangeKnobMoveStartEventDetail {
  value: RangeValue;
}

RangeKnobMoveEndEventDetail

interface RangeKnobMoveEndEventDetail {
  value: RangeValue;
}

RangeCustomEvent

必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。

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

Types

RangeValue

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

プロパティ

activeBarStart

Description	レンジアクティブバーの開始位置です。この機能は、ノブが1つの場合のみ有効です（dualKnobs="false"）。有効な値は、min値以上、max値以下です。
Attribute	`active-bar-start`
Type	`number ｜ undefined`
Default	`undefined`

color

Description	アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, と `"dark"` です．色に関する詳しい情報は theming を参照してください。
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
Default	`undefined`

debounce

Description	レンジの値が変化するたびに `ionInput` イベントをトリガーするまでの待ち時間（ミリ秒単位）。
Attribute	`debounce`
Type	`number ｜ undefined`
Default	`undefined`

disabled

Description	`true`の場合、ユーザは範囲と対話することができません。
Attribute	`disabled`
Type	`boolean`
Default	`false`

dualKnobs

Description	2つのノブを表示します。
Attribute	`dual-knobs`
Type	`boolean`
Default	`false`

label

Description	コントロールのラベルとして表示するテキスト。プレーンテキストのみが必要な場合は `label` スロットよりもこちらを使用する。両方を使用する場合は、`label` プロパティが `label` スロットよりも優先される。
Attribute	`label`
Type	`string ｜ undefined`
Default	`undefined`

labelPlacement

Description	範囲に対するラベルの位置。start"`：ラベルはLTRでは範囲の左側、RTLでは右側に表示される。end"`：ラベルはLTRでは範囲の右側、RTLでは左側に表示される。fixed"`：ラベルの幅が固定される以外は` "start" `と同じ動作をします。長いテキストは省略記号("...")で切り捨てられます。積み上げ"`：ラベルは方向に関係なく範囲の上に表示されます。
Attribute	`label-placement`
Type	`"end" ｜ "fixed" ｜ "stacked" ｜ "start"`
Default	`'start'`

max

Description	範囲の最大整数値。
Attribute	`max`
Type	`number`
Default	`100`

min

Description	範囲の最小の整数値。
Attribute	`min`
Type	`number`
Default	`0`

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

name

Description	フォームデータとともに送信されるコントロールの名前。
Attribute	`name`
Type	`string`
Default	`this.rangeId`

Description	`true`の場合、ノブを押したときに整数値のピンが表示されます。
Attribute	`pin`
Type	`boolean`
Default	`false`

pinFormatter

Description	ピンのテキストをフォーマットするためのコールバック。デフォルトでは、ピンのテキストは `Math.round(value)` に設定されます。コールバック内から `this` にアクセスする必要がある場合は https://ionicframework.com/docs/troubleshooting/runtime#accessing-this を参照してください。
Attribute	`undefined`
Type	`(value: number) => string ｜ number`
Default	`(value: number): number => Math.round(value)`

snaps

Description	`true`の場合、ノブはステッププロパティの値に基づいて等間隔に配置されたティックマークにスナップします。
Attribute	`snaps`
Type	`boolean`
Default	`false`

step

Description	値の粒度を指定します。
Attribute	`step`
Type	`number`
Default	`1`

ticks

Description	`true`の場合、ステップの値に基づいてティックマークを表示します。snaps`が` true` の場合のみ適用される。
Attribute	`ticks`
Type	`boolean`
Default	`true`

value

Description	範囲の値です。
Attribute	`value`
Type	`number ｜ { lower: number; upper: number; }`
Default	`0`

イベント

Name	Description	Bubbles
`ionBlur`	レンジの焦点が合わなくなったときに発行されます。	`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`	レンジのフォーカスが合ったときに発行されます。	`true`
`ionInput`	`ionInput`イベントは、`<ion-range>`要素に対して、値が変更されたときに発生するイベントです。`ionChange`とは異なり、`ionInput`はユーザがノブをドラッグしている間、継続して発生します。	`true`
`ionKnobMoveEnd`	マウスドラッグ、タッチジェスチャー、キーボード操作など、ユーザーが範囲ノブの移動を終了したときに発行されます。	`true`
`ionKnobMoveStart`	マウスドラッグ、タッチジェスチャー、キーボード操作など、ユーザーがレンジノブの移動を開始したときに発行されます。	`true`

メソッド

No public methods available for this component.

CSS Shadow Parts

Name	Description
`bar`	バーの非アクティブな部分。
`bar-active`	バーのアクティブな部分です。
`knob`	範囲をドラッグする際に使用するハンドル。
`label`	範囲を表すラベルテキスト。
`pin`	ノブの上に表示されるカウンターです。
`tick`	非アクティブなティックマークです。
`tick-active`	アクティブなティックマークです。

CSSカスタムプロパティ

Name	Description
`--bar-background`	レンジバーの背景
`--bar-background-active`	アクティブレンジバーの背景
`--bar-border-radius`	レンジバーのボーダー半径
`--bar-height`	レンジバーの高さ
`--height`	レンジの高さ
`--knob-background`	レンジノブの背景
`--knob-border-radius`	レンジツマミのボーダー半径
`--knob-box-shadow`	レンジノブのボックスシャドウ
`--knob-size`	レンジツマミの大きさ
`--pin-background`	レンジピンの背景（MD mode時のみ有効）
`--pin-color`	レンジピンの色（MD mode時のみ有効）

Name	Description
`--bar-background`	レンジバーの背景
`--bar-background-active`	アクティブレンジバーの背景
`--bar-border-radius`	レンジバーのボーダー半径
`--bar-height`	レンジバーの高さ
`--height`	レンジの高さ
`--knob-background`	レンジノブの背景
`--knob-border-radius`	レンジツマミのボーダー半径
`--knob-box-shadow`	レンジノブのボックスシャドウ
`--knob-size`	レンジツマミの大きさ
`--pin-background`	レンジピンの背景（MD mode時のみ有効）
`--pin-color`	レンジピンの色（MD mode時のみ有効）

Slots

Name	Description
`end`	コンテンツは、LTRでは範囲スライダーの右側に、RTLでは左側に配置されます。
`label`	範囲に関連付けるラベルテキスト。`"labelPlacement`"プロパティを使用して、ラベルが範囲に対してどの位置に配置されるかを制御します。
`start`	コンテンツは、LTRでは範囲スライダーの左側に、RTLでは右側に配置されます。

Labels​

Label Placement​

Label Slot​

No Visible Label​

Decorations​

Dual Knobs​

ピン​

Snapping & Ticks​

イベントハンドリング​

Using ionChange​

ionKnobMoveStart と ionKnobMoveEnd を使う​

テーマ​

CSSカスタムプロパティ​

CSS Shadow Parts​

レガシーな範囲構文からの移行​

最新の構文の使い方​

レガシー構文の使用​

Interfaces​

RangeChangeEventDetail​

RangeKnobMoveStartEventDetail​

RangeKnobMoveEndEventDetail​

RangeCustomEvent​

Types​

RangeValue​

プロパティ​

activeBarStart​

color​

debounce​

disabled​

dualKnobs​

label​

labelPlacement​

max​

min​

mode​

name​

pin​

pinFormatter​

snaps​

step​

ticks​

value​

イベント​

メソッド​

CSS Shadow Parts​

CSSカスタムプロパティ​

Slots​

Contents

Labels

Label Placement

Label Slot

No Visible Label

Decorations

Dual Knobs

ピン

Snapping & Ticks

イベントハンドリング

Using `ionChange`

`ionKnobMoveStart` と `ionKnobMoveEnd` を使う

テーマ

CSSカスタムプロパティ

CSS Shadow Parts

レガシーな範囲構文からの移行

最新の構文の使い方

レガシー構文の使用

Interfaces

RangeChangeEventDetail

RangeKnobMoveStartEventDetail

RangeKnobMoveEndEventDetail

RangeCustomEvent

Types

RangeValue

プロパティ

activeBarStart

color

debounce

disabled

dualKnobs

label

labelPlacement

max

min

mode

name

pin

pinFormatter

snaps

step

ticks

value

イベント

メソッド

CSS Shadow Parts

CSSカスタムプロパティ

Slots