@fox-js/phone-skills 4.0.1-0

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

@@ -0,0 +1,499 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: ActionsheetItem 组件使用规范
+impact: HIGH
+type: capability
+description: 动作面板输入框
+tags: [foxui, fox-actionsheet-item, FoxActionsheetItem]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-group","fox-actionsheet-pane"]
+---
+
+# ActionsheetItem 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+ActionsheetItem 是 foxui 中用于 **动作面板输入框** 的标准组件。
+- **基于**: NutUI `nut-actionsheet-item` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、内置必填校验标识、支持 v-model 双向绑定、支持标签位置自定义、支持占位符提示、支持禁用/只读状态、内置多级提示信息、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 动作面板输入框
+
+> 💡 **关键原则**: 在所有 动作面板输入框 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `source` | 数据源 | Array,Function,String | - |
+| `visible` | 是否可见 | boolean | false |
+| `value-type` | 值的类型text:item.text,value:item.value,item:item | String | "value" |
+| `text-key` | 指定异构数据源的text key | String | "text" |
+| `sub-text-key` | 指定异构数据源的subtext key | String | "subText" |
+| `value-key` | 指定异构数据源的value key | String | "value" |
+| `disabled-key` | 指定异构数据源的disabled key | String | "disabled" |
+| `item-options` | option样式设置 | ItemOption | - |
+| `icon` | option icon | Component | - |
+| `checked-icon` | option checked icon | Component | - |
+| `icon-size` | option icon sze | Number | - |
+| `page-size` | 加载列表的大小 | Number | 10 |
+| `options-height` | 列表高度 | String | - |
+| `multiple` | 是否多选 | Boolean | false |
+| `visible` | 是否可见 | Boolean | false |
+| `close-on-click-overlay` | 点击overlay关闭 | Boolean | true |
+| `title` | 设置标题 | String | - |
+| `confirm-text` | 确定按钮文案 | String | 确定 |
+| `load-text` | 加载数据提示 | String | 加载中 |
+| `load-more-text` | 无更多数据提交 | String | 无更多数据 |
+| `is-auto-back-fill` | 是否自定回填 | Boolean | 是否点击回填单选 |
+| `show-searchbar` | 是否显示查询栏 | Boolean | 是否显示查询栏 |
+| `search-key` | 查询输入框字段 | String | keyword |
+| `seach-placeholder` | 查询输入框placeholder | String | - |
+| `search-delay-trigger-clear` | 查询输入框延时触发clear动作 | number | 250 |
+| `before-close` | 关闭前拦截函数返回false阻止动作面板关闭 | BeforeClose | - |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 输入内容时触发 | val, item |
+| `focus` | 聚焦时触发 | val |
+| `blur` | 失焦时触发 | val |
+| `clear` | 点击清空时触发 | val |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+| `search` | 触发查询动作 | params |
+| `clear` | 触发清空动作 | - |
+| `confirm` | 触发确认动作 | - |
+| `cancel` | 触发取消动作 | - |
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `title` | ActionSheet标题内容 |
+| `search` | ActionSheet查询栏内容 |
+| `option` | ActionSheet列表option内容 |
+| `optionLabel` | ActionSheet列表option内容 |
+| `optionIcon` | ActionSheet列表Icon内容 |
+| `buttons` | ActionSheet底部按钮 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基础用法
+
+
+```html
+  <fox-group title="基础用法" label-width="120px">
+    <fox-actionsheet-item v-model="data.val" :source="sourceForArray" title="天下五绝">基础 </fox-actionsheet-item>
+    <fox-actionsheet-item v-model="data.val2" :source="sourceForArray" title="天下五绝" disabled
+      >禁用
+    </fox-actionsheet-item>
+  </fox-group>
+
+```
+
+```ts
+import { reactive, ref, watch } from 'vue'
+
+// 本地数据源
+const sourceForArray = ref([
+  {
+    text: '黄老邪',
+    subText: '天下五绝:东邪，桃花岛主',
+    value: '01'
+  },
+  {
+    text: '欧阳锋',
+    subText: '天下五绝:西毒，西域白驼山庄庄主',
+    value: '02'
+  },
+  {
+    text: '一灯大师',
+    subText: '天下五绝:南帝，大理段氏“一阳指”自成一派',
+    value: '03'
+  },
+  {
+    text: '洪七公',
+    subText: '天下五绝:北丐，丐帮帮主',
+    value: '04'
+  },
+  {
+    text: '王重阳',
+    subText: '天下五绝:中神通，全真派创始祖师',
+    value: '05'
+  },
+  {
+    text: '郭靖',
+    subText: '他用一生来践行“侠之大者，为国为民”的精神',
+    value: '06'
+  },
+  {
+    text: '黄蓉',
+    subText: '集天地灵气于一身，艳绝天下、冰雪聪明、玲珑剔透、多才多艺、博古通今',
+    value: '07'
+  },
+  {
+    text: '江南七怪',
+    subText: '江南七怪是郭靖最重要的启蒙师父，还是郭靖成为“侠之大者”的引路者',
+    value: '08'
+  }
+])
+
+// 数据
+const data = reactive({
+  val: '03',
+  val2: '02'
+})
+
+```
+
+### 多选
+
+通过属性`multiple`设置多选
+
+```html
+  <fox-group title="多选" label-width="100px">
+    <fox-actionsheet-item v-model="data.val3" :source="sourceForArray" title="天下五绝" multiple
+      >多选
+    </fox-actionsheet-item>
+    <fox-actionsheet-item v-model="data.val4" :source="sourceForArray" title="多选" multiple
+      >多选(预选)
+    </fox-actionsheet-item>
+  </fox-group>
+
+```
+
+```ts
+import { reactive, ref, watch } from 'vue'
+
+// 本地数据源
+const sourceForArray = ref([
+  {
+    text: '黄老邪',
+    subText: '天下五绝:东邪，桃花岛主',
+    value: '01'
+  },
+  {
+    text: '欧阳锋',
+    subText: '天下五绝:西毒，西域白驼山庄庄主',
+    value: '02'
+  },
+  {
+    text: '一灯大师',
+    subText: '天下五绝:南帝，大理段氏“一阳指”自成一派',
+    value: '03'
+  },
+  {
+    text: '洪七公',
+    subText: '天下五绝:北丐，丐帮帮主',
+    value: '04'
+  },
+  {
+    text: '王重阳',
+    subText: '天下五绝:中神通，全真派创始祖师',
+    value: '05'
+  },
+  {
+    text: '郭靖',
+    subText: '他用一生来践行“侠之大者，为国为民”的精神',
+    value: '06'
+  },
+  {
+    text: '黄蓉',
+    subText: '集天地灵气于一身，艳绝天下、冰雪聪明、玲珑剔透、多才多艺、博古通今',
+    value: '07'
+  },
+  {
+    text: '江南七怪',
+    subText: '江南七怪是郭靖最重要的启蒙师父，还是郭靖成为“侠之大者”的引路者',
+    value: '08'
+  }
+])
+
+// 数据
+const data = reactive({
+  val3: '',
+  val4: ['01', '03']
+})
+
+```
+
+### 自动回填(单选)
+
+通过属性`is-auto-back-fill`设置点击后自动回填，要求必须为单选模式
+
+```html
+  <fox-group title="自动回填(单选)" label-width="100px">
+    <fox-actionsheet-item v-model="data.val5" :source="sourceForArray" title="自动回填(单选)" :is-auto-back-fill="true"
+      >回填
+    </fox-actionsheet-item>
+  </fox-group>
+
+```
+
+```ts
+import { reactive, ref, watch } from 'vue'
+
+// 本地数据源
+const sourceForArray = ref([
+  {
+    text: '黄老邪',
+    subText: '天下五绝:东邪，桃花岛主',
+    value: '01'
+  },
+  {
+    text: '欧阳锋',
+    subText: '天下五绝:西毒，西域白驼山庄庄主',
+    value: '02'
+  },
+  {
+    text: '一灯大师',
+    subText: '天下五绝:南帝，大理段氏“一阳指”自成一派',
+    value: '03'
+  },
+  {
+    text: '洪七公',
+    subText: '天下五绝:北丐，丐帮帮主',
+    value: '04'
+  },
+  {
+    text: '王重阳',
+    subText: '天下五绝:中神通，全真派创始祖师',
+    value: '05'
+  },
+  {
+    text: '郭靖',
+    subText: '他用一生来践行“侠之大者，为国为民”的精神',
+    value: '06'
+  },
+  {
+    text: '黄蓉',
+    subText: '集天地灵气于一身，艳绝天下、冰雪聪明、玲珑剔透、多才多艺、博古通今',
+    value: '07'
+  },
+  {
+    text: '江南七怪',
+    subText: '江南七怪是郭靖最重要的启蒙师父，还是郭靖成为“侠之大者”的引路者',
+    value: '08'
+  }
+])
+
+// 数据
+const data = reactive({
+  val5: ''
+})
+
+```
+
+### 返回类型
+
+通过属性value-type设置v-model的数据类型，分别为text，value(默认)和item
+
+```html
+  <fox-group title="返回类型" label-width="100px">
+    <fox-actionsheet-item v-model="data.val6" :source="sourceForArray" title="返回value">value </fox-actionsheet-item>
+    <fox-actionsheet-item v-model="data.val7" :source="sourceForArray" title="返回text" value-type="text"
+      >text
+    </fox-actionsheet-item>
+    <fox-actionsheet-item v-model="data.val8" :source="sourceForArray" title="返回item" value-type="item"
+      >item
+    </fox-actionsheet-item>
+  </fox-group>
+```
+
+```ts
+import { reactive, ref, watch } from 'vue'
+
+// 本地数据源
+const sourceForArray = ref([
+  {
+    text: '黄老邪',
+    subText: '天下五绝:东邪，桃花岛主',
+    value: '01'
+  },
+  {
+    text: '欧阳锋',
+    subText: '天下五绝:西毒，西域白驼山庄庄主',
+    value: '02'
+  },
+  {
+    text: '一灯大师',
+    subText: '天下五绝:南帝，大理段氏“一阳指”自成一派',
+    value: '03'
+  },
+  {
+    text: '洪七公',
+    subText: '天下五绝:北丐，丐帮帮主',
+    value: '04'
+  },
+  {
+    text: '王重阳',
+    subText: '天下五绝:中神通，全真派创始祖师',
+    value: '05'
+  },
+  {
+    text: '郭靖',
+    subText: '他用一生来践行“侠之大者，为国为民”的精神',
+    value: '06'
+  },
+  {
+    text: '黄蓉',
+    subText: '集天地灵气于一身，艳绝天下、冰雪聪明、玲珑剔透、多才多艺、博古通今',
+    value: '07'
+  },
+  {
+    text: '江南七怪',
+    subText: '江南七怪是郭靖最重要的启蒙师父，还是郭靖成为“侠之大者”的引路者',
+    value: '08'
+  }
+])
+
+// 数据
+const data = reactive({
+  val6: '',
+  val7: '',
+  val8: {
+    text: '王重阳',
+    subText: '天下五绝:中神通，全真派创始祖师',
+    value: '05'
+  }
+})
+
+// watch 返回value
+watch(
+  () => data.val6,
+  val => {
+    console.info('返回value:', val)
+  }
+)
+// watch 返回text
+watch(
+  () => data.val7,
+  val => {
+    console.info('返回text:', val)
+  }
+)
+// watch 返回value
+watch(
+  () => data.val8,
+  val => {
+    console.info('返回item:', val)
+  }
+)
+
+```
+
+### 数据源
+
+```html
+
+ <fox-group title="数据源" label-width="100px">
+    <fox-actionsheet-item v-model="data.val9" :source="sourceForArray" title="数组数据源"
+      >数组数据源</fox-actionsheet-item
+    >
+    <fox-actionsheet-item v-model="data.val10" :source="sourceForFunction" title="函数数据源"
+      >函数数据源
+    </fox-actionsheet-item>
+    <fox-actionsheet-item v-model="data.val11" source="/api/metadata/actionsheet" title="API数据源"
+      >API数据源
+    </fox-actionsheet-item>
+ </fox-group>
+
+```
+
+```ts
+import { reactive, ref, watch } from 'vue'
+import { setAPI } from '@/api/index'
+
+// 基础数据源
+const baseData = [
+  {
+    text: '程序员',
+    subText: 'IT民工，996人生',
+    value: '01'
+  },
+  {
+    text: '教师',
+    subText: '以教育为生的职业',
+    value: '02'
+  },
+  {
+    text: '医生',
+    subText: '挽救生命以治病为业的人',
+    value: '03'
+  }
+]
+
+// 函数数据源
+const sourceForFunction = async (index: number, pageSize: number, params?: any, first?: boolean) => {
+  const keyword = (params ?? {}).keyword
+  let data = baseData
+  if (typeof keyword === 'string' && keyword.length > 0) {
+    data = data.filter(item => {
+      return item.text.includes(keyword) || item.subText.includes(keyword)
+    })
+  }
+  let startIndex = (index - 1) * pageSize
+  let endIndex = startIndex + pageSize
+  if (endIndex > data.length) {
+    endIndex = data.length
+  }
+  const list = data.slice(startIndex, endIndex)
+  return {
+    totalSize: data.length,
+    page: list
+  }
+}
+
+// remote api数据源
+const remoteAPI = async (path: string, index: number, pageSize: number, params?: any, first?: boolean) => {
+  const keyword = (params ?? {}).keyword
+  let data = baseData
+  if (typeof keyword === 'string' && keyword.length > 0) {
+    data = data.filter(item => {
+      return item.text.includes(keyword) || item.subText.includes(keyword)
+    })
+  }
+  let startIndex = (index - 1) * pageSize
+  let endIndex = startIndex + pageSize
+  if (endIndex > data.length) {
+    endIndex = data.length
+  }
+  const list = data.slice(startIndex, endIndex)
+  return {
+    totalSize: data.length,
+    page: list
+  }
+}
+
+//模拟测试，设置一个临时的API数据源，实际环境应该访问服务获取
+setAPI('actionsheet', remoteAPI)
+
+
+// 数据
+const data = reactive({
+  val9: '',
+  val10: '',
+  val11: ''
+})
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 ActionsheetItem 配合使用的相关组件
+- **fox-group**: 与 ActionsheetItem 配合使用的相关组件
+- **fox-actionsheet-pane**: 与 ActionsheetItem 配合使用的相关组件
+

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

@@ -0,0 +1,66 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Animate 组件使用规范
+impact: HIGH
+type: capability
+description: 给页面元素添加动画效果
+tags: [foxui, fox-animate, FoxAnimate]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-button"]
+---
+
+# Animate 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Animate 是 foxui 中用于 **给页面元素添加动画效果** 的标准组件。
+- **基于**: NutUI `nut-animate` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装
+- **适用场景**: 给页面元素添加动画效果
+
+> 💡 **关键原则**: 在所有 给页面元素添加动画效果 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `type` | 动画类型，见下方 type 值说明 | string | - |
+| `action` | 触发方式，initial-初始化执行;  click-点击执行 | string | initial |
+| `loop` | 是否循环执行。true-循环执行; false-执行一次 | boolean | false |
+| `duration` | 动画时长，单位 ms | number \ | string |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `click` | 点击元素时触发 | event: Event |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+无
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Animate 配合使用的相关组件
+- **fox-button**: 与 Animate 配合使用的相关组件
+

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

@@ -0,0 +1,76 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Audio 组件使用规范
+impact: HIGH
+type: capability
+description: 音频播放器
+tags: [foxui, fox-audio, FoxAudio]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-voice","fox-audio-operate-group","fox-audio-operate"]
+---
+
+# Audio 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Audio 是 foxui 中用于 **音频播放器** 的标准组件。
+- **基于**: NutUI `nut-audio` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装
+- **适用场景**: 音频播放器
+
+> 💡 **关键原则**: 在所有 音频播放器 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `url` | 语音播放的连接 | String | '' |
+| `muted` | 是否静音 | Boolean | false |
+| `autoplay` | 是否自动播放 | Boolean | false |
+| `loop` | 是否循环播放 | Boolean | false |
+| `preload` | 是否预加载语音 | String | 'auto' |
+| `type` | 展示形式，可选值：controls 控制面板   progress 进度条  icon 图标 none 自定义 | String | 'progress' |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `fast-back` | 触发语音快退 | 返回当前播放时长（单位：毫秒） |
+| `forward` | 触发语音快进 | 返回当前播放时长（单位：毫秒） |
+| `play` | 触发播放/暂停语音 | 返回当前播放状态 |
+| `ended` | 语音播放完成，当 loop == false 时生效 | —— |
+| `mute` | 触发静音 | —— |
+| `change-progress` | 当进度条改变时触发 | 返回当前播放时长（单位：毫秒） |
+| `can-play` | 当可以播放媒体文件时触发 | event: Event |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+无
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Audio 配合使用的相关组件
+- **fox-voice**: 与 Audio 配合使用的相关组件
+- **fox-audio-operate-group**: 与 Audio 配合使用的相关组件
+- **fox-audio-operate**: 与 Audio 配合使用的相关组件
+

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

@@ -0,0 +1,70 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Avatar 组件使用规范
+impact: HIGH
+type: capability
+description: 头像
+tags: [foxui, fox-avatar, FoxAvatar]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-header","fox-avata","fox-badge","fox-avatar-group","fox-cell"]
+---
+
+# Avatar 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Avatar 是 foxui 中用于 **头像** 的标准组件。
+- **基于**: NutUI `nut-avatar` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 头像
+
+> 💡 **关键原则**: 在所有 头像 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `size` | 头像的大小，可选值为：large、normal、small，支持输入数字 | string \ | number |
+| `shape` | 头像的形状，可选值为：square、round  | string | round |
+| `color` | 字体颜色 | string | 666 |
+| `bg-color` | 背景色 | string | eee |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | 默认插槽，可放置图片、图标、文本等元素 |
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Avatar 配合使用的相关组件
+- **fox-header**: 与 Avatar 配合使用的相关组件
+- **fox-avata**: 与 Avatar 配合使用的相关组件
+- **fox-badge**: 与 Avatar 配合使用的相关组件
+- **fox-avatar-group**: 与 Avatar 配合使用的相关组件
+- **fox-cell**: 与 Avatar 配合使用的相关组件
+