跳至主要內容
版本：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，則可以改為使用 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>
注意

在過去的 Ionic 版本中，ion-range 必須搭配 ion-item 才能正常運作。從 Ionic 7.0 開始，只有當 ion-item 放置在 ion-list 中時，ion-range 才應該在 ion-item 內使用。此外，ion-range 不再需要 ion-item 才能正常運作。

使用舊版語法​

Ionic 使用啟發式方法來檢測應用程式是否正在使用現代的 range 語法。在某些情況下，可能更偏好繼續使用舊版語法。開發人員可以將 ion-range 的 legacy 屬性設定為 true，以強制該 range 實例使用舊版語法。

介面​

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​

描述range 活動條的起始位置。此功能僅適用於單個旋鈕 (dualKnobs="false")。有效值必須大於或等於最小值，且小於或等於最大值。
屬性active-bar-start
型別number ｜ undefined
預設值undefined

color​

描述要從應用程式的調色盤中使用的顏色。預設選項為："primary"、"secondary"、"tertiary"、"success"、"warning"、"danger"、"light"、"medium" 和 "dark"。有關顏色的更多資訊，請參閱主題化。
屬性顏色
型別"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
預設值undefined

debounce​

描述在 range 值每次更改後，等待觸發 ionInput 事件的毫秒數。
屬性debounce
型別number ｜ undefined
預設值undefined

disabled​

描述如果為 true，則使用者無法與 range 互動。
屬性disabled
型別boolean
預設值false

dualKnobs​

描述顯示兩個旋鈕。
屬性dual-knobs
型別boolean
預設值false

label​

描述要顯示為控制項標籤的文字。如果只需要純文字，請使用此屬性，而非 label 插槽。如果同時使用，label 屬性的優先順序會高於 label 插槽。
屬性label
型別string ｜ undefined
預設值undefined

labelPlacement​

描述標籤相對於 range 的放置位置。"start"：標籤在 LTR 中會出現在 range 的左側，在 RTL 中會出現在右側。"end"：標籤在 LTR 中會出現在 range 的右側，在 RTL 中會出現在左側。"fixed"：標籤的行為與 "start" 相同，只是它也有固定的寬度。長文字會被截斷並顯示省略符號 ("...")。"stacked"：標籤會出現在 range 上方，無論方向為何。
屬性label-placement
型別"end" ｜ "fixed" ｜ "stacked" ｜ "start"
預設值'start'

max​

描述range 的最大整數值。
屬性max
型別number
預設值100

min​

描述range 的最小整數值。
屬性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.dev.org.tw/docs/troubleshooting/runtime#accessing-this。
屬性undefined
型別(value: number) => string ｜ number
預設值(value: number): number => Math.round(value)

snaps​

描述如果為 true，則旋鈕會根據 step 屬性值，對齊均勻間隔的刻度標記。
屬性snaps
型別boolean
預設值false

step​

描述指定值粒度。
屬性step
型別number
預設值1

ticks​

描述如果為 true，則會根據 step 值顯示刻度標記。僅在 snaps 為 true 時適用。
屬性ticks
型別boolean
預設值true

value​

描述range 的值。
屬性value
型別number ｜ { lower: number; upper: number; }
預設值0

事件​

名稱描述冒泡
ionBlur當 range 失去焦點時發出。true
ionChange當使用者修改 <ion-range> 元素的值時，會觸發 ionChange 事件：- 當使用者拖曳後釋放旋鈕時；- 當使用者使用鍵盤箭頭移動旋鈕時

當以程式方式設定 value 屬性時，此事件不會發出。		true
ionFocus當 range 獲得焦點時發出。true
ionInput當值被修改時，會針對 <ion-range> 元素觸發 ionInput 事件。與 ionChange 不同，ionInput 會在使用者拖曳旋鈕時連續觸發。true
ionKnobMoveEnd當使用者完成移動 range 旋鈕時發出，無論是透過滑鼠拖曳、觸控手勢或鍵盤互動。true
ionKnobMoveStart當使用者開始移動 range 旋鈕時發出，無論是透過滑鼠拖曳、觸控手勢或鍵盤互動。true

方法​

此元件沒有可用的公開方法。

CSS 陰影部分​

名稱描述
barbar 的非活動部分。
bar-activebar 的活動部分。
knob用於拖曳 range 的控制把手。
label描述 range 的標籤文字。
pin出現在旋鈕上方的計數器。
tick非活動刻度標記。
tick-active活動刻度標記。

CSS 自訂屬性​

名稱描述
--bar-backgroundrange bar 的背景
--bar-background-active活動 range bar 的背景
--bar-border-radiusrange bar 的邊框半徑
--bar-heightrange bar 的高度
--heightrange 的高度
--knob-backgroundrange 旋鈕的背景
--knob-border-radiusrange 旋鈕的邊框半徑
--knob-box-shadowrange 旋鈕的陰影
--knob-sizerange 旋鈕的大小
--pin-backgroundrange 圖釘的背景 (僅在 MD 模式下可用)
--pin-colorrange 圖釘的顏色 (僅在 MD 模式下可用)

插槽​

名稱描述
end在 LTR 中，內容放置在 range 滑桿的右側，在 RTL 中則放置在左側。
label要與 range 相關聯的標籤文字。使用 "labelPlacement" 屬性來控制標籤相對於 range 的放置位置。
start在 LTR 中，內容放置在 range 滑桿的左側，在 RTL 中則放置在右側。

目錄

編輯此頁面