@fox-js/phone-skills 4.0.1-0

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

@@ -0,0 +1,438 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: DatePicker 组件使用规范
+impact: HIGH
+type: capability
+description: 提供多个选型集合供用户选择,支持单列选择和多列级联,通常与弹出层配合使用
+tags: [foxui, fox-date-picker, FoxDatePicker]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-date-item","fox-group","fox-button"]
+---
+
+# DatePicker 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+DatePicker 是 foxui 中用于 **提供多个选型集合供用户选择,支持单列选择和多列级联,通常与弹出层配合使用** 的标准组件。
+- **基于**: NutUI `nut-date-picker` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 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**: 与 DatePicker 配合使用的相关组件
+- **fox-date-item**: 与 DatePicker 配合使用的相关组件
+- **fox-group**: 与 DatePicker 配合使用的相关组件
+- **fox-button**: 与 DatePicker 配合使用的相关组件
+

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

@@ -0,0 +1,242 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Dialog 组件使用规范
+impact: HIGH
+type: capability
+description: 模态对话框，在浮层中显示，引导用户进行相关操作，支持图片对话框。
+tags: [foxui, fox-dialog, FoxDialog]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-cell-group","fox-cell"]
+---
+
+# Dialog 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Dialog 是 foxui 中用于 **模态对话框，在浮层中显示，引导用户进行相关操作，支持图片对话框。** 的标准组件。
+- **基于**: NutUI `nut-dialog` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、适配 H5 与小程序多端、支持插槽扩展自定义内容
+- **适用场景**: 模态对话框，在浮层中显示，引导用户进行相关操作，支持图片对话框。
+
+> 💡 **关键原则**: 在所有 模态对话框，在浮层中显示，引导用户进行相关操作，支持图片对话框。 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+无
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `confirm` | 确定按钮回调 | Function |
+| `cancel` | 取消按钮回调 | Function |
+| `closed` | 关闭弹框回调 | Function |
+| `opened` | 打开弹框回调 | Function |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `header` | 自定义标题区域 |
+| `default` | 自定义内容 |
+| `footer` | 自定义底部按钮区域 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 函数调用（小程序模式暂不支持）
+```html
+<template>
+ <fox-cell-group title="函数式调用">
+  <fox-cell title="基础弹框" @click="baseClick"></fox-cell>
+  <fox-cell title="透明弹框" @click="transparentClick"></fox-cell>
+  <fox-cell title="支持富文本 html" @click="htmlClick"></fox-cell>
+  <fox-cell title="异步关闭" @click="beforeCloseClick"></fox-cell>
+  <fox-cell title="无标题弹框" @click="noTitleClick"></fox-cell>
+  <fox-cell title="提示弹框" @click="tipsClick"></fox-cell>
+  <fox-cell title="底部按钮 垂直调用" @click="verticalClick"></fox-cell>
+ </fox-cell-group>
+</template>
+<script lang="ts">
+import { ref,createVNode } from 'vue';
+import { Dialog } from '@nutui/nutui';
+export default {
+    setup() {
+        const onCancel = () => {
+          console.log('event cancel');
+        };
+        const onConfirm = () => {
+          console.log('event confirm');
+        };
+        const baseClick = (): void => {
+          Dialog({
+            title: '基础弹框',
+            content: createVNode('span', { style: { color: 'red' } }, '我可以是一个自定义组件'),
+            onCancel,
+            onConfirm
+          });
+        };
+        const transparentClick = (): void => {
+          Dialog({
+            overlayStyle: { background: 'rgba(0,0,0,0)' },
+            title: '透明弹框',
+            content: 'Content',
+            onCancel,
+            onConfirm
+          });
+        };
+        const htmlClick = (): void => {
+          Dialog({
+            title: "支持富文本 html",
+            content:
+              "<p style='color:red'>html</p><img src='./demo/img/hotsell.gif' />",
+            onCancel,
+            onConfirm
+          });
+        };
+        const beforeCloseClick = (): void => {
+          Dialog({
+            title: '异步关闭',
+            content: '点击确认后，1秒后关闭',
+            onCancel,
+            onConfirm,
+            beforeClose: (action: string) => {
+              return new Promise((r) => {
+                setTimeout(() => {
+                  r(action == 'confirm');
+                }, 1000);
+              });
+            }
+          });
+        };
+        const noTitleClick = () => {
+          Dialog({
+            content: '无标题弹框',
+            onCancel,
+            onConfirm
+          });
+        };
+        const tipsClick = () => {
+          Dialog({
+            title: '温馨提示',
+            content: '支持函数调用和组件调用两种方式。',
+            noCancelBtn: true,
+            onCancel,
+            onConfirm
+          });
+        };
+        const verticalClick = () => {
+          Dialog({
+            title: '温馨提示',
+            content: '支持底部按钮纵向排列。',
+            footerDirection: 'vertical',
+            onCancel,
+            onConfirm
+          });
+        };
+        return {
+          baseClick,
+          transparentClick,
+          htmlClick,
+          beforeCloseClick,
+          noTitleClick,
+          tipsClick,
+          verticalClick
+        };
+    }
+}
+</script>
+```
+## teleport 使用，挂载到指定节点
+``` html
+<fox-dialog teleport="#app" ... />
+```
+``` javascript
+Dialog({
+  teleport: '#app',
+  ...
+});
+Dialog({
+  teleport: '.demo',
+  ...
+});
+```
+### 函数调用 proxy.&dialog(...)
+```javascript
+import { ref } from 'vue';
+import { Dialog } from '@nutui/nutui';
+import { getCurrentInstance } from 'vue';
+export default {
+  setup() {
+    const { proxy } = getCurrentInstance();
+    proxy.$dialog({
+      title: '基础弹框',
+      content: '支持函数调用和组件调用两种方式。'
+    });
+  }
+}
+```
+### 标签式组件使用
+```html
+<template>
+  <fox-cell-group title="标签式使用">
+    <fox-cell title="组件调用" @click="componentClick"></fox-cell>
+    <fox-dialog
+      teleport="#app"
+      title="组件调用"
+      content="如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式。"
+      v-model:visible="visible"
+    >
+    </fox-dialog>
+    <fox-cell title="底部按钮 垂直使用" @click="componentvVrticalClick"></fox-cell>
+    <fox-dialog
+      footer-direction="vertical"
+      teleport="#app"
+      title="组件调用"
+      content="如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式。"
+      v-model:visible="visible1"
+    >
+    </fox-dialog>
+  </fox-cell-group>
+</template>
+<script lang="ts">
+import { ref } from 'vue';
+export default {
+  setup() {
+    const visible = ref(false);
+    const visible1 = ref(false);
+    const componentClick = () => {
+      visible.value = true;
+    };
+    const componentvVrticalClick = () => {
+      visible1.value = true;
+    };
+    return { visible,visible1,componentClick,componentvVrticalClick };
+  }
+}
+</script>
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Dialog 配合使用的相关组件
+- **fox-cell-group**: 与 Dialog 配合使用的相关组件
+- **fox-cell**: 与 Dialog 配合使用的相关组件
+