@fox-js/phone-skills 4.0.1-0

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

@@ -0,0 +1,251 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Mapping 组件使用规范
+impact: HIGH
+type: capability
+description: 映射组件
+tags: [foxui, fox-mapping, FoxMapping]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-group","fox-item"]
+---
+
+# Mapping 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Mapping 是 foxui 中用于 **映射组件** 的标准组件。
+- **基于**: NutUI `nut-mapping` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持插槽扩展自定义内容
+- **适用场景**: 映射组件
+
+> 💡 **关键原则**: 在所有 映射组件 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `modelValue` | value/v-model | String/Boolean/Number | - |
+| `source` | 映射数据源 | String/Function/Array  | - |
+| `source-type` | 映射数据源类型 | String | mapping |
+| `params` | 参数配合api数据源 | String | - |
+| `text-key` | 数据源text键名 | String | text |
+| `value-key` | 数据源value键名 | String | value |
+| `children-key` | 数据源children键名 | String | children |
+| `tag` | 组件对应的标签 | String/Component | span |
+| `separator` | 多列数据使用的分割符 | String | - |
+| `empty-text` | 匹配不到时，显示的默认text | String | - |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | 内容 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基础用法+数组数据源
+ 设置`value`和`source`属性，组件把`value`值映射成`text`显示出来
+```html
+<script lang="ts" setup>
+import { ref } from 'vue'
+const source =[{text:'男', value:'01'}, {text:'女', value:"02"}]
+const value = ref('01')
+</script>
+<template>
+<fox-group column="2">
+  <fox-item>
+    <fox-mapping class="my-text" v-model="value" :source="source"></fox-mapping>
+  </fox-item>
+</fox-group>
+</template>
+<style lang="scss" scoped>
+.my-text{
+  color: #F00;
+  font-size: 20px;
+}
+</style>
+```
+### 多列数据+函数数据源
+`source`为多列数据源，并通过`separator`设置了分割符
+```html
+<script lang="ts" setup>
+import { ref } from 'vue'
+const sourceForFunction = async function(){
+  let startYear = 2010
+  const yearItems = []
+  for(let i=0; i<12; i++){
+    const cur = startYear+i
+    yearItems.push({
+      text:`${cur}年`, value:`${cur}`
+    })
+  }
+  let monthItems = []
+  for(let i=1; i<=12; i++){
+    let s = `${i}`
+    if(s.length ==1){
+      s = `0${s}`
+    }
+    monthItems.push({
+      text:`${s}月`, value:`${i}`
+    })
+  }
+  return  [yearItems, monthItems]
+}
+const value = ref(['2021','5'])
+</script>
+<template>
+<fox-group column="2">
+  <fox-item>
+    <fox-mapping class="my-text" v-model="value" :source="sourceForFunction" separator="-"></fox-mapping>
+  </fox-item>
+</fox-group>
+</template>
+<style lang="scss" scoped>
+.my-text{
+  color: #F00;
+  font-size: 20px;
+}
+</style>
+```
+### 级联数据+API数据源
+```html
+<script lang="ts" setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+import { setAPI } from '@/api'
+//模拟测试，设置一个临时的API数据源，实际环境应该访问服务获取
+setAPI('mapping',  async function(){
+  return  [
+        {
+          text: '浙江',
+          value: '01',
+          children: [
+            {
+              text: '杭州',
+              value: '0101',
+              children: [
+                { text: '西湖区', value: '010101' },
+                { text: '余杭区', value: '010102' }
+              ]
+            },
+            {
+              text: '温州',
+              value: '0102',
+              children: [
+                { text: '鹿城区', value: '010201' },
+                { text: '瓯海区', value: '010201' }
+              ]
+            }
+          ]
+        },
+        {
+          text: '福建',
+          value: '02',
+          children: [
+            {
+              text: '福州',
+              value: '0201',
+              children: [
+                { text: '鼓楼区', value: '020101' },
+                { text: '台江区', value: '020102' }
+              ]
+            },
+            {
+              text: '厦门',
+              value: '0202',
+              children: [
+                { text: '思明区', value: '020201' },
+                { text: '海沧区', value: '020201' }
+              ]
+            }
+          ]
+        }
+      ]
+})
+const value = ref(['01','0101','010101'])
+const value2 = ref<string[]>([])
+let timer:any = null
+onMounted(()=>{
+  let list = [['02','0201','020101'],['02','0202','020201']]
+  let i = 0
+  timer = setInterval(()=>{
+    let index = (i++)%list.length
+    value2.value = list[index]
+  },3000)
+})
+onUnmounted(()=>{
+  clearInterval(timer)
+})
+</script>
+<template>
+<fox-group column="2">
+  <fox-item>
+    <fox-mapping class="my-text" v-model="value" source="/api/city" ></fox-mapping>
+  </fox-item>
+  <fox-item>
+    <fox-mapping class="my-text2" v-model="value2" source="/api/city"></fox-mapping>
+  </fox-item>
+</fox-group>
+</template>
+<style lang="scss" scoped>
+.my-text{
+  color: #F00;
+  font-size: 20px;
+}
+.my-text2{
+  color: #00F;
+  font-size: 20px;
+}
+</style>
+```
+###  自定义插槽
+使用自定义插槽，对显示内容进行扩展
+```html
+<script lang="ts" setup>
+import { ref } from 'vue'
+const source = [
+  { text: '男', value: '01' },
+  { text: '女', value: '02' }
+]
+const value = ref('01')
+</script>
+<template>
+  <fox-group column="2">
+    <fox-item>
+      <fox-mapping v-model="value" :source="source">
+        <template v-slot:default="scope">
+          <span>{{ scope.value }}-{{ scope.text }}</span>
+        </template>
+      </fox-mapping>
+    </fox-item>
+  </fox-group>
+</template>
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Mapping 配合使用的相关组件
+- **fox-group**: 与 Mapping 配合使用的相关组件
+- **fox-item**: 与 Mapping 配合使用的相关组件
+

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

@@ -0,0 +1,425 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Menu 组件使用规范
+impact: HIGH
+type: capability
+description: 下拉菜单组件
+tags: [foxui, fox-menu, FoxMenu]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-menu-item","fox-button"]
+---
+
+# Menu 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Menu 是 foxui 中用于 **下拉菜单组件** 的标准组件。
+- **基于**: NutUI `nut-menu` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持禁用/只读状态、适配 H5 与小程序多端、支持主题定制
+- **适用场景**: 下拉菜单组件
+
+> 💡 **关键原则**: 在所有 下拉菜单组件 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `title` | 菜单项标题 | String | 当前选中项文字 |
+| `options` | 选项数组 | Array | - |
+| `disabled` | 是否禁用菜单 | Boolean | false |
+| `cols` | 可以设置一行展示多少列 options | Number | 1 |
+| `title-icon` | 自定义标题图标 | String | - |
+| `option-icon` | 自定义选项图标 | String | 'Check' |
+| `direction` | 菜单展开方向，可选值为up | String | 'down' |
+| `activeTitleClass` | 选项选中时自定义标题样式类 | String | - |
+| `inactiveTitleClass` | 选项非选中时自定义标题样式类 | String | - |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 选择 option 之后触发 | 选择的 value |
+| `toggle` | 切换菜单展示状态，传 true 为显示，false 为隐藏，不传参为取反 | show?: boolean |
+| `open` | 打开菜单栏时触发 | - |
+| `close` | 关闭菜单栏时触发 | - |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+无
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基础用法
+
+
+```html
+<template>
+  <fox-menu>
+    <fox-menu-item v-model="state.value1" :options="state.options1" />
+    <fox-menu-item v-model="state.value2" @change="handleChange" :options="state.options2" />
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue';
+
+export default {
+  setup() {
+    const state = reactive({
+      options1: [
+        { text: '全部商品', value: 0 },
+        { text: '新款商品', value: 1 },
+        { text: '活动商品', value: 2 }
+      ],
+      options2: [
+        { text: '默认排序', value: 'a' },
+        { text: '好评排序', value: 'b' },
+        { text: '销量排序', value: 'c' },
+      ],
+      value1: 0,
+      value2: 'a'
+    });
+
+    const handleChange = val => {
+      console.log('val', val);
+    }
+
+    return {
+      state,
+      handleChange
+    };
+  }
+}
+</script>
+```
+
+### 自定义菜单内容
+使用实例上的 toggle 方法可以手动关闭弹框。
+
+
+```html
+<template>
+  <fox-menu>
+    <fox-menu-item v-model="state.value1" :options="state.options1" />
+    <fox-menu-item title="筛选" ref="item">
+      <div :style="{display: 'flex', flex: 1, 'justify-content': 'space-between', 'align-items': 'center'}">
+        <div :style="{ marginRight: '10px'}">自定义内容</div>
+        <fox-button @click="onConfirm">确认</fox-button>
+      </div>
+    </fox-menu-item>
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue';
+
+export default {
+  setup() {
+    const state = reactive({
+      options1: [
+        { text: '全部商品', value: 0 },
+        { text: '新款商品', value: 1 },
+        { text: '活动商品', value: 2 }
+      ],
+      value1: 0
+    });
+
+    const item = ref('');
+
+    const onConfirm = () => {
+      item.value.toggle();
+    }
+
+    return {
+      state,
+      item,
+      onConfirm
+    };
+  }
+}
+</script>
+```
+
+
+### 一行两列
+
+```html
+<template>
+  <fox-menu>
+    <fox-menu-item v-model="state.value3" :cols="2" :options="state.options3" />
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue';
+
+export default {
+  setup() {
+    const state = reactive({
+      options3: [
+        { text: '全部商品', value: 0 },
+        { text: '家庭清洁/纸品', value: 1 },
+        { text: '个人护理', value: 2 },
+        { text: '美妆护肤', value: 3 },
+        { text: '食品饮料', value: 4 },
+        { text: '家用电器', value: 5 },
+        { text: '母婴', value: 6 },
+        { text: '数码', value: 7 },
+        { text: '电脑、办公', value: 8 },
+        { text: '运动户外', value: 9 },
+        { text: '厨具', value: 10 },
+        { text: '医疗保健', value: 11 },
+        { text: '酒类', value: 12 },
+        { text: '生鲜', value: 13 },
+        { text: '家具', value: 14 },
+        { text: '传统滋补', value: 15 },
+        { text: '汽车用品', value: 16 },
+        { text: '家居日用', value: 17 },
+      ],
+      value3: 0
+    });
+
+    return {
+      state
+    };
+  }
+}
+</script>
+```
+
+### 自定义选中态颜色
+
+
+```html
+<template>
+  <fox-menu active-color="green">
+    <fox-menu-item v-model="state.value1" :options="state.options1" />
+    <fox-menu-item v-model="state.value2" @change="handleChange" :options="state.options2" />
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue';
+
+export default {
+  setup() {
+    const state = reactive({
+      options1: [
+        { text: '全部商品', value: 0 },
+        { text: '新款商品', value: 1 },
+        { text: '活动商品', value: 2 }
+      ],
+      options2: [
+        { text: '默认排序', value: 'a' },
+        { text: '好评排序', value: 'b' },
+        { text: '销量排序', value: 'c' },
+      ],
+      value1: 0,
+      value2: 'a'
+    });
+
+    const handleChange = val => {
+      console.log('val', val);
+    }
+
+    return {
+      state,
+      handleChange
+    };
+  }
+}
+</script>
+```
+
+### 自定义图标
+
+
+```html
+<template>
+  <fox-menu>
+    <fox-menu-item v-model="state.value1" :options="state.options1" titleIcon="joy-smile" />
+    <fox-menu-item v-model="state.value2" @change="handleChange" :options="state.options2" optionIcon="checklist" />
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue';
+
+export default {
+  setup() {
+    const state = reactive({
+      options1: [
+        { text: '全部商品', value: 0 },
+        { text: '新款商品', value: 1 },
+        { text: '活动商品', value: 2 }
+      ],
+      options2: [
+        { text: '默认排序', value: 'a' },
+        { text: '好评排序', value: 'b' },
+        { text: '销量排序', value: 'c' },
+      ],
+      value1: 0,
+      value2: 'a'
+    });
+
+    const handleChange = val => {
+      console.log('val', val);
+    }
+
+    return {
+      state,
+      handleChange
+    };
+  }
+}
+</script>
+```
+
+
+### 向上展开
+
+
+```html
+<template>
+  <div class="blank"></div>
+  <fox-menu direction="up">
+    <fox-menu-item v-model="state.value1" :options="state.options1" />
+    <fox-menu-item v-model="state.value2" @change="handleChange" :options="state.options2" />
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue'
+
+export default {
+  setup() {
+    const state = reactive({
+      options1: [
+        { text: '全部商品', value: 0 },
+        { text: '新款商品', value: 1 },
+        { text: '活动商品', value: 2 }
+      ],
+      options2: [
+        { text: '默认排序', value: 'a' },
+        { text: '好评排序', value: 'b' },
+        { text: '销量排序', value: 'c' },
+      ],
+      value1: 0,
+      value2: 'a'
+    });
+
+    const handleChange = val => {
+      console.log('val', val);
+    }
+
+    return {
+      state,
+      handleChange
+    };
+  }
+}
+</script>
+<style>
+.blank {
+  width: 200px;
+  height: 200px;
+}
+</style>
+```
+
+### 禁用菜单
+
+```html
+<template>
+  <fox-menu>
+    <fox-menu-item disabled v-model="state.value1" :options="state.options1" />
+    <fox-menu-item disabled v-model="state.value2" @change="handleChange" :options="state.options2" />
+  </fox-menu>
+</template>
+
+<script>
+import { reactive, ref } from 'vue';
+
+export default {
+  setup() {
+    const state = reactive({
+      options1: [
+        { text: '全部商品', value: 0 },
+        { text: '新款商品', value: 1 },
+        { text: '活动商品', value: 2 }
+      ],
+      options2: [
+        { text: '默认排序', value: 'a' },
+        { text: '好评排序', value: 'b' },
+        { text: '销量排序', value: 'c' },
+      ],
+      options3: [
+        { text: '全部商品', value: 0 },
+        { text: '家庭清洁/纸品', value: 1 },
+        { text: '个人护理', value: 2 },
+        { text: '美妆护肤', value: 3 },
+        { text: '食品饮料', value: 4 },
+        { text: '家用电器', value: 5 },
+        { text: '母婴', value: 6 },
+        { text: '数码', value: 7 },
+        { text: '电脑、办公', value: 8 },
+        { text: '运动户外', value: 9 },
+        { text: '厨具', value: 10 },
+        { text: '医疗保健', value: 11 },
+        { text: '酒类', value: 12 },
+        { text: '生鲜', value: 13 },
+        { text: '家具', value: 14 },
+        { text: '传统滋补', value: 15 },
+        { text: '汽车用品', value: 16 },
+        { text: '家居日用', value: 17 },
+      ],
+      value1: 0,
+      value2: 'a',
+      value3: 0
+    });
+
+    const item = ref('');
+
+    const onConfirm = () => {
+      item.value.toggle();
+    }
+
+    const handleChange = val => {
+      console.log('val', val);
+    }
+
+    return {
+      state,
+      item,
+      onConfirm,
+      handleChange
+    };
+  }
+}
+</script>
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Menu 配合使用的相关组件
+- **fox-menu-item**: 与 Menu 配合使用的相关组件
+- **fox-button**: 与 Menu 配合使用的相关组件
+