@fox-js/phone-skills 4.0.1-0

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

@@ -0,0 +1,389 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: PickerItem 组件使用规范
+impact: HIGH
+type: capability
+description: 选择框组件
+tags: [foxui, fox-picker-item, FoxPickerItem]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-group","fox-switch-item"]
+---
+
+# PickerItem 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+PickerItem 是 foxui 中用于 **选择框组件** 的标准组件。
+- **基于**: NutUI `nut-picker-item` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、内置必填校验标识、支持 v-model 双向绑定、支持标签位置自定义、支持占位符提示、支持禁用/只读状态、内置多级提示信息、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 选择框组件
+
+> 💡 **关键原则**: 在所有 选择框组件 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 输入值，双向绑定 | String | - |
+| `placeholder` | 为空时占位符 | String | - |
+| `clearable` | 展示清除icon | Boolean | true |
+| `text-align` | 文本位置,可选值left,center,right | String | left |
+| `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 | - |
+| `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" |
+| `value-key` | 指定异构数据源的value key | String | "value" |
+| `children-key` | 指定异构数据源的children key | String | "children" |
+| `teleport` | 指定挂载节点 | String | "body" |
+| `close-on-click-overlay` | 点击蒙层是否关闭对话框 | Boolean | false |
+| `lock-scroll` | 背景是否锁定 | Boolean | false |
+| `three-dimensional` | 是否开启3D效果 | Boolean | true |
+| `swipe-duration` | 惯性滚动时长 | Number、String | 1000 |
+| `visible-item-count` | 可见item数量必须为奇数 | Number、String | 7 |
+| `separator` | 分割符 | String |   |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 输入内容时触发 | val, item |
+| `focus` | 聚焦时触发 | val |
+| `blur` | 失焦时触发 | val |
+| `clear` | 点击清空时触发 | val |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | label内容 |
+| `prepend` | 左侧自定义内容 |
+| `append` | 右侧自定义内容 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+### 基础用法
+常用属性与事件
+```html
+<fox-picker-item v-model="val" :source="m_str_items" @change="onChange" @focus="onFocus" @blur="onBlur">选择框</fox-picker-item>
+<fox-picker-item v-model="val2" :source="m_items" :is-required="m_required">必输</fox-picker-item>
+<fox-picker-item v-model="val3" :source="m_str_multi_items" :readonly="m_readonly">只读</fox-picker-item>
+<fox-picker-item v-model="val4" :source="m_str_multi_items" :disabled="m_disabled">禁用</fox-picker-item>
+<fox-picker-item v-model="val14" :source="m_str_multi_items" :three-dimensional="false">平铺样式</fox-picker-item>
+```
+```javascript
+export default createDemo({
+  setup() {
+    // 数据
+    const data = reactive({
+      m_str_items: ['南京', '无锡', '海北藏族自治区', '北京', '连云港', '浙江省', '江苏省'],
+      m_items: [
+        { text: '南京', value: '01' },
+        { text: '无锡', value: '02' },
+        { text: '海北藏族自治区', value: '03' },
+        { text: '北京', value: '04' },
+        { text: '连云港', value: '05' },
+        { text: '浙江省', value: '06' },
+        { text: '江苏省', value: '07' }
+      ],
+      m_str_multi_items: [
+        ['周一', '周二', '周三', '周四', '周五'],
+        ['上午', '下午', '晚上']
+      ],
+      val: '浙江省',
+      val2: '',
+      val3: ['周三', '晚上'],
+      val4: ['周五', '下午'],
+      val14: null,
+      m_disabled: true,
+      m_readonly: true,
+      m_required: true,
+    })
+     // 方法
+    const methods = {
+      onChange: (value: string | number, event: Event) => {
+        console.log('change: ', value, event)
+      },
+      onFocus: (value: string | number, event: Event) => {
+        console.log('focus:', value, event)
+      },
+      onBlur: (value: string | number, event: Event) => {
+        console.log('blur:', value, event)
+      },
+      onClear: (value: string | number) => {
+        console.log('clear:', value)
+      }
+    }
+    return {
+      ...toRefs(data),
+      ...methods
+    };
+  }
+});
+```
+### 多列样式
+根据不同的数据源格式，select组件分为单列、多列和级联
+```html
+<fox-picker-item v-model="val5" :source="m_items">单列</fox-picker-item>
+<fox-picker-item v-model="val6" :source="m_func">多列</fox-picker-item>
+<fox-picker-item v-model="val7" :source="m_address">级联</fox-picker-item>
+```
+```javascript
+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_items: [
+        { text: '南京', value: '01' },
+        { text: '无锡', value: '02' },
+        { text: '海北藏族自治区', value: '03' },
+        { text: '北京', value: '04' },
+        { text: '连云港', value: '05' },
+        { text: '浙江省', value: '06' },
+        { text: '江苏省', value: '07' }
+      ],
+       m_func: (): Promise<unknown> => {
+        return new Promise(resolve => {
+          resolve(m_multi_items)
+        })
+      },
+      val5: '03',
+      val6: ['周五', '晚上'],
+      val7: [],
+    })
+    return {
+      ...toRefs(data),
+    };
+  }
+});
+```
+### 返回类型
+通过属性value-type设置v-model的数据类型，分别为text，value(默认)和item
+```html
+<fox-picker-item v-model="val8" :source="m_items">value</fox-picker-item>
+<fox-picker-item v-model="val9" :source="m_func" value-type="text">text</fox-picker-item>
+<fox-picker-item v-model="val10" :source="m_address" value-type="item">item</fox-picker-item>
+```
+```javascript
+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_items: [
+        { text: '南京', value: '01' },
+        { text: '无锡', value: '02' },
+        { text: '海北藏族自治区', value: '03' },
+        { text: '北京', value: '04' },
+        { text: '连云港', value: '05' },
+        { text: '浙江省', value: '06' },
+        { text: '江苏省', value: '07' }
+      ],
+       m_func: (): Promise<unknown> => {
+        return new Promise(resolve => {
+          resolve(m_multi_items)
+        })
+      },
+      val8: '医生',
+      val9: '',
+      val10: [],
+    })
+    return {
+      ...toRefs(data),
+    };
+  }
+});
+```
+### 数据源
+
+选择组件的数据源支持`数组`, `函数`, `服务API`和`异构`(需要配合`text-key`和`value-key`两个属性)，另外可以通过`source-filter`属性对数据源进行最终的过滤（一般配合`服务API数据源`使用）
+
+```vue
+<!--
+ * @Author: 江成
+ * @Date: 2022-11-28 19:07:56
+-->
+<script lang="ts" setup>
+import { ref, watch, computed } from 'vue'
+import { setAPI } from '@/api'
+
+// 注册api代理函数，模拟api请求
+setAPI('select', (path: string, params: any) => {
+  console.info(`处理select获取数据请求, path:${path} params:`, params)
+  if (path === 'provide') {
+    return new Promise<any>(resolve => {
+      setTimeout(() => {
+        resolve([
+          { text: '广东省', value: 'a' },
+          { text: '江苏省', value: 'b' },
+          { text: '浙江省', value: 'c' },
+          { text: '福建省', value: 'd' },
+          { text: '四川省', value: 'e' },
+          { text: '云南省', value: 'f' }
+        ])
+      }, 500)
+    })
+  } else {
+    return new Promise<any>(resolve => {
+      setTimeout(() => {
+        resolve([
+          { text: '南京', value: '01' },
+          { text: '无锡', value: '02' },
+          { text: '苏州', value: '03' },
+          { text: '无锡', value: '04' },
+          { text: '台州', value: '05' },
+          { text: '杭州', value: '06' },
+          { text: '宁波', value: '07' }
+        ])
+      }, 500)
+    })
+  }
+})
+
+// 数组数据源
+const sourceForArray = ref([
+  { text: '南京', value: '01' },
+  { text: '无锡', value: '02' },
+  { text: '海北藏族自治区', value: '03' },
+  { text: '北京', value: '04' },
+  { text: '连云港', value: '05' },
+  { text: '浙江省', value: '06' },
+  { text: '江苏省', value: '07' }
+])
+// 函数数据源
+const sourceForFunction = async (params: any) => {
+  console.info('函数处理数据源, params:', params)
+  return sourceForArray.value
+}
+// 异构数据源
+const sourceForOtherType = ref([
+  {
+    id: '001',
+    name: '刘德华'
+  },
+  {
+    id: '002',
+    name: '黎明'
+  },
+  {
+    id: '003',
+    name: '张学友'
+  },
+  {
+    id: '004',
+    name: '郭富城'
+  }
+])
+
+// model value
+const val = ref('01')
+const val2 = ref('02')
+const val3 = ref('05')
+const val4 = ref({
+  id: '002',
+  name: '黎明'
+})
+
+watch(val4, newVal => {
+  console.info('------ val4 change', newVal)
+})
+
+// 省份value
+const val5 = ref('')
+// source filter
+const sourceFilter = (item: Record<string, any>) => {
+  if (isCoastalRegion.value) {
+    return ['a', 'b', 'c', 'd'].includes(item.value)
+  } else {
+    return ['e', 'f'].includes(item.value)
+  }
+}
+// source filter
+// 是否沿海省份
+const isCoastalRegion = ref(true)
+// coastal region text
+const coastalRegionText = computed(() => {
+  return isCoastalRegion.value ? '沿海省份' : '内地省份'
+})
+</script>
+
+<template>
+  <fox-group column="3">
+    <fox-picker-item v-model="val" :source="sourceForArray">数组</fox-picker-item>
+    <fox-picker-item v-model="val2" :source="sourceForFunction">函数</fox-picker-item>
+    <fox-picker-item v-model="val3" source="city">API</fox-picker-item>
+    <fox-picker-item v-model="val4" :source="sourceForOtherType" value-type="item" text-key="name" value-key="id"
+      >异构
+    </fox-picker-item>
+    <fox-picker-item v-model="val5" source="provide" :source-filter="sourceFilter">省份</fox-picker-item>
+    <fox-switch-item v-model="isCoastalRegion">{{ coastalRegionText }}</fox-switch-item>
+  </fox-group>
+</template>
+
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 PickerItem 配合使用的相关组件
+- **fox-group**: 与 PickerItem 配合使用的相关组件
+- **fox-switch-item**: 与 PickerItem 配合使用的相关组件
+

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

@@ -0,0 +1,70 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Popover 组件使用规范
+impact: HIGH
+type: capability
+description: 气泡弹出框
+tags: [foxui, fox-popover, FoxPopover]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-button","fox-icon"]
+---
+
+# Popover 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Popover 是 foxui 中用于 **气泡弹出框** 的标准组件。
+- **基于**: NutUI `nut-popover` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持禁用/只读状态、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 气泡弹出框
+
+> 💡 **关键原则**: 在所有 气泡弹出框 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `list` | 选项列表 | List |  |
+| `visible` | 是否展示气泡弹出层 | boolean | false |
+| `theme` | 主题风格，可选值为 dark | string | light |
+| `location` | 弹出位置，可选值为 top,left,right | string | bottom |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `choose` | 点击选项时触发 |
+| `open` | 打开菜单时触发 |
+| `close` | 关闭菜单时触发 |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `content` | 自定义气泡组件菜单内容 |
+| `reference` | 触发 Popover 显示的元素内容 |
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Popover 配合使用的相关组件
+- **fox-button**: 与 Popover 配合使用的相关组件
+- **fox-icon**: 与 Popover 配合使用的相关组件
+

package/foxui/references/fox-popover-dialog/doc.md

@@ -0,0 +1,113 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: PopoverDialog 组件使用规范
+impact: HIGH
+type: capability
+description: Popover弹出框
+tags: [foxui, fox-popover-dialog, FoxPopoverDialog]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js"]
+---
+
+# PopoverDialog 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+PopoverDialog 是 foxui 中用于 **Popover弹出框** 的标准组件。
+- **基于**: NutUI `nut-popover-dialog` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: Popover弹出框
+
+> 💡 **关键原则**: 在所有 Popover弹出框 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `visible` | 是否展示气泡弹出层 | boolean | false |
+| `reference` | 相关组件 | any |
+| `referenceInset` | 相关组件inset | any |
+| `width` | 弹出宽度 | string |
+| `offset` | 弹框偏移量 | string |
+| `placement` | 弹出位置，可选值为 top,top-start, top-end,left,left-start,left-end,right,right-start,right-end,bottom,bottom-start,bottom-end | string | bottom-start |
+| `auto-fit` | 是否自定调整位置 | boolean | true |
+| `title` | 标题 | string |
+| `effect` | 主题风格，可选值为 dark | string | light |
+| `show-arrow` | 是否显示arrow | boolean |
+| `arrow-size` | 箭头size | number | 14 |
+| `arrow-offset` | 箭头offset | number | 20 |
+| `show-overlay` | 是否显示overlay | boolean | false |
+| `close-on-click` | 点击关闭 | boolean | true |
+| `z-index` | z-index | string |
+| `custom-class` | 自定义class | string |
+| `custom-style` | 自定义style | Object |
+| `leave-hide` | 鼠标离开隐藏 | boolean |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `title` | 自定义气泡组件标题内容 |
+| `default` | 自定义气泡组件内容 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 主题风格
+
+Popover 支持明朗和暗黑两种风格，默认为明朗风格，将 effect 属性设置为 dark 可切换为暗黑风格。
+
+
+:::demo
+
+popoverdialog/demo_effect
+
+:::
+
+
+### 位置自定义
+
+支持 top, top-start, top-end, bottom, bottom-start, bottom-end, left, left-start, left-end , right, right-start, right-end 12种弹出位置，默认值为 bottom。
+
+
+:::demo
+
+popoverdialog/demo_placement
+
+:::
+
+### 自定义内容
+
+可以通过插槽自定义内容
+
+:::demo
+
+popoverdialog/demo_custom
+
+:::
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 PopoverDialog 配合使用的相关组件
+

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

@@ -0,0 +1,88 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Popup 组件使用规范
+impact: HIGH
+type: capability
+description: 弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示
+tags: [foxui, fox-popup, FoxPopup]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-cell"]
+---
+
+# Popup 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Popup 是 foxui 中用于 **弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示** 的标准组件。
+- **基于**: NutUI `nut-popup` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示
+
+> 💡 **关键原则**: 在所有 弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model:visible` | 控制当前组件显示/隐藏 | boolean | false |
+| `z-index` | 遮罩层级 | string \ | number |
+| `duration` | 组件显示/隐藏的动画时长，单位秒 | string \ | number |
+| `lock-scroll` | 背景是否锁定 | boolean | true |
+| `overlay` | 是否显示遮罩 | boolean | true |
+| `close-on-click-overlay` | 是否点击遮罩关闭 | boolean | true |
+| `position` | 弹出位置（top,bottom,left,right,center） | string | "center" |
+| `transition` | 动画名 | string | - |
+| `style` | 自定义弹框样式 | CSSProperties | - |
+| `pop-class` | 自定义弹框类名 | string | - |
+| `closeable` | 是否显示关闭按钮 | boolean | false |
+| `close-icon-position` | 关闭按钮位置（top-left,top-right,bottom-left,bottom-right） | string | "top-right" |
+| `destroy-on-close` | 弹层关闭后 slot内容会不会清空 | boolean | true |
+| `round` | 是否显示圆角 | boolean | false |
+| `teleport` | 指定挂载节点 | string | "body" |
+| `teleport-disable` | 是否允许挂载节点 | boolean | false |
+| `overlay-class` | 自定义遮罩层类名 | string | '' |
+| `overlay-style` | 自定义遮罩层样式 | string | '' |
+| `safe-area-inset-bottom` | 是否开启 iphone 系列全面屏底部安全区适配,仅当 position 为 bottom 时有效 | boolean | false |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `click-pop` | 点击弹出层时触发 | event: Event |
+| `click-close-icon` | 点击关闭图标时触发 | event: Event |
+| `open` | 打开弹框时触发 | - |
+| `close` | 关闭弹框时触发 | - |
+| `opend` | 遮罩打开动画结束时触发 | event: Event |
+| `closed` | 遮罩关闭动画结束时触发 | event: Event |
+| `click-overlay` | 点击遮罩触发 | event: Event |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | 自定义内嵌内容 |
+| `close-icon` | 关闭按钮的自定义图标 |
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Popup 配合使用的相关组件
+- **fox-cell**: 与 Popup 配合使用的相关组件
+