@fox-js/phone-skills 4.0.1-0

package/foxui/references/fox-picker/doc.md

@@ -0,0 +1,668 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Picker 组件使用规范
+impact: HIGH
+type: capability
+description: 提供多个选型集合供用户选择,支持单列选择和多列级联,通常与弹出层配合使用
+tags: [foxui, fox-picker, FoxPicker]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-cell","fox-switch-item","fox-button"]
+---
+
+# Picker 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Picker 是 foxui 中用于 **提供多个选型集合供用户选择,支持单列选择和多列级联,通常与弹出层配合使用** 的标准组件。
+- **基于**: NutUI `nut-picker` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持插槽扩展自定义内容
+- **适用场景**: 提供多个选型集合供用户选择,支持单列选择和多列级联,通常与弹出层配合使用
+
+> 💡 **关键原则**: 在所有 提供多个选型集合供用户选择,支持单列选择和多列级联,通常与弹出层配合使用 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 值 | Array,Boolean,String,Number | false |
+| `v-model:visible` | 是否可见 | Boolean | false |
+| `title` | 设置标题 | String | - |
+| `cancel-text` | 取消按钮文案 | String | 取消 |
+| `confirm-text` | 确定按钮文案 | String | 确定 |
+| `source` | 数据源 | string / array/ function  | — |
+| `source-filter` | 数据源过滤器 | function | — |
+| `param` | 请求参数配置数据源api使用 | record<string,any> | — |
+| `valueType` | 值的类型text:item.text,value:item.value,item:item | String | "value" |
+| `text-key` | 指定异构数据源的text key | String | "text" |
+| `text-key` | 指定异构数据源的value key | String | "value" |
+| `children-key` | 指定异构数据源的children key | String | "children" |
+| `three-dimensional` | 是否开启3D效果 | Boolean | true |
+| `swipe-duration` | 惯性滚动时长 | Number、String | 1000 |
+| `visible-item-count` | 可见item数量必须为奇数 | Number、String | 7 |
+| `teleport` | 指定挂载节点 | String | "body" |
+| `close-on-click-overlay` | 点击蒙层是否关闭对话框 | Boolean | false |
+| `lock-scroll` | 背景是否锁定 | Boolean | false |
+| `poppable` | 是否弹出 | Boolean | true |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `close` | 关闭弹窗时触发 | event: Event |
+| `confirm` | 点击确认时候触发 | event: Event |
+| `change` | 改变时触发 | val |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | 自定义滑动数据底部区域 |
+| `top` | 自定义滑动数据顶部区域 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基础用法
+
+```html
+<fox-cell title="请选择城市" :desc="desc(val)" @click="open(1)"></fox-cell>
+<fox-picker v-model="val" v-model:visible="show" :source="m_str_items" title="城市选择" @confirm="confirm" @close="close">
+</fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_str_items: ['南京', '无锡', '海北藏族自治区', '北京', '连云港', '浙江省', '江苏省'],
+      val: '浙江市',
+      show: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+### 平铺样式
+
+```
+<h2>平铺样式</h2>
+<fox-cell title="请选择城市" :desc="desc(val2)" @click="open(2)"></fox-cell>
+<fox-picker
+      v-model="val2"
+      v-model:visible="show2"
+      :source="m_items"
+      :three-dimensional="false"
+      title="城市选择"
+      @confirm="confirm"
+      @close="close"
+    >
+</fox-picker>
+
+```
+
+设置`three-dimensional`属性为false
+
+### 平铺样式
+
+```
+<h2>平铺样式</h2>
+<fox-cell title="请选择城市" :desc="desc(val2)" @click="open(2)"></fox-cell>
+<fox-picker
+    v-model="val2"
+    v-model:visible="show2"
+    :source="m_items"
+    :three-dimensional="false"
+    title="城市选择"
+    @confirm="confirm"
+    @close="close"
+    >
+</fox-picker>
+
+```
+
+设置`three-dimensional`属性为false
+
+### 显示数量设置
+
+```
+<h2>显示数量设置</h2>
+<fox-cell title="请选择城市" :desc="desc(val3)" @click="open(3)"></fox-cell>
+<fox-picker
+    v-model="val3"
+    v-model:visible="show3"
+    :source="m_items"
+    :three-dimensional="false"
+    :visible-item-count="13"
+    title="城市选择"
+    @confirm="confirm"
+    @close="close">
+</fox-picker>
+
+```
+前提是设置`three-dimensional`属性为false, `visible-item-count`属性为可见item的数量，必须为奇数
+
+### 多列样式
+
+```html
+<fox-cell title="请选择时间" :desc="desc(val2)" @click="open(2)"></fox-cell>
+<fox-picker v-model="val2" v-model:visible="show2" :source="m_str_multi_items" title="多列选择"
+ @confirm="confirm" @close="close">
+</fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_str_multi_items: [
+        ['周一', '周二', '周三', '周四', '周五'],
+        ['上午', '下午', '晚上']
+      ],
+      val2: [],
+      show2: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+### 多级联动
+
+```html
+<fox-cell title="请选择地址" :desc="desc(val3)" @click="open(3)"></fox-cell>
+<fox-picker v-model="val3" v-model:visible="show3" :source="m_address" title="地址选择" @confirm="confirm"></fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_address: [
+        {
+          text: '浙江',
+          value: '浙江',
+          children: [
+            {
+              text: '杭州',
+              value: '杭州',
+              children: [
+                { text: '西湖区', value: '西湖区' },
+                { text: '余杭区', value: '余杭区' }
+              ]
+            },
+            {
+              text: '温州',
+              value: '温州',
+              children: [
+                { text: '鹿城区', value: '鹿城区' },
+                { text: '瓯海区', value: '瓯海区' }
+              ]
+            }
+          ]
+        },
+        {
+          text: '福建',
+          value: '福建',
+          children: [
+            {
+              text: '福州',
+              value: '福州',
+              children: [
+                { text: '鼓楼区', value: '鼓楼区' },
+                { text: '台江区', value: '台江区' }
+              ]
+            },
+            {
+              text: '厦门',
+              value: '厦门',
+              children: [
+                { text: '思明区', value: '思明区' },
+                { text: '海沧区', value: '海沧区' }
+              ]
+            }
+          ]
+        }
+      ],
+      val3: [],
+      show3: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+### 返回类型text
+
+```html
+<fox-cell title="请选择城市" :desc="desc(val4)" @click="open(4)"></fox-cell>
+<fox-picker v-model="val4" v-model:visible="show4" :source="m_items" title="城市选择" value-type="text" @confirm="confirm" @close="close" >
+</fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_items: [
+        { text: '南京', value: '01' },
+        { text: '无锡', value: '02' },
+        { text: '海北藏族自治区', value: '03' },
+        { text: '北京', value: '04' },
+        { text: '连云港', value: '05' },
+        { text: '浙江省', value: '06' },
+        { text: '江苏省', value: '07' }
+      ],
+      val4: [],
+      show4: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+### 返回类型value
+
+```html
+<fox-cell title="请选择城市" :desc="desc(val5)" @click="open(5)"></fox-cell>
+<fox-picker v-model="val5" v-model:visible="show5" :source="m_items" title="城市选择" value-type="value" @confirm="confirm" @close="close">
+</fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_items: [
+        { text: '南京', value: '01' },
+        { text: '无锡', value: '02' },
+        { text: '海北藏族自治区', value: '03' },
+        { text: '北京', value: '04' },
+        { text: '连云港', value: '05' },
+        { text: '浙江省', value: '06' },
+        { text: '江苏省', value: '07' }
+      ],
+      val5: [],
+      show5: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+### 返回类型item
+
+```html
+<fox-cell title="请选择城市" :desc="desc(val6)" @click="open(6)"></fox-cell>
+<fox-picker v-model="val6" v-model:visible="show6" :source="m_items" title="城市选择" value-type="item" @confirm="confirm" @close="close"></fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_items: [
+        { text: '南京', value: '01' },
+        { text: '无锡', value: '02' },
+        { text: '海北藏族自治区', value: '03' },
+        { text: '北京', value: '04' },
+        { text: '连云港', value: '05' },
+        { text: '浙江省', value: '06' },
+        { text: '江苏省', value: '07' }
+      ],
+      val6: { text: '北京', value: '04' },,
+      show6: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+### 函数数据源
+
+```html
+<fox-cell title="请选择时间" :desc="desc(val7)" @click="open(7)"></fox-cell>
+<fox-picker v-model="val7" v-model:visible="show7" :source="m_func" title="时间选择" value-type="text" @confirm="confirm" @close="close"></fox-picker>
+```
+
+```javascript
+<script>
+export default createDemo({
+  setup() {
+    let m_multi_items = [
+      [
+        { text: '周一', value: '一' },
+        { text: '周二', value: '二' },
+        { text: '周三', value: '三' },
+        { text: '周四', value: '四' },
+        { text: '周五', value: '五' }
+      ],
+      [
+        { text: '上午', value: '上' },
+        { text: '下午', value: '下' },
+        { text: '晚上', value: '晚' }
+      ]
+    ]
+
+    // 数据
+    const data = reactive({
+      m_func: (): Promise<unknown> => {
+        return new Promise(resolve => {
+          resolve(m_multi_items)
+        })
+      },
+      val7: ['周五', '晚上'],
+      show7: false,
+    })
+
+    // 方法
+    const methods = {
+      // open picker
+      open(id: number) {
+        if (id == 1) {
+          data.show = true
+        } else {
+          let dataAny = data as any
+          dataAny[`show${id}`] = true
+        }
+      },
+      // close picker
+      close() {
+        console.info('close')
+      },
+      // confirm action
+      confirm() {
+        console.info('confirm')
+      },
+      // 显示描述
+      desc(val: unknown) {
+        if (Array.isArray(val)) {
+          if (val.length == 0) {
+            return ''
+          }
+          return JSON.stringify(val)
+        } else if (typeof val == 'object') {
+          return JSON.stringify(val)
+        } else {
+          return `${val}`
+        }
+      }
+    }
+
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+</script>
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Picker 配合使用的相关组件
+- **fox-cell**: 与 Picker 配合使用的相关组件
+- **fox-switch-item**: 与 Picker 配合使用的相关组件
+- **fox-button**: 与 Picker 配合使用的相关组件
+