@fox-js/phone-skills 4.0.1-0

package/foxui/references/fox-cascader-item/doc.md

@@ -0,0 +1,710 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: CascaderItem 组件使用规范
+impact: HIGH
+type: capability
+description: 级联选择器，用于多层级数据的选择，典型场景为省市区选择.
+tags: [foxui, fox-cascader-item, FoxCascaderItem]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-group","fox-item","fox-input-text","fox-cascader"]
+---
+
+# CascaderItem 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+CascaderItem 是 foxui 中用于 **级联选择器，用于多层级数据的选择，典型场景为省市区选择.** 的标准组件。
+- **基于**: NutUI `nut-cascader-item` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、内置必填校验标识、支持 v-model 双向绑定、支持标签位置自定义、支持占位符提示、支持禁用/只读状态、内置多级提示信息、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 级联选择器，用于多层级数据的选择，典型场景为省市区选择.
+
+> 💡 **关键原则**: 在所有 级联选择器，用于多层级数据的选择，典型场景为省市区选择. 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 选中值，双向绑定 | Array | - |
+| `source` | 级联数据 | Array,Function,String | - |
+| `lazy` | 是否开启动态加载 | Boolean | - |
+| `lazy-load` | 动态加载回调，开启动态加载时生效 | Function | - |
+| `value-key` | 自定义options结构中value的字段 | String | - |
+| `text-key` | 自定义options结构中text的字段 | String | - |
+| `children-key` | 自定义options结构中children的字段 | String | - |
+| `convert-config` | 当options为可转换为树形结构的扁平结构时，配置转换规则 | Object | - |
+| `title` | 标题 | String | '' |
+| `show-all-levels` | 是否显示完整的路径 | Boolean | true |
+| `separator` | 分割符 | String | / |
+| `close-icon-position` | 取消按钮位置，继承 Popup 组件 | String | "top-right" |
+| `close-icon` | 自定义关闭按钮，继承 Popup 组件 | String | "close" |
+| `closeable` | 是否显示关闭按钮，继承 Popup 组件 | Boolean | true |
+| `label` | 标签 | String | - |
+| `label-width` | 标签宽度 | String | - |
+| `label-position` | 标签位置可选值left,right,top | String | - |
+| `is-required` | 左侧号是否展示 | Boolean | false |
+| `disabled` | 是否禁用 | Boolean | false |
+| `readonly` | 是否只读 | Boolean | false |
+| `error-tip` | 错误提示 | String | - |
+| `error-icon` | 错误提示图标 | String | - |
+| `warn-tip` | 警告提示 | String | - |
+| `warn-icon` | 警告提示图标 | String | - |
+| `info-tip` | 提示 | String | - |
+| `info-icon` | 提示图标 | String | - |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 选中值改变时触发 | value, pathNodes |
+| `pathChange` | 选中项改变时触发 | pathNodes |
+| `change` | 输入内容时触发 | val ,event |
+| `focus` | 聚焦时触发 | val  ,event |
+| `blur` | 失焦时触发 | val ,event |
+| `clear` | 点击清空时触发 | val |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | label内容 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+### 基础用法
+`source`数组数据源和设置禁用或只读属性
+```html
+  <fox-group v-if="true" title="基础用法">
+    <fox-cascader-item
+      v-model="demo1.value"
+      :source="demo1.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >选择地址</fox-cascader-item
+    >
+    <fox-cascader-item
+      readonly
+      v-model="demo1.value2"
+      :source="demo1.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >只读</fox-cascader-item
+    >
+    <fox-cascader-item
+      disabled
+      v-model="demo1.value3"
+      :source="demo1.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >禁用</fox-cascader-item
+    >
+     <fox-cascader-item
+      v-model="demo1.value3"
+      :source="demo1.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      :show-all-levels="false"
+      >显示最后一级</fox-cascader-item
+    >
+  </fox-group>
+```
+```javascript
+setup() {
+  // 基础用法
+    const demo1 = reactive({
+      value: [],
+      value2: ['广东', '广州', '黄埔区'],
+      value3: ['福建', '福州', '台江区'],
+      value4:'',
+      source: [
+        {
+          value: '广东',
+          text: '广东',
+          children: [
+            {
+              value: '广州',
+              text: '广州',
+              disabled: true,
+              children: [
+                { value: '黄埔区', text: '黄埔区' },
+                { value: '南沙', text: '南沙' }
+              ]
+            },
+            {
+              value: '佛山',
+              text: '佛山',
+              children: [
+                { value: '禅城区', text: '禅城区' },
+                { value: '南海区', text: '南海区' }
+              ]
+            }
+          ]
+        },
+        {
+          value: '浙江',
+          text: '浙江',
+          children: [
+            {
+              value: '杭州',
+              text: '杭州',
+              disabled: true,
+              children: [
+                { value: '西湖区', text: '西湖区' },
+                { value: '余杭区', text: '余杭区' }
+              ]
+            },
+            {
+              value: '温州',
+              text: '温州',
+              children: [
+                { value: '鹿城区', text: '鹿城区' },
+                { value: '瓯海区', text: '瓯海区' }
+              ]
+            }
+          ]
+        },
+        {
+          value: '湖南',
+          text: '湖南',
+          disabled: true
+        },
+        {
+          value: '福建',
+          text: '福建',
+          children: [
+            {
+              value: '福州',
+              text: '福州',
+              children: [
+                { value: '鼓楼区', text: '鼓楼区' },
+                { value: '台江区', text: '台江区' }
+              ]
+            }
+          ]
+        }
+      ]
+    })
+    watch(
+      () => demo1.value,
+      newVal => {
+        console.info('watch demo1 value', newVal)
+        newVal.forEach(item => {
+          console.info(item)
+        })
+      }
+    )
+  const events = {
+    change(...args: any) {
+      console.log('change', ...args);
+    },
+    pathChange(...args: any) {
+      console.log('pathChange', ...args);
+    },
+  };
+  return { demo1, events };
+}
+```
+### 自定义属性名称
+可通过`textKey`、`valueKey`、`childrenKey`指定属性名。
+```html
+<fox-group>
+  <fox-item label="选择地址">
+    <input
+      class="fox-input-text"
+      @click="state.visible = true"
+      :value="state.value"
+      readonly
+      placeholder="请选择地址"
+      type="text"
+    />
+    <fox-cascader
+      title="地址选择"
+      v-model:visible="state.visible"
+      v-model="state.value"
+      label-key="text"
+      @change="events.change"
+      @path-change="events.pathChange"
+      value-key="text"
+      children-key="items"
+      :options="state.options"
+    ></fox-cascader>
+  </fox-item>
+</fox-group>
+```
+```ts
+setup() {
+  const state = reactive({
+    visible: false,
+    value: ['浙江', '杭州', '西湖区'],
+    options: [
+      {
+        text: '浙江',
+        items: [
+          {
+            text: '杭州',
+            disabled: true,
+            items: [{ text: '西湖区' }, { text: '余杭区' }]
+          },
+          {
+            text: '温州',
+            items: [{ text: '鹿城区' }, { text: '瓯海区' }]
+          }
+        ]
+      },
+      {
+        text: '福建',
+        items: [
+          {
+            text: '福州',
+            items: [{ text: '鼓楼区' }, { text: '台江区' }]
+          }
+        ]
+      }
+    ]
+  });
+  const events = {
+    change(...args: any) {
+      console.log('change', ...args)
+    },
+    pathChange(...args: any) {
+      console.log('pathChange', ...args)
+    },
+  };
+  return { demo1, events }
+}
+```
+### 返回类型
+通过设置value-type(返回类型)，让v-model指向选中项中的text、value或json对象
+级联选项的
+```html
+<fox-group v-if="true" title="返回类型">
+    <fox-cascader-item
+      v-model="demo2.value"
+      :source="demo2.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >value</fox-cascader-item
+    >
+    <fox-cascader-item
+      value-type="text"
+      v-model="demo2.value2"
+      :source="demo2.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >text</fox-cascader-item
+    >
+    <fox-cascader-item
+      value-type="item"
+      v-model="demo2.value3"
+      :source="demo2.source"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >item</fox-cascader-item
+    >
+  </fox-group>
+```
+```ts
+setup() {
+  // 返回类型
+    const demo2 = reactive({
+      value: ['01', '0102', '010201'],
+      value2: [],
+      value3: [
+        { value: '03', text: '福建' },
+        { value: '0301', text: '福州' },
+        { value: '030102', text: '台江区' }
+      ],
+      source: [
+        {
+          value: '01',
+          text: '浙江',
+          children: [
+            {
+              value: '0101',
+              text: '杭州',
+              disabled: true,
+              children: [
+                { value: '010101', text: '西湖区' },
+                { value: '010102', text: '余杭区' }
+              ]
+            },
+            {
+              value: '0102',
+              text: '温州',
+              children: [
+                { value: '010201', text: '鹿城区' },
+                { value: '010201', text: '瓯海区' }
+              ]
+            }
+          ]
+        },
+        {
+          value: '02',
+          text: '湖南',
+          disabled: true
+        },
+        {
+          value: '03',
+          text: '福建',
+          children: [
+            {
+              value: '0301',
+              text: '福州',
+              children: [
+                { value: '030101', text: '鼓楼区' },
+                { value: '030102', text: '台江区' }
+              ]
+            }
+          ]
+        }
+      ]
+    })
+    watch(
+      () => demo2.value,
+      val => {
+        console.info('demo value1', val)
+      }
+    )
+    watch(
+      () => demo2.value2,
+      val => {
+        console.info('demo value2', val)
+      }
+    )
+    watch(
+      () => demo2.value3,
+      val => {
+        console.info('demo value3', val)
+      }
+    )
+   
+    const events = {
+      change(...args: any) {
+        console.log('change', ...args)
+      },
+      pathChange(...args: any) {
+        console.log('pathChange', ...args)
+      }
+    }
+   
+    return { demo2, events }
+ }  
+```
+### 数据源
+组件的数据源有几种类型
+* 数组
+* 函数
+* 服务API
+```html
+<fox-group v-if="true" title="数据源">
+    <fox-cascader-item
+      v-model="demo3.value"
+      :source="demo3.list"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >数组</fox-cascader-item
+    >
+    <fox-cascader-item
+      v-model="demo3.value2"
+      :source="demo3.func"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >函数</fox-cascader-item
+    >
+    <fox-cascader-item
+      v-model="demo3.value3"
+      :source="demo3.path"
+      title="请选择地址"
+      placeholder="请选择地址"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >服务API</fox-cascader-item
+    >
+  </fox-group>
+```
+```ts
+setup() {
+    // 数据源
+    const demo3 = reactive({
+      value: [],
+      value2: [],
+      value3: ['01', '0101', '010101'],
+      list: [
+        {
+          value: '浙江',
+          text: '浙江',
+          children: [
+            {
+              value: '杭州',
+              text: '杭州',
+              disabled: true,
+              children: [
+                { value: '西湖区', text: '西湖区' },
+                { value: '余杭区', text: '余杭区' }
+              ]
+            },
+            {
+              value: '温州',
+              text: '温州',
+              children: [
+                { value: '鹿城区', text: '鹿城区' },
+                { value: '瓯海区', text: '瓯海区' }
+              ]
+            }
+          ]
+        },
+        {
+          value: '湖南',
+          text: '湖南',
+          disabled: true
+        },
+        {
+          value: '福建',
+          text: '福建',
+          children: [
+            {
+              value: '福州',
+              text: '福州',
+              children: [
+                { value: '鼓楼区', text: '鼓楼区' },
+                { value: '台江区', text: '台江区' }
+              ]
+            }
+          ]
+        }
+      ],
+      func: () => {
+        return [
+          {
+            value: '广东',
+            text: '广东',
+            children: [
+              {
+                value: '广州',
+                text: '广州',
+                disabled: true,
+                children: [
+                  { value: '黄埔区', text: '黄埔区' },
+                  { value: '南沙', text: '南沙' }
+                ]
+              },
+              {
+                value: '佛山',
+                text: '佛山',
+                children: [
+                  { value: '禅城区', text: '禅城区' },
+                  { value: '南海区', text: '南海区' }
+                ]
+              }
+            ]
+          },
+          {
+            value: '福建',
+            text: '福建',
+            children: [
+              {
+                value: '福州',
+                text: '福州',
+                children: [
+                  { value: '鼓楼区', text: '鼓楼区' },
+                  { value: '台江区', text: '台江区' }
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      path: '/DD/cascader'
+    })
+   
+    const events = {
+      change(...args: any) {
+        console.log('change', ...args)
+      },
+      pathChange(...args: any) {
+        console.log('pathChange', ...args)
+      }
+    }
+    return { demo3, events }
+ }  
+```
+### 异构结构
+默认的选项item的数据结构如下
+```ts
+export type CascaderOption = {
+  text?: string
+  value?: number | string
+  children?: CascaderOption[]
+}
+```
+如果item的数据结构和默认的有差异，这需要通过
+* text-key
+* value-key
+* children-key
+三个属性重新指定对应的key
+```html
+<fox-group v-if="true" title="异构结构">
+    <fox-cascader-item
+      v-model="demo4.value"
+      :source="demo4.source"
+      title="地址选择"
+      text-key="name"
+      value-key="id"
+      children-key="items"
+      @change="events.change"
+      @path-change="events.pathChange"
+      >选择地址</fox-cascader-item
+    >
+  </fox-group>
+```
+```ts
+setup() {
+     // 自定义属性名称
+    const demo4 = reactive({
+      value: ['01', '0101', '010101'],
+      source: [
+        {
+          id: '01',
+          name: '中国',
+          items: [
+            {
+              id: '0101',
+              name: '广东',
+              items: [
+                { id: '010101', name: '广州' },
+                { id: '010102', name: '佛山' },
+                { id: '010103', name: '茂名' }
+              ]
+            },
+            {
+              id: '0201',
+              name: '江苏',
+              items: [
+                { id: '020101', name: '南京' },
+                { id: '020102', name: '苏州' }
+              ]
+            }
+          ]
+        },
+        {
+          id: '02',
+          name: '欧洲',
+          items: [
+            {
+              id: '0201',
+              name: '法国',
+              items: [
+                { id: '020101', name: '巴黎' },
+                { id: '020102', name: '凡尔赛' }
+              ]
+            }
+          ]
+        }
+      ]
+    })
+   
+    const events = {
+      change(...args: any) {
+        console.log('change', ...args)
+      },
+      pathChange(...args: any) {
+        console.log('pathChange', ...args)
+      }
+    }
+    return { deme4, events }
+ }  
+```
+### 动态加载
+使用`lazy`标识是否需要动态获取数据，此时不传`options`代表所有数据都需要通过`lazyLoad`加载，首次加载通过`root`属性区分，当遇到非叶子节点时会调用`lazyLoad`方法，参数为当前节点和`resolve`方法，注意`resolve`方法必须调用，不传子节点时会被当做叶子节点处理。
+```html
+ <fox-group v-if="true" title="动态加载">
+    <fox-cascader-item
+      title="地址选择"
+      v-model="demo5.value"
+      @change="events.change"
+      @path-change="events.pathChange"
+      lazy
+      :lazy-load="demo5.lazyLoad"
+      >地址选择</fox-cascader-item
+    >
+  </fox-group>
+```
+```ts
+setup() {
+   // 动态加载
+    const demo5 = reactive({
+      value: ['A0', 'A12', 'A23', 'A32'],
+      lazyLoad(node: any, resolve: (children: any) => void) {
+        setTimeout(() => {
+          // root表示第一层数据
+          if (node.root) {
+            resolve([
+              { value: 'A0', text: 'A0' },
+              { value: 'B0', text: 'B0' },
+              { value: 'C0', text: 'C0' }
+            ])
+          } else {
+            const { value, level } = node
+            const text = value.substring(0, 1)
+            const value1 = `${text}${level + 1}1`
+            const value2 = `${text}${level + 1}2`
+            const value3 = `${text}${level + 1}3`
+            resolve([
+              { value: value1, text: value1, leaf: level >= 6 },
+              { value: value2, text: value2, leaf: level >= 6 },
+              { value: value3, text: value3, leaf: level >= 6 }
+            ])
+          }
+        }, 2000)
+      }
+    })
+    const events = {
+      change(...args: any) {
+        console.log('change', ...args)
+      },
+      pathChange(...args: any) {
+        console.log('pathChange', ...args)
+      }
+    }
+  return { demo5, events };
+}
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 CascaderItem 配合使用的相关组件
+- **fox-group**: 与 CascaderItem 配合使用的相关组件
+- **fox-item**: 与 CascaderItem 配合使用的相关组件
+- **fox-input-text**: 与 CascaderItem 配合使用的相关组件
+- **fox-cascader**: 与 CascaderItem 配合使用的相关组件
+