@fox-js/phone-skills 4.0.1-0

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

@@ -0,0 +1,67 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Price 组件使用规范
+impact: HIGH
+type: capability
+description: 价格组件
+tags: [foxui, fox-price, FoxPrice]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js"]
+---
+
+# Price 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Price 是 foxui 中用于 **价格组件** 的标准组件。
+- **基于**: NutUI `nut-price` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、适配 H5 与小程序多端
+- **适用场景**: 价格组件
+
+> 💡 **关键原则**: 在所有 价格组件 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `price` | 价格数量 | Number | 0 |
+| `need-symbol` | 是否需要加上 symbol 符号 | Boolean | true |
+| `symbol` | 符号类型 | String | yen; |
+| `decimal-length` | 小数位位数 | Number | 2 |
+| `digits` | 分块长度，0的时候不分块 | Number | 3 |
+| `separator` | 分块分割符 | String | , |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+无
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Price 配合使用的相关组件
+

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

@@ -0,0 +1,74 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Progress 组件使用规范
+impact: HIGH
+type: capability
+description: 用来展示进度
+tags: [foxui, fox-progress, FoxProgress]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-cell"]
+---
+
+# Progress 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Progress 是 foxui 中用于 **用来展示进度** 的标准组件。
+- **基于**: NutUI `nut-progress` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 用来展示进度
+
+> 💡 **关键原则**: 在所有 用来展示进度 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `percentage` | 百分比 | Number | 0 |
+| `is-show-percentage` | 是否需要展示百分号 | Boolean | true |
+| `stroke-color` | 进度条背景色 | String | f30 |
+| `stroke-width` | 进度条宽度 | String | '' |
+| `size` | 进度条及文字尺寸，可选值small/base/large | String | - |
+| `show-text` | 是否显示进度条文字内容 | Boolean | true |
+| `text-inside` | 进度条文字显示位置false:外显，true:内显 | Boolean | false |
+| `text-color` | 进度条文字颜色设置 | String | 333 |
+| `text-background` | 进度条文字背景颜色设置 | String | 同进度条颜色 |
+| `status` | 进度条当前状态,active展示动画效果/icon展示icon标签 | String | text |
+| `icon-name` | icon名称 | String | checked |
+| `icon-color` | icon颜色 | String | 439422 |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `icon-name` | 右侧 icon 内容 |
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Progress 配合使用的相关组件
+- **fox-cell**: 与 Progress 配合使用的相关组件
+

package/foxui/references/fox-pull-refresh/doc.md

@@ -0,0 +1,77 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: PullRefresh 组件使用规范
+impact: HIGH
+type: capability
+description: 在列表中通过手指下拉刷新加载新内容的交互操作
+tags: [foxui, fox-pull-refresh, FoxPullRefresh]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-page","fox-content","fox-group","fox-row-item"]
+---
+
+# PullRefresh 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+PullRefresh 是 foxui 中用于 **在列表中通过手指下拉刷新加载新内容的交互操作** 的标准组件。
+- **基于**: NutUI `nut-pull-refresh` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持插槽扩展自定义内容
+- **适用场景**: 在列表中通过手指下拉刷新加载新内容的交互操作
+
+> 💡 **关键原则**: 在所有 在列表中通过手指下拉刷新加载新内容的交互操作 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 是否触发下拉刷新 | boolean | false |
+| `pull-distance` | 触发下拉刷新的距离 | number \ | string |
+| `head-height` | 顶部内容高度 | number \ | string |
+| `loading-icon` | 加载中状态时，loading 图标。为空表示去掉 | string | loading |
+| `pulling-text` | 下拉过程提示文案 | string | 下拉刷新 |
+| `loosing-text` | 释放过程提示文案 | string | 释放刷新 |
+| `loading-text` | 加载过程提示文案 | string | 加载中... |
+| `duration` | 下拉动画加载时长 | number | 0.3 |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 下拉过程或状态改变时触发 | status:string,distance:number |
+| `refresh` | 下拉刷新事件回调 | - |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `pulling` | 下拉过程的顶部内容 |
+| `loosing` | 释放过程中顶部内容 |
+| `loading` | 加载过程中顶部内容 |
+| `default` | 自定义内容 |
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 PullRefresh 配合使用的相关组件
+- **fox-page**: 与 PullRefresh 配合使用的相关组件
+- **fox-content**: 与 PullRefresh 配合使用的相关组件
+- **fox-group**: 与 PullRefresh 配合使用的相关组件
+- **fox-row-item**: 与 PullRefresh 配合使用的相关组件
+

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

@@ -0,0 +1,384 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: RadioItem 组件使用规范
+impact: HIGH
+type: capability
+description: 单选按钮组
+tags: [foxui, fox-radio-item, FoxRadioItem]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-item","fox-row-item","fox-button","fox-group","fox-switch-item"]
+---
+
+# RadioItem 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+RadioItem 是 foxui 中用于 **单选按钮组** 的标准组件。
+- **基于**: NutUI `nut-radio-item` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、内置必填校验标识、支持 v-model 双向绑定、支持标签位置自定义、支持禁用/只读状态、内置多级提示信息、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 单选按钮组
+
+> 💡 **关键原则**: 在所有 单选按钮组 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `disabled` | 是否禁用选择 | boolean | false |
+| `icon-size` | 图标尺寸 | string \ | number |
+| `label` | 单选框标识 | string \ | number \ |
+| `shape` | 形状，可选值为 button、round | string | round |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 值变化时触发 | 当前选中项值（value）设置value后有值、默认为空 |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+| `clear` | 清空radio-group得选中状态 | - |
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `options` | source为空的情况下，直接编写radio列表 |
+| `default` | label |
+| `text` | 自定义radio项的text内容 |
+| `icon` | 默认图标 |
+| `checkedIcon` | 选中图标 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+### 左侧位置
+使用`v-model`绑定值当前选项的`value`, 并且通过`source`属性设置radio列表, 并可通过`text-position`设置label的位置
+```html
+<fox-radio-item v-model="val" :source="m_items" text-position="left"></fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+const val = ref('1')
+const m_items = ref([
+  { text: '单选框1', value: '1' },
+  { text: '单选框2', value: '2' },
+  { text: '单选框3', value: '3' }
+])
+```
+### 右侧位置
+通过`text-position`设置label的位置
+```html
+ <fox-radio-item v-model="val" :source="m_items"></fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+const val = ref('1')
+const m_items = ref([
+  { text: '单选框1', value: '1' },
+  { text: '单选框2', value: '2' },
+  { text: '单选框3', value: '3' }
+])
+```
+### 按钮形状
+通过`shape`设置radio item的外形
+```html
+ <fox-radio-item v-model="val" :source="m_items" shape="button"> </fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+const val = ref('1')
+const m_items = ref([
+  { text: '单选框1', value: '1' },
+  { text: '单选框2', value: '2' },
+  { text: '单选框3', value: '3' }
+])
+```
+### 水平布局
+通过设置`direction`属性来达到水平布局的效果
+```html
+<fox-radio-item v-model="val" :source="m_items" direction="horizontal" text-position="left"></fox-radio-item>
+<fox-radio-item v-model="val" :source="m_items" direction="horizontal"></fox-radio-item>
+<fox-radio-item v-model="val" :source="m_items" shape="button" direction="horizontal"></fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+const val = ref('1')
+const m_items = ref([
+  { text: '单选框1', value: '1' },
+  { text: '单选框2', value: '2' },
+  { text: '单选框3', value: '3' }
+])
+```
+### 自定义样式
+通过`icon-size`属性来控制图标的大小，另外通过插槽`icon`和`chekcedIcon`来设置自定义图标
+```html
+ <fox-radio-item v-model="val2" :source="m_items2" icon-size="12px"> </fox-radio-item>
+ <fox-radio-item v-model="val3" :source="m_items3">
+     <template v-slot:icon><Checklist></Checklist></template>
+     <template v-slot:checkedIcon><Checklist color="red"></Checklist></template>
+ </fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+import { Checklist } from '@fox-js/icons-vue'
+const val2 = ref('2')
+const m_items2 = ref([
+  { text: '自定义尺寸12', value: '1' },
+  { text: '自定义尺寸12', value: '2' }
+])
+const val3 = ref('1')
+const m_items3 = ref([
+  { text: '自定义图标', value: '1' },
+  { text: '自定义图标', value: '2' }
+])
+```
+### 只读/禁用
+通过`readonly`和`disabled`属性设置
+```html
+ <fox-radio-item v-model="val4" :source="m_items4" disabled="true"> </fox-radio-item>
+<fox-radio-item v-model="val4" :source="m_items4" readonly="true"> </fox-radio-item>
+```
+### 部分禁用选择
+```html
+ <fox-radio-item v-model="val5" :source="m_items5"></fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+const val5 = ref('')
+const m_items5 = ref([
+  { text: '部分禁用1', value: '1', disabled: true },
+  { text: '部分禁用2', value: '2' }
+])
+```
+### 返回类型
+通过fox-radio-item组件**value-type**设置v-model绑定的数据类型
+* `value`(默认) 绑定`item`对象的`item.value`
+* text 绑定item对象的item.text
+* item 绑定item对象
+### 返回value类型(默认)
+```html
+<fox-radio-item v-model="val6" :source="m_items6"></fox-radio-item>
+```
+```ts
+import {ref} from 'vue'
+const val6 = ref('1')
+const m_items6 = ref([
+  { text: '返回value1', value: '1' },
+  { text: '返回value2', value: '2' },
+  { text: '返回value3', value: '3' }
+])
+```
+### 返回text类型
+```html
+<fox-radio-item value-type="text" v-model="val8" :source="m_items8"></fox-radio-item>
+```
+```ts
+import {ref} from 'vue'
+const val7 = ref('返回text2')
+const m_items7 = ref([
+  { text: '返回text1', value: '1' },
+  { text: '返回text2', value: '2' },
+  { text: '返回text3', value: '3' }
+])
+```
+### 返回item类型
+```html
+ <fox-radio-item value-type="item" v-model="val8" :source="m_items8"></fox-radio-item>
+```
+```ts
+import { ref } from 'vue'
+const val8 = ref({ text: '返回Item3', value: '3' })
+const m_items8 = ref([
+  { text: '返回Item1', value: '1' },
+  { text: '返回Item2', value: '2' },
+  { text: '返回Item3', value: '3' }
+])
+```
+### 触发事件与方法
+点击fox-radio-item组件的radio能触发change事件
+```html
+<fox-radio-item ref="radioRef" v-model="val9" :source="m_items9" @change="handleChange"></fox-radio-item>
+<fox-item label-width="120px">
+  <template v-slot:label><span style="color: red">当前选择值:</span></template>
+  <template v-slot:default>{{ JSON.stringify(val9) }}</template>
+</fox-item>
+<fox-row-item>
+  <fox-button type="primary" @click="onClear">清理</fox-button>
+</fox-row-item>
+```
+```ts
+import { ref } from 'vue'
+const val9 = ref('1')
+const m_items9 = ref([
+  { text: '触发事件', value: '1' },
+  { text: '触发事件', value: '2' }
+])
+const handleChange = (value: any) => {
+  Toast.text(`您选中了${value}`)
+}
+const radioRef = ref<any>(null)
+// 清空选择状态
+const onClear = () => {
+  radioRef.value.clear()
+}
+```
+
+### 数据源
+
+通过属性`source`可以设置radio item的数据源，目前支持数组、函数和API服务三种数据源, 另外还支持异构(需要配合`text-key`和`value-key`两个属性)，另外可以通过`source-filter`属性对数据源进行最终的过滤（一般配合`服务API数据源`使用）
+
+```ts
+<script lang="ts" setup>
+import { ref, watch, computed } from 'vue'
+import { setAPI } from '@/api'
+
+// 注册api代理函数，模拟api请求
+setAPI('checkbox', (path: string, params: any) => {
+  console.info(`处理checkbox获取数据请求, 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'
+  }
+])
+// 函数数据源
+const sourceForFunction = (): Promise<Record<string, any>[]> => {
+  return new Promise<Record<string, any>[]>(resolve => {
+    resolve([
+      {
+        text: '足球',
+        value: 1
+      },
+      {
+        text: '篮球',
+        value: 2
+      },
+      {
+        text: '排球',
+        value: 3
+      }
+    ])
+  })
+}
+
+// 异构数据源
+const sourceForOtherType = ref([
+  {
+    id: '001',
+    name: '刘德华'
+  },
+  {
+    id: '002',
+    name: '黎明'
+  },
+  {
+    id: '003',
+    name: '张学友'
+  },
+  {
+    id: '004',
+    name: '郭富城'
+  }
+])
+
+let val = ref(['01'])
+let val2 = ref([1])
+let val3 = ref('')
+let val4 = ref('')
+watch([val, val2, val3, val4], ([newVal, newVal2, newVal3, newVal4]) => {
+  console.info('checkbox value change', newVal, newVal2, newVal3, newVal4)
+})
+
+// 省份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="1" label-width="150px">
+    <fox-radio-item v-model="val" :source="sourceForArray">数组数据源</fox-radio-item>
+    <fox-radio-item v-model="val2" :source="sourceForFunction">函数函数源</fox-radio-item>
+    <fox-radio-item v-model="val3" source="/metadata/city">API数据源</fox-radio-item>
+    <fox-radio-item v-model="val4" :source="sourceForOtherType" text-key="name" value-key="id"
+      >异构数据源</fox-radio-item
+    >
+    <fox-radio-item v-model="val5" source="provide" :source-filter="sourceFilter">省份</fox-radio-item>
+    <fox-switch-item v-model="isCoastalRegion">{{ coastalRegionText }}</fox-switch-item>
+  </fox-group>
+</template>
+
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 RadioItem 配合使用的相关组件
+- **fox-item**: 与 RadioItem 配合使用的相关组件
+- **fox-row-item**: 与 RadioItem 配合使用的相关组件
+- **fox-button**: 与 RadioItem 配合使用的相关组件
+- **fox-group**: 与 RadioItem 配合使用的相关组件
+- **fox-switch-item**: 与 RadioItem 配合使用的相关组件
+

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

@@ -0,0 +1,65 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Range 组件使用规范
+impact: HIGH
+type: capability
+description: 滑动输入条，用于在给定的范围内选择一个值。
+tags: [foxui, fox-range, FoxRange]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-cell"]
+---
+
+# Range 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Range 是 foxui 中用于 **滑动输入条，用于在给定的范围内选择一个值。** 的标准组件。
+- **基于**: NutUI `nut-range` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、支持禁用/只读状态、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 滑动输入条，用于在给定的范围内选择一个值。
+
+> 💡 **关键原则**: 在所有 滑动输入条，用于在给定的范围内选择一个值。 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+无
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 进度变化且结束拖动后触发 | value: number \ |
+| `drag-start` | 开始拖动时触发 | - |
+| `drag-end` | 结束拖动时触发 | - |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `button` | 自定义滑动按钮 |
+
+## 3. 例子 (Examples)
+
+
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Range 配合使用的相关组件
+- **fox-cell**: 与 Range 配合使用的相关组件
+