Skip to main content
Version: v7

ion-range

shadow

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

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

Labels

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

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

Label Placement

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

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を使用するためには、開発者は snapsticks プロパティの両方を true に設定する必要があります。

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

イベントハンドリング

Using ionChange

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

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

ionKnobMoveStartionKnobMoveEnd を使う

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

テーマ

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 内に直接渡すことができる。

<!-- 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-rangeion-item 内でアイテムを ion-list に配置する場合にのみ使用します。また、ion-range が正しく機能するためには、ion-item は不要になりました。

レガシー構文の使用

Ionicは、アプリが最新の範囲構文を使用しているかどうかをヒューリスティックで検出します。場合によっては、レガシー構文を使い続けた方が望ましいこともあります。開発者は ion-rangelegacy プロパティを 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値以下です。
Attributeactive-bar-start
Typenumber | undefined
Defaultundefined

color

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

debounce

Descriptionレンジの値が変化するたびに ionInput イベントをトリガーするまでの待ち時間(ミリ秒単位)。
Attributedebounce
Typenumber | undefined
Defaultundefined

disabled

Descriptiontrueの場合、ユーザは範囲と対話することができません。
Attributedisabled
Typeboolean
Defaultfalse

dualKnobs

Description2つのノブを表示します。
Attributedual-knobs
Typeboolean
Defaultfalse

label

DescriptionThe 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.
Attributelabel
Typestring | undefined
Defaultundefined

labelPlacement

Description範囲に対してラベルを配置する場所。"start":ラベルはLTRでは範囲の左側に、RTLでは右側に表示されます。"end":ラベルはLTRでは範囲の右側、RTLでは左側に表示されます。"fixed":ラベルの幅が固定される以外は、"start"と同じ動作をします。長いテキストは省略記号("...")で切り捨てられます。
Attributelabel-placement
Type"end" | "fixed" | "start"
Default'start'

legacy

Descriptionlegacyプロパティをtrueに設定すると、レガシーフォームコントロールのマークアップを強制的に使用することができます。Ionicは、コンポーネントがaria-label属性またはlabelプロパティを使用している場合にのみ、最新のフォームマークアップを選択します。そのため、legacyプロパティは、この自動オプトイン動作を回避したい場合にのみ、エスケープハッチとして使用する必要があります。なお、このプロパティはIonicの今後のメジャーリリースで削除され、すべてのフォームコンポーネントはモダンフォームマークアップを使用するようオプトインされる予定です。
Attributelegacy
Typeboolean | undefined
Defaultundefined

max

Description範囲の最大整数値。
Attributemax
Typenumber
Default100

min

Description範囲の最小の整数値。
Attributemin
Typenumber
Default0

mode

Descriptionmodeは、どのプラットフォームのスタイルを使用するかを決定します。
Attributemode
Type"ios" | "md"
Defaultundefined

name

Descriptionフォームデータとともに送信されるコントロールの名前。
Attributename
Typestring
Defaultthis.rangeId

pin

Descriptiontrueの場合、ノブを押したときに整数値のピンが表示されます。
Attributepin
Typeboolean
Defaultfalse

pinFormatter

Descriptionピンのテキストをフォーマットするために使用されるコールバックです。デフォルトでは、ピンのテキストは Math.round(value) に設定されます。
Attributeundefined
Type(value: number) => string | number
Default(value: number): number => Math.round(value)

snaps

Descriptiontrueの場合、ノブはステッププロパティの値に基づいて等間隔に配置されたティックマークにスナップします。
Attributesnaps
Typeboolean
Defaultfalse

step

Description値の粒度を指定します。
Attributestep
Typenumber
Default1

ticks

Descriptiontrueの場合、ステップの値に基づいてティックマークを表示します。snapstrue` の場合のみ適用される。
Attributeticks
Typeboolean
Defaulttrue

value

Description範囲の値です。
Attributevalue
Typenumber | { lower: number; upper: number; }
Default0

イベント

NameDescription
ionBlurレンジの焦点が合わなくなったときに発行されます。
ionChangeionChangeイベントは、<ion-range>要素に対して、ユーザーがその要素の値を変更したときに発生します: - ドラッグした後にノブを離したとき - キーボードの矢印でノブを動かしたとき プログラムで値を変更したときは、ionChangeイベントは発生しません。
ionFocusレンジのフォーカスが合ったときに発行されます。
ionInputionInputイベントは、<ion-range>要素に対して、値が変更されたときに発生するイベントです。ionChangeとは異なり、ionInputはユーザがノブをドラッグしている間、継続して発生します。
ionKnobMoveEndマウスドラッグ、タッチジェスチャー、キーボード操作など、ユーザーが範囲ノブの移動を終了したときに発行されます。
ionKnobMoveStartマウスドラッグ、タッチジェスチャー、キーボード操作など、ユーザーがレンジノブの移動を開始したときに発行されます。

メソッド

No public methods available for this component.

CSS Shadow Parts

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

CSSカスタムプロパティ

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

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