sard-uniapp/components/picker/README.md

sard-uniapp 是一套基于 Uniapp + Vue3 框架开发的兼容多端的 UI 组件库

---
title: Picker
subtitle: 选择器
group: 表单组件
---

## 介绍

一个或多个可滚动列表选择器。

## 引入

```js
import Picker from 'sard-uniapp/components/picker/picker.vue'
```

## 代码演示

### 基础使用

通过 `v-model` 绑定当前值，通过 `columns` 配置选项数据。

<<< @demo/picker/demo/Basic.vue

### 对象类型

列的每一项可以为一个对象，使用 `optionKeys` 属性可以指定对象中哪个属性值为选中的值，哪个属性值为要显示的标签。

<<< @demo/picker/demo/ObjectOption.vue

### 多列

当 `columns` 属性值为一个二维数组时会显示为多列。

<<< @demo/picker/demo/Multiple.vue

### 对象类型多列

`columns` 属性值为对象类型的二维数组。

<<< @demo/picker/demo/ObjectMultiple.vue

### 级联选择

当 `columns` 第一个元素为对象且其 `children` 属性值为数组时会被当作级联选择。

<<< @demo/picker/demo/Cascaded.vue

### 插槽

可通过 `custom` 插槽自定义每一个选项的内容。

::: info
因小程序不支持循环中的插槽，因此循环逻辑要自行实现；

因 `picker-view-column` 要为 `picker-view` 的直接子元素，因此要把 `picker-view` 提取出来，要自行绑定属性和事件。

:::
<<< @demo/picker/demo/Slot.vue

## API

### PickerProps

| 属性             | 描述                                               | 类型                               | 默认值                                                   |
| ---------------- | -------------------------------------------------- | ---------------------------------- | -------------------------------------------------------- |
| root-class       | 组件根元素类名                                     | string                             | -                                                        |
| root-style       | 组件根元素样式                                     | StyleValue                         | -                                                        |
| columns          | 配置每一列的数据                                   | PickerOption[] \| PickerOption[][] | []                                                       |
| option-keys      | 自定义 `columns` 结构中的字段                      | OptionKeys                         | `{label: 'label', value: 'value', children: 'children'}` |
| model-value      | 选中项的值                                         | any                                | -                                                        |
| immediate-change | 是否在手指松开时立即触发 `update:model-value` 事件 | boolean                            | false                                                    |

### PickerSlots

| 插槽                    | 描述             | 属性                                                                                                                                        |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| custom <sup>1.17+</sup> | 自定义选项的内容 | `{ columns: any[][]; value: number[]; pickerViewClass: string; maskClass: string; indicatorClass: string; onChange: (event: any) => void;}` |

### PickerEmits

| 事件                     | 描述                 | 类型                                                                       |
| ------------------------ | -------------------- | -------------------------------------------------------------------------- |
| update:model-value       | 选中的选项改变时触发 | `(value: any, selectedOptions: PickerOption[], indexes: number[]) => void` |
| change <sup>1.9.2+</sup> | 选中的选项改变时触发 | `(value: any, selectedOptions: PickerOption[], indexes: number[]) => void` |

### PickerOption

```tsx
type PickerOption =
  | {
      [key: PropertyKey]: any
    }
  | number
  | string
```

### OptionKeys

```tsx
interface OptionKeys {
  label?: string
  value?: string
  children?: string
}
```

## 主题定制

### CSS 变量

<<< @comp/picker/variables.scss#variables