ion-range

shadow

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

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

Labels

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

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

Label Placement

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

src/app/example.component.html

<ion-range labelPlacement="start" label="Label at the Start"></ion-range>

<br />

<ion-range labelPlacement="end" label="Label at the End"></ion-range>

<br />

<ion-range labelPlacement="fixed" label="Fixed Width Label"></ion-range>

<br />

<ion-range labelPlacement="stacked" label="Stacked Label"></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {}

Label Slot

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

src/app/example.component.html

<ion-range>
  <div slot="label">Label with <ion-text color="primary">custom HTML</ion-text></div>
</ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange, IonText } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange, IonText],
})
export class ExampleComponent {}

No Visible Label

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

src/app/example.component.html

<ion-range aria-label="Volume"></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {}

Decorations

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

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

src/app/example.component.html

<ion-range aria-label="Temperature">
  <ion-icon slot="start" name="snow-outline"></ion-icon>
  <ion-icon slot="end" name="sunny-outline"></ion-icon>
</ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonIcon, IonRange } from '@ionic/angular/standalone';

import { addIcons } from 'ionicons';
import { snowOutline, sunnyOutline } from 'ionicons/icons';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonIcon, IonRange],
})
export class ExampleComponent {
  constructor() {
    /**
     * Any icons you want to use in your application
     * can be registered in app.component.ts and then
     * referenced by name anywhere in your application.
     */
    addIcons({ snowOutline, sunnyOutline });
  }
}

Dual Knobs

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

src/app/example.component.html

<ion-range aria-label="Dual Knobs Range" [dualKnobs]="true" [value]="{ lower: 20, upper: 80 }"></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {}

ピン

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

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

src/app/example.component.html

<ion-range aria-label="Range with pin" [pin]="true" [pinFormatter]="pinFormatter"></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {
  pinFormatter(value: number) {
    return `${value}%`;
  }
}

Snapping & Ticks

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

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

src/app/example.component.html

<ion-range aria-label="Range with ticks" [ticks]="true" [snaps]="true" [min]="0" [max]="10"></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {}

イベントハンドリング

Using ionChange

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

Console

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

src/app/example.component.html

<ion-range aria-label="Range with ionChange" (ionChange)="onIonChange($event)"></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange, RangeCustomEvent } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {
  onIonChange(event: RangeCustomEvent) {
    console.log('ionChange emitted value:', event.detail.value);
  }
}

ionKnobMoveStart と ionKnobMoveEnd を使う

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

Console

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

src/app/example.component.html

<ion-range
  aria-label="Range with knob events"
  (ionKnobMoveStart)="onIonKnobMoveStart($event)"
  (ionKnobMoveEnd)="onIonKnobMoveEnd($event)"
></ion-range>

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange, RangeCustomEvent } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {
  onIonKnobMoveStart(event: RangeCustomEvent) {
    console.log('ionKnobMoveStart:', event.detail.value);
  }

  onIonKnobMoveEnd(event: RangeCustomEvent) {
    console.log('ionKnobMoveEnd:', event.detail.value);
  }
}

テーマ

CSSカスタムプロパティ

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

src/app/example.component.html

<ion-range aria-label="Custom range" [value]="50" [pin]="true"></ion-range>

src/app/example.component.css

ion-range {
  --bar-background: #a2d2ff;
  --bar-background-active: #bde0fe;
  --bar-height: 8px;
  --bar-border-radius: 8px;
  --knob-background: #ffc8dd;
  --knob-size: 40px;
  --pin-background: #ffafcc;
  --pin-color: #fff;
}

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {}

CSS Shadow Parts

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

src/app/example.component.html

<ion-range
  aria-label="Custom range"
  [min]="0"
  [max]="10"
  [value]="5"
  [pin]="true"
  [ticks]="true"
  [snaps]="true"
></ion-range>

src/app/example.component.css

ion-range::part(tick) {
  background: #a2d2ff;
}

ion-range::part(tick-active) {
  background: #bde0fe;
}

ion-range::part(pin) {
  display: inline-flex;
  align-items: center;
  justify-content: center;

  background: #ffafcc;
  color: #fff;

  border-radius: 50%;
  transform: scale(1.01);

  top: -20px;

  min-width: 28px;
  height: 28px;
  transition: transform 120ms ease, background 120ms ease;
}

ion-range::part(pin)::before {
  content: none;
}

ion-range::part(knob) {
  background: #ffc8dd;
}

ion-range::part(bar) {
  background: #a2d2ff;
}

ion-range::part(bar-active) {
  background: #bde0fe;
}

src/app/example.component.ts

import { Component } from '@angular/core';
import { IonRange } from '@ionic/angular/standalone';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonRange],
})
export class ExampleComponent {}

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

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

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

最新の構文の使い方

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

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

JavaScript

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

Angular

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

React

{/* 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>

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>

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

pin

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カスタムプロパティ

iOS

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時のみ有効）

MD

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では右側に配置されます。