@fox-js/phone-skills 4.0.1-0

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

@@ -0,0 +1,346 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: Calendar 组件使用规范
+impact: HIGH
+type: capability
+description: 日历组件
+tags: [foxui, fox-calendar, FoxCalendar]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-cell"]
+---
+
+# Calendar 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+Calendar 是 foxui 中用于 **日历组件** 的标准组件。
+- **基于**: NutUI `nut-calendar` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 日历组件
+
+> 💡 **关键原则**: 在所有 日历组件 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 绑定值，日期选择 String 格式，区间选择 Array 格式 | String 、 Array | null |
+| `v-model:visible` | 是否可见 | Boolean | false |
+| `type` | 类型，日期选择'one'，区间选择'range' | String | 'one' |
+| `poppable` | 是否弹窗状态展示 | Boolean | true |
+| `is-auto-back-fill` | 自动回填 | Boolean | false |
+| `title` | 显示标题 | String | ‘日期选择’ |
+| `default-value` | 默认值，日期选择 String 格式，区间选择 Array 格式 | String 、 Array | null |
+| `start-date` | 开始日期， 如果不限制开始日期传 null | String | 今天 |
+| `end-date` | 结束日期，如果不限制结束日期传 null | String | 距离今天 365 天 |
+| `show-today` | 是否展示今天标记 | Boolean | true |
+| `start-text` | 范围选择，开始信息文案 | String | ’开始‘ |
+| `end-text` | 范围选择，结束信息文案 | String | ‘结束’ |
+| `confirm-text` | 底部确认按钮文案 | String | ’确认‘ |
+| `show-title` | 是否在展示日历标题 | Boolean | true |
+| `show-sub-title` | 是否展示日期标题 | Boolean | true |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `choose` | 选择之后或是点击确认按钮触发 | 日期数组（包含年月日和星期） |
+| `close` | 关闭时触发 | - |
+| `select` | 点击/选择后触发 | Day:object |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+| `scrollToDate` | 滚动到指定日期所在月,如：'2021-12-30' | string |
+| `initPosition` | 初始化滚动位置 | 无 |
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `btn` | 自定义日历标题下部，可用以添加自定义操作 |
+| `day` | 日期信息 |
+| `topInfo` | 日期顶部信息 |
+| `bottomInfo` | 日期底部信息 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基础用法
+
+```html
+<fox-cell
+  :showIcon="true"
+  title="选择单个日期"
+  :desc="date ? `${date} ${dateWeek}` : '请选择'"
+  @click="openSwitch('isVisible')"
+>
+</fox-cell>
+<fox-calendar
+  v-model:visible="isVisible"
+  :default-value="date"
+  @close="closeSwitch('isVisible')"
+  @choose="setChooseValue"
+  :start-date="`2019-10-11`"
+  :end-date="`2022-11-11`"
+>
+</fox-calendar>
+```
+
+```javascript
+setup() {
+    const state = reactive({
+      isVisible: false,
+      date: '',
+      dateWeek: ''
+    })
+    const openSwitch = param => {
+      state[`${param}`] = true;
+    }
+    const closeSwitch = param => {
+      state[`${param}`] = false;
+    }
+    const setChooseValue = (param: any) => {
+      state.date = param[3]
+      state.dateWeek = param[4]
+    }
+
+    return {
+      ...toRefs(state),
+      openSwitch,
+      closeSwitch,
+      setChooseValue
+    }
+  }
+```
+
+### 区间选择
+
+```html
+<fox-cell
+  :show-icon="true"
+  title="选择日期区间"
+  :desc="date1 ? `${date1[0]}至${date1[1]}` : '请选择'"
+  @click="openSwitch('isVisible1')"
+  >
+</fox-cell>
+<fox-calendar
+   v-model:visible="isVisible1"
+   :default-value="date1"
+   type="range"
+   :start-date="`2019-12-22`"
+   :end-date="`2021-01-08`"
+   @close="closeSwitch('isVisible1')"
+   @choose="setChooseValue1"
+   @select="select"
+>
+</fox-calendar>
+```
+
+```javascript
+setup() {
+    const state: TestCalendarState = reactive({
+      date1: ['2019-12-23', '2019-12-26'],
+      isVisible1: true
+    })
+    const openSwitch = param => {
+      state[`${param}`] = true;
+    }
+    const closeSwitch = param => {
+      state[`${param}`] = false;
+    }
+    const setChooseValue1 = (param: any) => {
+      state.date1 = [...[param[0][3], param[1][3]]]
+    }
+
+    return {
+      ...toRefs(state),
+      openSwitch,
+      closeSwitch,
+      setChooseValue1
+    }
+  }
+```
+
+### 快捷选择
+
+```html
+<fox-cell
+  :showIcon="true"
+  title="选择日期"
+  :desc="date3 ? date3 : '请选择'"
+  @click="openSwitch('isVisible3')"
+>
+</fox-cell>
+<fox-calendar
+  v-model:visible="isVisible"
+  default-value="date3"
+  @close="closeSwitch('isVisible3')"
+  @choose="setChooseValue3"
+  :start-date="null"
+  :end-date="null"
+  :is-auto-back-fill="true"
+>
+</fox-calendar>
+```
+
+```javascript
+setup() {
+    const state = reactive({
+      date3: '',
+      isVisible3: false
+    })
+    const openSwitch = param => {
+      state[`${param}`] = true;
+    }
+    const closeSwitch = param => {
+      state[`${param}`] = false;
+    }
+    const setChooseValue3= (param: any) => {
+      state.date3 = param[3]
+    }
+    return {
+      ...toRefs(state),
+      openSwitch,
+      closeSwitch,
+      setChooseValue3
+    }
+  }
+```
+
+### 自定义日历
+
+```html
+<div>
+      <fox-cell
+        :show-icon="true"
+        title="自定义按钮"
+        :desc="date5 && date5[0] ? `${date5[0]}至${date5[1]}` : '请选择'"
+        @click="openSwitch('isVisible5')"
+      >
+      </fox-cell>
+      <fox-calendar
+        v-model:visible="isVisible5"
+        :default-value="date5"
+        type="range"
+        :start-date="`2021-12-22`"
+        :end-date="`2022-12-31`"
+        @close="closeSwitch('isVisible5')"
+        @choose="setChooseValue5"
+      >
+        <template v-slot:btn>
+          <div class="wrapper">
+            <div class="d_div"><span class="d_btn" @click="clickBtn">最近七天</span></div>
+            <div class="d_div"><span class="d_btn" @click="clickBtn1">当月</span></div>
+          </div>
+        </template>
+        <template v-slot:day="date">
+          <span>{{ date.date.day }}</span>
+        </template>
+      </fox-calendar>
+    </div>
+    <div>
+      <fox-cell
+        :show-icon="true"
+        title="自定义时间文案"
+        :desc="date6 && date6[0] ? `${date6[0]}至${date6[1]}` : '请选择'"
+        @click="openSwitch('isVisible6')"
+      >
+      </fox-cell>
+      <fox-calendar
+        v-model:visible="isVisible6"
+        :default-value="date6"
+        type="range"
+        @close="closeSwitch('isVisible6')"
+        @choose="setChooseValue6"
+        :start-date="`2022-01-01`"
+        :end-date="`2022-12-31`"
+        confirm-text="submit"
+        start-text="入店"
+        end-text="离店"
+        title="日期选择"
+      >
+        <template v-slot:day="date">
+          <span>{{ date.date.day <= 9 ? '0' + date.date.day : date.date.day }}</span>
+        </template>
+        <template v-slot:bottomInfo="date">
+          <span class="info">{{
+            date.date ? (date.date.day <= 10 ? '上旬' : date.date.day <= 20 ? '中旬' : '下旬') : ''
+          }}</span>
+        </template>
+      </fox-calendar>
+    </div>
+```
+
+```javascript
+setup() {
+    const state: TestCalendarState = reactive({
+      isVisible5: boolean
+      isVisible6: boolean
+      date5: string[]
+      date6: string[]
+    })
+    const openSwitch = param => {
+      state[`${param}`] = true;
+    }
+    const closeSwitch = param => {
+      state[`${param}`] = false;
+    }
+    const setChooseValue5 = (param: any) => {
+      state.date5 = [...[param[0][3], param[1][3]]]
+    }
+   const setChooseValue6 = (param: any) => {
+      state.date6 = [...[param[0][3], param[1][3]]]
+    }
+    }
+
+    return {
+      ...toRefs(state),
+      openSwitch,
+      closeSwitch,
+      setChooseValue5,
+      setChooseValue6
+    }
+  }
+```
+
+
+### 平铺展示
+
+```html
+<div class="test-calendar-wrapper">
+   <fox-calendar :poppable="false" :default-value="date2" :is-auto-back-fill="true" @choose="setChooseValue2">
+   </fox-calendar>
+</div>
+```
+
+```javascript
+setup() {
+    const state: TestCalendarState = reactive({
+      date2: ''
+    })
+     const setChooseValue2 = (param: any) => {
+      state.date2 = param[3]
+    }
+    return {
+      ...toRefs(state),
+      setChooseValue2
+    }
+  }
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 Calendar 配合使用的相关组件
+- **fox-cell**: 与 Calendar 配合使用的相关组件
+

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

@@ -0,0 +1,331 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: CalendarItem 组件使用规范
+impact: HIGH
+type: capability
+description: 日历选择框
+tags: [foxui, fox-calendar-item, FoxCalendarItem]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js"]
+---
+
+# CalendarItem 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+CalendarItem 是 foxui 中用于 **日历选择框** 的标准组件。
+- **基于**: NutUI `nut-calendar-item` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、内置必填校验标识、支持 v-model 双向绑定、支持标签位置自定义、支持占位符提示、支持禁用/只读状态、内置多级提示信息、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 日历选择框
+
+> 💡 **关键原则**: 在所有 日历选择框 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 绑定值 | string,string（范围）,Date,Date（范围） | - |
+| `value-format` | 可选，绑定值的格式。不指定则绑定值为 Date 对象 | String | - |
+| `format` | 格式化显示的文本值 | String | - |
+| `placeholder` | 为空时占位符 | String | - |
+| `clearable` | 展示清除icon | Boolean | true |
+| `text-align` | 文本位置,可选值left,center,right | String | left |
+| `label` | 标签 | String | - |
+| `label-width` | 标签宽度 | String | - |
+| `label-position` | 标签位置可选值left,right,top | String | - |
+| `is-required` | 左侧号是否展示 | Boolean | false |
+| `disabled` | 是否禁用 | Boolean | false |
+| `readonly` | 是否只读 | Boolean | false |
+| `error-tip` | 错误提示 | String | - |
+| `error-icon` | 错误提示图标 | String | - |
+| `warn-tip` | 警告提示 | String | - |
+| `wran-icon` | 警告提示图标 | String | - |
+| `info-tip` | 提示 | String | - |
+| `info-icon` | 提示图标 | String | - |
+| `v-model:visible` | 是否可见 | Boolean | false |
+| `type` | 类型，日期选择'one'，区间选择'range' | String | 'one' |
+| `poppable` | 是否弹窗状态展示 | Boolean | true |
+| `is-auto-back-fill` | 自动回填 | Boolean | false |
+| `title` | 显示标题 | String | ‘日期选择’ |
+| `default-value` | 默认值，日期选择 String 格式，区间选择 Array 格式 | String 、 Array | null |
+| `start-date` | 开始日期， 如果不限制开始日期传 null | String | 今天 |
+| `end-date` | 结束日期，如果不限制结束日期传 null | String | 距离今天 365 天 |
+| `show-today` | 是否展示今天标记 | Boolean | true |
+| `start-text` | 范围选择，开始信息文案 | String | ’开始‘ |
+| `end-text` | 范围选择，结束信息文案 | String | ‘结束’ |
+| `confirm-text` | 底部确认按钮文案 | String | ’确认‘ |
+| `show-title` | 是否在展示日历标题 | Boolean | true |
+| `show-sub-title` | 是否展示日期标题 | Boolean | true |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `default` | label内容 |
+| `prepend` | 左侧自定义内容 |
+| `append` | 右侧自定义内容 |
+| `btn` | 自定义日历标题下部，可用以添加自定义操作 |
+| `day` | 日期信息 |
+| `topInfo` | 日期顶部信息 |
+| `bottomInfo` | 日期底部信息 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+### 单选
+```html
+<fox-calendar-item v-model="date" :show-week="true" start-date="2021-10-01" end-date="2021-10-31" @focus="onFocus" @blur="onBlur">单选日历</fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date: '2021-10-05',
+    })
+    // 方法
+    const method = {
+      onFocus() {
+        console.info('on focus')
+      },
+      onBlur() {
+        console.info('on blur')
+      }
+    }
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+### 单选（value格式化）
+```html
+ <fox-calendar-item v-model="date2" value-format="YYYY/MM/DD" :show-week="true" @focus="onFocus" @blur="onBlur">value格式化
+</fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date2: '',
+    })
+    // 方法
+    const method = {
+      onFocus() {
+        console.info('on focus')
+      },
+      onBlur() {
+        console.info('on blur')
+      }
+    }
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+### 单选（text格式化）
+```html
+<fox-calendar-item v-model="date3" format="YYYY年MM月DD日" :show-week="false" @focus="onFocus" @blur="onBlur">text格式化</fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date3: new Date(),
+    })
+    // 方法
+    const method = {
+      onFocus() {
+        console.info('on focus')
+      },
+      onBlur() {
+        console.info('on blur')
+      }
+    }
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+### 区间选择
+```html
+<fox-calendar-item type="range" v-model="date4" value-format="YYYY年MM月DD日">范围选择</fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date4: ['2021-10-01', '2021-10-31'],
+    })
+    // 方法
+    const method = {
+    }
+   
+    watch(
+      () => data.date4,
+      val => {
+        console.info(`date4 change`, val)
+      }
+    )
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+### 自动回填
+```html
+<fox-calendar-item type="range" v-model="date5" format="YYYY/MM/DD" :is-auto-back-fill="true">自动回填</fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date5: ''
+    })
+    // 方法
+    const method = {
+    }
+   
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+### 自定义-自定义按钮
+```html
+<fox-calendar-item
+      type="range"
+      v-model="date6"
+      :start-date="`2021-12-22`"
+      :end-date="`2022-12-31`"
+      value-format="YYYY年MM月DD日"
+    >
+      <template v-slot:default>自定义按钮</template>
+      <template v-slot:btn>
+        <div class="wrapper">
+          <div class="my-calender-div"><span class="my-calender-btn" @click="selectLast7Days">最近七天</span></div>
+          <div class="my-calender-div"><span class="my-calender-btn" @click="selectCurMonth">当月</span></div>
+        </div>
+      </template>
+      <template v-slot:day="date">
+        <span>{{ date.date.day }}</span>
+      </template>
+    </fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date6: ''
+    })
+    // 方法
+    const method = {
+       selectLast7Days: () => {
+        let date = [Utils.date2Str(new Date()), Utils.getDay(6)]
+        data.date6 = date
+      },
+      selectCurMonth: () => {
+        let date = new Date()
+        let year = date.getFullYear()
+        let month: any = date.getMonth() + 1
+        month = month < 10 ? '0' + month : month + ''
+        let yearMonth = `${year}-${month}`
+        let currMonthDays = Utils.getMonthDays(year + '', month + '')
+        data.date6 = [`${yearMonth}-01`, `${yearMonth}-${currMonthDays}`]
+      }
+    }
+   
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+### 自定义-自定义文案
+```html
+<fox-calendar-item
+      v-model="date7"
+      type="range"
+      :start-date="`2022-01-01`"
+      :end-date="`2022-12-31`"
+      confirm-text="submit"
+      start-text="入店"
+      end-text="离店"
+      title="日期选择"
+    >
+      <template v-slot:default>自定义文案</template>
+      <template v-slot:day="date">
+        <span>{{ date.date.day <= 9 ? '0' + date.date.day : date.date.day }}</span>
+      </template>
+      <template v-slot:bottomInfo="date">
+        <span class="info">{{
+          date.date ? (date.date.day <= 10 ? '上旬' : date.date.day <= 20 ? '中旬' : '下旬') : ''
+        }}</span>
+      </template>
+    </fox-calendar-item>
+```
+```javascript
+export default createDemo({
+  props: {},
+  setup() {
+    // 数据
+    const data = reactive({
+      date7: ''
+    })
+    // 方法
+    const method = {
+    }
+   
+    return {
+      ...toRefs(data),
+      ...method
+    }
+  }
+})
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 CalendarItem 配合使用的相关组件
+