@fox-js/phone-skills 4.0.1-0

package/foxui/references/fox-count-up/doc.md

@@ -0,0 +1,178 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: CountUp 组件使用规范
+impact: HIGH
+type: capability
+description: 数字滚动组件，动态变化展示
+tags: [foxui, fox-count-up, FoxCountUp]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-countup","fox-button"]
+---
+
+# CountUp 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+CountUp 是 foxui 中用于 **数字滚动组件，动态变化展示** 的标准组件。
+- **基于**: NutUI `nut-count-up` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持禁用/只读状态、适配 H5 与小程序多端
+- **适用场景**: 数字滚动组件，动态变化展示
+
+> 💡 **关键原则**: 在所有 数字滚动组件，动态变化展示 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `init-num` | 初始数字 | Number | 0 |
+| `end-num` | 结束数字 | Number | 0 |
+| `speed` | 间隔数字，目前仅支持基本用法 | Number | 1 |
+| `to-fixed` | 保留小数点后几位 | Number | 以传入的数字为准 |
+| `start-flag` | 触发数字滚动的标识 | Boolean | true |
+| `during` | 滚动一次运行时间 | Number | 1000 |
+| `num-width` | 数字宽度，常用于自定义无缝滚动 | Number | 20 |
+| `num-height` | 数字高度，常用于自定义无缝滚动（抽奖功能必传） | Number | 20 |
+| `scrolling` | 用于数字滚动展示 | Boolean | false |
+| `custom` | 用于自定义图片数字滚动 | Boolean | false |
+| `custom-change-num` | 要变化的数字（用于自定义图片,initNum\endNum在此无效） | Number | 1 |
+| `custom-bg-img` | 自定义图片（建议使用雪碧图实现，使用抽奖功能必须使用雪碧图） | - | - |
+| `custom-spac-num` | 图片中数字之间可能会存在间距 | Number | 0 |
+| `type` | 使用抽奖功能必传“machine” | string | '' |
+| `machine-prize-num` | 奖品个数，一共多少个奖品，必传 | number | 4 |
+| `machine-num` | 抽奖位，即滚动几个，必传 | number | 3 |
+| `machine-prize-level` | 中奖图标，图标在雪碧图中的位置 | number | 0 |
+| `machine-trun-more` | 滚动圈数 | number | 0 |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `scroll-end` | 滚动结束后回调函数 | - |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+无
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+## 基本用法
+
+```html
+<fox-countup :init-num='0' :end-num='200'></fox-countup>
+
+<fox-countup :init-num='150.00' :end-num='0.00' :speed='2.62' :to-fixed='2'></fox-countup>
+
+<fox-countup :init-num='1000.00' :end-num='0.00' :speed='6.3' :start-flag='startNum' :to-fixed='2'></fox-countup>
+```
+
+## 数字滚动
+
+```html
+<fox-countup :scrolling="true" :init-num='17.618' :during="600"></fox-countup>
+```
+
+## 自定义数字图片展示
+
+```html
+<fox-countup
+    :custom-change-num="customNumber"
+    :custom-bg-img="bgImage"
+    :custom-spac-num="11"
+    :num-width="33"
+    :num-height="47"
+    :during="5000"
+>
+</fox-countup>
+```
+
+```javascript
+export default {
+    data() {
+        return {
+            customNumber: 618, 
+            bgImage: './demo/img/countup-number.png'
+        };
+    },
+    methods: {
+        run() {
+            let timer = null;
+            timer = setInterval(() => {
+                this.customNumber = Math.floor(Math.random() * (700 - 100 + 1) + 100);
+            }, 5000);
+        }
+    },
+    mounted() {
+        this.run();
+    }
+};
+```
+
+## 抽奖
+
+```html
+<fox-countup
+    ref="countup-machine"
+    type="machine"
+    :machine-num="machineNum"
+    :machine-prize-num="5"
+    :machine-prize-level="prizeLevel"
+    :custom-bg-img="bgImage"
+    :num-width="100"
+    :num-height="100"
+    :during="3000"
+    @scroll-end="scrollAniEnd"
+>
+</fox-countup>
+<fox-button @click="startRole" :disabled="startFlag">抽奖</fox-button>
+```
+
+```javascript
+export default {
+    data() {
+        return {
+            startFlag: false,
+            machineNum: 3,
+            bgImage: './demo/img/countup-icon.png',
+            prizeLevel: 0
+        };
+    },
+    methods: {
+        startRole() {
+            this.prizeLevel = Math.floor(Math.random() * 5 + 1);
+            this.startFlag = true;
+            this.$refs['countup-machine'].machineLuck();
+        },
+        scrollAniEnd() {
+            this.$toast.text('恭喜中奖！！！');
+            setTimeout(() => {
+                this.startFlag = false;
+            }, 300);
+        }
+    }
+};
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 CountUp 配合使用的相关组件
+- **fox-countup**: 与 CountUp 配合使用的相关组件
+- **fox-button**: 与 CountUp 配合使用的相关组件
+

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

@@ -0,0 +1,437 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: DateItem 组件使用规范
+impact: HIGH
+type: capability
+description: 日期组件
+tags: [foxui, fox-date-item, FoxDateItem]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-group","fox-button"]
+---
+
+# DateItem 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+DateItem 是 foxui 中用于 **日期组件** 的标准组件。
+- **基于**: NutUI `nut-date-item` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、内置必填校验标识、支持 v-model 双向绑定、支持标签位置自定义、支持占位符提示、支持禁用/只读状态、内置多级提示信息、支持插槽扩展自定义内容
+- **适用场景**: 日期组件
+
+> 💡 **关键原则**: 在所有 日期组件 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `date` | 日期类型（YYYY-MM-DD） |
+| `datetime` | 日期时间类型（YYYY-MM-DD HH:mm:ss） |
+| `time` | 时间类型（HH:mm:ss） |
+| `year-month` | 年月类型（YYYY-MM） |
+| `month-day` | 月天类型（MM-DD） |
+| `hour-minute` | 时分类型（HH-mm） |
+| `datehour` | 带小时的日期类型（YYYY-MM-DD HH） |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 输入内容时触发 | val ,event |
+| `focus` | 聚焦时触发 | val  ,event |
+| `blur` | 失焦时触发 | val ,event |
+| `clear` | 点击清空时触发 | val |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | 输入框标签内容 |
+| `prepend` | 输入框左侧内容 |
+| `append` | 输入框右侧内容 |
+| `top` | 弹出选择框顶部内容 |
+| `bottom` | 弹出选择框底部内容 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+### date类型
+```html
+<fox-date-item v-model="val">日期框</fox-date-item>
+<fox-date-item v-model="val2" :min-date="minDate" :max-date="maxDate" :value-format="formatTemplates.date">value格式化</fox-date-item>
+<fox-date-item v-model="val3" :value-format="formatTemplates.date" :format="formatTemplates.textDate">text格式化</fox-date-item>
+```
+```javascript
+export default createDemo({
+  // setup
+  setup() {
+    // 通用Format
+    const formatTemplates: Record<string, string> = {
+      date: 'YYYY-MM-DD',
+      textDate: 'YYYY年MM月DD日',
+      datetime: 'YYYY-MM-DD HH:mm:ss',
+      textDatetime: 'YYYY/MM/DD HH:mm:ss',
+      time: 'HH:mm:ss',
+      ['month-day']: 'MM-DD',
+      datehour: 'YYYY年MM月DD日 HH时'
+    }
+    const tody = new Date()
+    // 数据
+    const data = reactive({
+      minDate: new Date(2010, 0, 1),
+      maxDate: new Date(2050, 11, 31),
+      val: tody,
+      val2: DateUtils.format(tody, formatTemplates.date),
+      val3: '',
+    })
+    watch(
+      () => data.val,
+      newVal => {
+        console.info('val', newVal)
+      }
+    )
+    watch(
+      () => data.val2,
+      newVal => {
+        console.info('val2', newVal)
+      }
+    )
+    watch(
+      () => data.val3,
+      newVal => {
+        console.info('val3', newVal)
+      }
+    )
+    watch(
+      () => data.val10,
+      newVal => {
+        console.info('val10', newVal)
+      }
+    )
+    return {
+      formatTemplates,
+      ...toRefs(data)
+    }
+  }
+})
+```
+### datetime类型
+```html
+<fox-date-item type="datetime" v-model="val4">日期时间框</fox-date-item>
+<fox-date-item type="datetime" v-model="val5" :min-date="minDate" :max-date="maxDate"  :value-format="formatTemplates.datetime">value格式化</fox-date-item>
+<fox-date-item type="datetime" v-model="val6" :value-format="formatTemplates.datetime" :format="formatTemplates.textDatetime">text格式化</fox-date-item>
+```
+```javascript
+export default createDemo({
+  // setup
+  setup() {
+    // 通用Format
+    const formatTemplates: Record<string, string> = {
+      date: 'YYYY-MM-DD',
+      textDate: 'YYYY年MM月DD日',
+      datetime: 'YYYY-MM-DD HH:mm:ss',
+      textDatetime: 'YYYY/MM/DD HH:mm:ss',
+      time: 'HH:mm:ss',
+      ['month-day']: 'MM-DD',
+      datehour: 'YYYY年MM月DD日 HH时'
+    }
+    const tody = new Date()
+    // 数据
+    const data = reactive({
+      minDate: new Date(2010, 0, 1),
+      maxDate: new Date(2050, 11, 31),
+      val4: new Date(2020, 0, 1),
+      val5: '',
+      val6: '',
+    })
+    return {
+      formatTemplates,
+      ...toRefs(data)
+    }
+  }
+})
+```
+### time类型
+```html
+<fox-date-item type="time" v-model="val7" :value-format="formatTemplates.time" title="时间选择" :min-date="minDate" :max-date="maxDate">时间框</fox-date-item>
+<fox-date-item type="time" v-model="val8" :value-format="formatTemplates.time" title="时间选择" :min-date="minDate" :minute-step="5" :max-date="maxDate">步长时间框</fox-date-item>
+```
+```javascript
+export default createDemo({
+  // setup
+  setup() {
+    // 通用Format
+    const formatTemplates: Record<string, string> = {
+      date: 'YYYY-MM-DD',
+      textDate: 'YYYY年MM月DD日',
+      datetime: 'YYYY-MM-DD HH:mm:ss',
+      textDatetime: 'YYYY/MM/DD HH:mm:ss',
+      time: 'HH:mm:ss',
+      ['month-day']: 'MM-DD',
+      datehour: 'YYYY年MM月DD日 HH时'
+    }
+    const tody = new Date()
+    // 数据
+    const data = reactive({
+      minDate: new Date(2010, 0, 1),
+      maxDate: new Date(2050, 11, 31),
+      val7: '',
+      val8: '',
+    })
+    return {
+      formatTemplates,
+      ...toRefs(data)
+    }
+  }
+})
+```
+
+### year-month类型
+
+```html
+<fox-group title="year-month类型" label-width="120px">
+    <fox-date-item type="year-month" v-model="data.val8" :value-format="formatTemplates['year-month']" title="时间选择"
+      >时间选择</fox-date-item
+    >
+</fox-group>
+```
+
+```javascript
+export default createDemo({
+  // setup
+  setup() {
+    // 通用Format
+    const formatTemplates: Record<string, string> = {
+      date: 'YYYY-MM-DD',
+      textDate: 'YYYY年MM月DD日',
+      datetime: 'YYYY-MM-DD HH:mm:ss',
+      textDatetime: 'YYYY/MM/DD HH:mm:ss',
+      time: 'HH:mm:ss',
+      ['year-month']: 'YY-MM',
+      ['month-day']: 'MM-DD',
+      datehour: 'YYYY年MM月DD日 HH时'
+    }
+    const tody = new Date()
+    // 数据
+    const data = reactive({
+      minDate: new Date(2010, 0, 1),
+      maxDate: new Date(2050, 11, 31),
+      val8: ''
+    })
+    return {
+      formatTemplates,
+      ...toRefs(data)
+    }
+  }
+})
+
+
+```
+
+
+### month-day类型
+```html
+<fox-date-item type="month-day" v-model="val9" :value-format="formatTemplates['month-day']" title="时间选择">时间选择</fox-date-item>
+```
+```javascript
+export default createDemo({
+  // setup
+  setup() {
+    // 通用Format
+    const formatTemplates: Record<string, string> = {
+      date: 'YYYY-MM-DD',
+      textDate: 'YYYY年MM月DD日',
+      datetime: 'YYYY-MM-DD HH:mm:ss',
+      textDatetime: 'YYYY/MM/DD HH:mm:ss',
+      time: 'HH:mm:ss',
+      ['year-month']: 'YY-MM',
+      ['month-day']: 'MM-DD',
+      datehour: 'YYYY年MM月DD日 HH时'
+    }
+    const tody = new Date()
+    // 数据
+    const data = reactive({
+      minDate: new Date(2010, 0, 1),
+      maxDate: new Date(2050, 11, 31),
+      val9: ''
+    })
+    return {
+      formatTemplates,
+      ...toRefs(data)
+    }
+  }
+})
+```
+
+### datehour类型
+```html
+<fox-date-item type="datehour" v-model="val10" :value-format="formatTemplates['datehour']" title="时间选择">时间选择</fox-date-item>
+```  
+```javascript
+export default createDemo({
+  // setup
+  setup() {
+    // 通用Format
+    const formatTemplates: Record<string, string> = {
+      date: 'YYYY-MM-DD',
+      textDate: 'YYYY年MM月DD日',
+      datetime: 'YYYY-MM-DD HH:mm:ss',
+      textDatetime: 'YYYY/MM/DD HH:mm:ss',
+      time: 'HH:mm:ss',
+      ['month-day']: 'MM-DD',
+      datehour: 'YYYY年MM月DD日 HH时'
+    }
+    const tody = new Date()
+    // 数据
+    const data = reactive({
+      minDate: new Date(2010, 0, 1),
+      maxDate: new Date(2050, 11, 31),
+      val10: ''
+    })
+    watch(
+      () => data.val10,
+      newVal => {
+        console.info('val10', newVal)
+      }
+    )
+    return {
+      formatTemplates,
+      ...toRefs(data)
+    }
+  }
+})
+```
+
+### 自定义按钮
+```html
+<fox-date-item ref="dateRef" v-model="data.val11">
+    <template v-slot:default>日期框</template>
+    <template v-slot:bottom>
+      <fox-button block type="primary" @click="clearFunc">清空</fox-button>
+    </template>
+</fox-date-item>
+    
+```  
+```javascript
+
+<script lang="ts" setup>
+import { reactive, watch, ref } from 'vue'
+
+const data = reactive({
+  val12:''
+})
+
+const dateRef = ref<any>()
+const clearFunc = () => {
+  data.val11 = ''
+  dateRef.value?.hidePicker()
+}
+
+</script>
+
+```
+
+
+### 样式设置
+
+通过属性`three-dimensional`可设置是否开启3D效果 
+
+```html
+ <fox-date-item v-model="data.val14" :three-dimensional="false" :visible-item-count="13">平铺</fox-date-item>
+    
+```  
+```javascript
+
+<script lang="ts" setup>
+import { reactive, watch, ref } from 'vue'
+
+const data = reactive({
+  val14:''
+})
+
+</script>
+
+```
+
+### item格式化
+
+通过属性`dateItem-formatter`格式化picker item的格式
+
+```html
+ <fox-date-item v-model="data.val15" :is-show-chinese="false" :item-formatter="dateItemFormatter">格式化</fox-date-item>
+    
+```  
+
+```javascript
+
+<script lang="ts" setup>
+import { reactive, watch, ref } from 'vue'
+
+const data = reactive({
+  val15:''
+})
+
+// date item formatter
+const dateItemFormatter = (option: Record<string, any>): void => {
+  if (option.type === 'year') {
+    option.text = `${option.text} 年`
+  } else if (option.type === 'month') {
+    option.text = `${option.text} 月`
+  } else if (option.type === 'day') {
+    option.text = `${option.text} 日`
+  }
+}
+
+</script>
+
+```
+
+### item过滤
+
+通过属性`dateItem-filter`可以过滤那些item可显示，返回`false`代表不显示
+
+```html
+ <fox-date-item v-model="data.val16"  :item-filter="dateItemFilter">格式化</fox-date-item>
+    
+```  
+
+```javascript
+
+<script lang="ts" setup>
+import { reactive, watch, ref } from 'vue'
+
+const data = reactive({
+  val16:''
+})
+
+// date item filter（只显示偶数的年份）
+const dateItemFilter = (option: Record<string, any>): boolean => {
+  if (option.type === 'year') {
+    return option.value % 2 === 0
+  }
+  return true
+}
+
+</script>
+
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 DateItem 配合使用的相关组件
+- **fox-group**: 与 DateItem 配合使用的相关组件
+- **fox-button**: 与 DateItem 配合使用的相关组件
+