---
title: william-weng/wwwheelpickerviewui
framework: Swift Package Catalog
role: article
path: packages/william-weng/wwwheelpickerviewui
---

# william-weng/wwwheelpickerviewui

[English](./README.en.md) | [繁體中文](./README.md)

## ✨ [特色](https://peterpanswift.github.io/iphone-bezels/)

- 使用 `ScrollView` + `ScrollViewReader` 製作水平刻度選擇器。 - 支援點擊指定刻度後，自動捲動到中央位置。 - 滑動過程中，會持續回報目前最接近中央的 index。 - 停止捲動後，會自動吸附到最近的刻度位置。 - 可自訂主刻度顯示間隔 `majorTickInterval`。 - 提供 `onTapIndex`、`onChangingIndex`、`onSettledIndex` 三種事件回呼。

## 📦 安裝方式

### Swift Package Manager

```swift dependencies: [     .package(url: "https://github.com/William-Weng/WWWheelPickerViewUI.git", from: "0.7.0") ] ```

## 🚀 可用參數

| 參數 | 說明 | |---------|-------------| | `items` | 外部傳入的刻度資料。 | | `scrollAxis` | ScrollView 的捲動方向，預設為 `.horizontal`。 | | `selectedIndex` | 目前選取的 index，停止後會吸附並更新該值。 | | `majorTickInterval` | 每隔幾格顯示一次主刻度與文字，預設是 `5`。 | | `lengthMultiple` | 刻度線的長度比例。 |

## 🧩 可用API

| 方法 | 說明 | |--------|-------------| | `onTapIndex` | 點擊某個刻度時觸發。 | | `onChangingIndex` | 滑動過程中，目前 index 改變時觸發。 | | `onSettledIndex` | 捲動停止並完成吸附後觸發。 |

## 🚀 使用範例

### 水平方向

```swift import SwiftUI import WWWheelPickerViewUI

struct HorizontalContent: View {          @State private var selectedIndex: Int = 10     @State private var selectedTitle: String?          private let items: [WWWheelPickerItem] = (0...20).map { index in         .init(id: index, value: index - 10, label: "\(index - 10)")     }          var body: some View {                  VStack {                          Text(selectedTitle ?? "?")                          WWWheelPickerViewUI(items: items, selectedIndex: $selectedIndex)                 .frame(height: 80)                 .background(Color.green)                 .onAppear {                     selectedTitle = "\(items[selectedIndex].label)"                 }                 .onChange(of: selectedIndex) { oldValue, newValue in                     selectedTitle = "\(items[newValue].label)"                 }         }     } }

#Preview {     HorizontalContent() } ```

### 垂直方向

```swift import SwiftUI import WWWheelPickerViewUI

struct VerticalContent: View {          @State private var selectedIndex: Int = 10     @State private var selectedTitle: String?          private let items: [WWWheelPickerItem] = (0...20).map { index in         .init(id: index, value: index - 10, label: "\(index - 10)")     }          var body: some View {                  HStack {                                      WWWheelPickerViewUI(items: items, selectedIndex: $selectedIndex, scrollAxis: .vertical)                 .onTapIndex { index in                     print("onTapIndex = \(index)")                 }.onChangingIndex({ index in                     selectedTitle = "\(items[index].label)"                 }).onSettledIndex({ index in                     selectedTitle = "\(items[index].label)"                 })                 .frame(width: 120)                 .background(Color.yellow)                 .onAppear {                     selectedTitle = "\(items[selectedIndex].label)"                 }                          Text(selectedTitle ?? "?")                 .frame(width: 32)         }     } }

#Preview {     VerticalContent() } ```

## ⚠️ 注意事項

- `id` 必須為正值，且建議從 `0` 開始連續編號，因為它是 `index` 的參考值。 - 建議 `items.index` 依序排列，避免 Scroll 定位與顯示邏輯不一致。 - `majorTickInterval` 只影響主刻度高度與文字顯示，不影響實際選取邏輯。

## Package Metadata

Repository: william-weng/wwwheelpickerviewui

Default branch: main

README: README.md