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