sard-uniapp 1.19.1 → 1.19.3

package/components/config/index.d.ts

@@ -1,13 +1,19 @@
 import { type AvatarProps } from '../avatar';
 import { type AlertProps } from '../alert';
 import { type ButtonProps } from '../button';
+import { type CalendarInputProps } from '../calendar-input';
 import { type CalendarProps } from '../calendar';
+import { type CascaderInputProps } from '../cascader-input';
 import { type CheckboxGroupProps } from '../checkbox';
+import { type CheckboxInputProps } from '../checkbox-input';
+import { type DatetimePickerInputProps } from '../datetime-picker-input';
+import { type DatetimeRangePickerInputProps } from '../datetime-range-picker-input';
 import { type DialogProps } from '../dialog';
 import { type DropdownProps } from '../dropdown';
 import { type FloatingBubbleProps } from '../floating-bubble';
 import { type FormProps } from '../form';
 import { type GridProps } from '../grid';
+import { type IconProps } from '../icon';
 import { type InputProps } from '../input';
 import { type KeyboardProps } from '../keyboard';
 import { type ListItemProps } from '../list';
@@ -17,12 +23,14 @@ import { type NoticeBarProps } from '../notice-bar';
 import { type NotifyProps } from '../notify';
 import { type PaginationProps } from '../pagination';
 import { type PasswordInputProps } from '../password-input';
+import { type PickerInputProps } from '../picker-input';
 import { type PopoutProps } from '../popout';
 import { type PopoverProps } from '../popover';
 import { type PopupProps } from '../popup';
 import { type QrcodeProps } from '../qrcode';
 import { type RadioGroupProps } from '../radio';
 import { type RadioInputProps } from '../radio-input';
+import { type RadioPopoutProps } from '../radio-popout';
 import { type ResultProps } from '../result';
 import { type SearchProps } from '../search';
 import { type SpaceProps } from '../space';
@@ -40,6 +48,23 @@ type DeepPartial<T> = {
 };
 export declare const defaultConfig: {
     initialZIndex: number;
+    /**
+     * 设置点击清除按钮后的值
+     *
+     * - 类型：() => any
+     * - 默认值：() = undefined
+     *
+     * 支持以下组件：
+     *
+     * - CalendarInput
+     * - DatetimePickerInput
+     * - DatetimeRangePickerInput
+     * - CascaderInput
+     * - CheckboxInput
+     * - PickerInput
+     * - RadioInput
+     */
+    valueOnClear: (() => any) | undefined;
     actionSheet: {
         overlayClosable: boolean;
         duration: number;
@@ -74,6 +99,7 @@ export declare const defaultConfig: {
     };
     calendarInput: {
         outletFormat: string;
+        valueOnClear: CalendarInputProps["valueOnClear"];
     };
     calendarPopout: {
         showConfirm: boolean;
@@ -83,6 +109,9 @@ export declare const defaultConfig: {
         showConfirm: boolean;
         validateEvent: boolean;
     };
+    cascaderInput: {
+        valueOnClear: CascaderInputProps["valueOnClear"];
+    };
     checkbox: {
         validateEvent: boolean;
     };
@@ -90,6 +119,9 @@ export declare const defaultConfig: {
         direction: CheckboxGroupProps["direction"];
         validateEvent: boolean;
     };
+    checkboxInput: {
+        valueOnClear: CheckboxInputProps["valueOnClear"];
+    };
     checkboxPopout: {
         validateEvent: boolean;
     };
@@ -117,12 +149,18 @@ export declare const defaultConfig: {
         type: string;
         calendar: "solar";
     };
+    datetimePickerInput: {
+        valueOnClear: DatetimePickerInputProps["valueOnClear"];
+    };
     datetimePickerPopout: {
         validateEvent: boolean;
     };
     datetimeRangePicker: {
         type: string;
     };
+    datetimeRangePickerInput: {
+        valueOnClear: DatetimeRangePickerInputProps["valueOnClear"];
+    };
     datetimeRangePickerPopout: {
         validateEvent: boolean;
     };
@@ -187,6 +225,7 @@ export declare const defaultConfig: {
     icon: {
         name: string;
         family: string;
+        separate: IconProps["separate"];
     };
     indexes: {
         hintDuration: number;
@@ -254,6 +293,9 @@ export declare const defaultConfig: {
     picker: {
         immediateChange: boolean;
     };
+    pickerInput: {
+        valueOnClear: PickerInputProps["valueOnClear"];
+    };
     pickerPopout: {
         validateEvent: boolean;
     };
@@ -307,9 +349,12 @@ export declare const defaultConfig: {
         direction: RadioGroupProps["direction"];
         validateEvent: boolean;
     };
+    radioInput: {
+        valueOnClear: RadioInputProps["valueOnClear"];
+    };
     radioPopout: {
         validateEvent: boolean;
-        type: RadioInputProps["type"];
+        type: RadioPopoutProps["type"];
     };
     rate: {
         count: number;

package/components/config/index.js

@@ -2,6 +2,23 @@
 export const defaultConfig = {
     // 全局初始 zIndex
     initialZIndex: 1000,
+    /**
+     * 设置点击清除按钮后的值
+     *
+     * - 类型：() => any
+     * - 默认值：() = undefined
+     *
+     * 支持以下组件：
+     *
+     * - CalendarInput
+     * - DatetimePickerInput
+     * - DatetimeRangePickerInput
+     * - CascaderInput
+     * - CheckboxInput
+     * - PickerInput
+     * - RadioInput
+     */
+    valueOnClear: undefined,
     actionSheet: {
         overlayClosable: true,
         duration: 250,
@@ -36,6 +53,7 @@ export const defaultConfig = {
     },
     calendarInput: {
         outletFormat: 'YYYY-MM-DD',
+        valueOnClear: undefined,
     },
     calendarPopout: {
         showConfirm: true,
@@ -45,6 +63,9 @@ export const defaultConfig = {
         showConfirm: true,
         validateEvent: true,
     },
+    cascaderInput: {
+        valueOnClear: undefined,
+    },
     checkbox: {
         validateEvent: true,
     },
@@ -52,6 +73,9 @@ export const defaultConfig = {
         direction: 'vertical',
         validateEvent: true,
     },
+    checkboxInput: {
+        valueOnClear: undefined,
+    },
     checkboxPopout: {
         validateEvent: true,
     },
@@ -79,12 +103,18 @@ export const defaultConfig = {
         type: 'yMd',
         calendar: 'solar',
     },
+    datetimePickerInput: {
+        valueOnClear: undefined,
+    },
     datetimePickerPopout: {
         validateEvent: true,
     },
     datetimeRangePicker: {
         type: 'yMd',
     },
+    datetimeRangePickerInput: {
+        valueOnClear: undefined,
+    },
     datetimeRangePickerPopout: {
         validateEvent: true,
     },
@@ -149,6 +179,7 @@ export const defaultConfig = {
     icon: {
         name: '',
         family: 'sari',
+        separate: false,
     },
     indexes: {
         hintDuration: 300,
@@ -216,6 +247,9 @@ export const defaultConfig = {
     picker: {
         immediateChange: false,
     },
+    pickerInput: {
+        valueOnClear: undefined,
+    },
     pickerPopout: {
         validateEvent: true,
     },
@@ -269,6 +303,9 @@ export const defaultConfig = {
         direction: 'vertical',
         validateEvent: true,
     },
+    radioInput: {
+        valueOnClear: undefined,
+    },
     radioPopout: {
         validateEvent: true,
         type: 'circle',

package/components/count-down/README.md

@@ -0,0 +1,97 @@
+---
+nav: 组件
+title: CountDown
+subtitle: 倒计时
+group: 数据展示
+---
+
+## 介绍
+
+倒计时的展示 ，以便告知用户在一定时间后可以进行某些操作。
+
+```ts
+import CountDown from 'sard-uniapp/components/count-down/count-down.vue'
+```
+
+## 代码演示
+
+## 引入
+
+### 基础使用
+
+使用 `time` 属性配置倒计时总时长（单位毫秒）。
+
+@code('${DEMO_PATH}/count-down/demo/Basic.vue')
+
+### 自定义格式
+
+默认格式为 `HH:mm:ss` ，也可以使用 `format` 自定义人任意想要的格式。
+
+@code('${DEMO_PATH}/count-down/demo/Format.vue')
+
+### 毫秒级别的渲染
+
+默认每隔一秒渲染一次，使用 `millisecond` 属性可以设置毫秒级别渲染。
+
+@code('${DEMO_PATH}/count-down/demo/Millisecond.vue')
+
+### 自定义样式
+
+如果想获取时分秒等数据分别渲染不同的样式，可以使用默认插槽提供的 `time` 属性来获取数据（`time` 类型为：`CountDownCurrentTime`）。
+
+@code('${DEMO_PATH}/count-down/demo/Style.vue')
+
+### 手动控制
+
+当倒计时结束时便会停止，通过组件提供的方法可以控制倒计时的开始、暂停或进行重置。
+
+@code('${DEMO_PATH}/count-down/demo/Control.vue')
+
+### 验证码倒计时
+
+下面代码演示了获取验证码场景中倒计时配合按钮的使用。
+
+@code('${DEMO_PATH}/count-down/demo/Captcha.vue')
+
+## API
+
+### CountDownProps
+
+| 属性        | 描述                   | 类型    | 默认值     |
+| ----------- | ---------------------- | ------- | ---------- |
+| time        | 倒计时总时长，单位毫秒 | number  | 0          |
+| auto-start  | 是否自动开始倒计时     | boolean | true       |
+| format      | 时间格式               | string  | 'HH:mm:ss' |
+| millisecond | 是否开启毫秒级别渲染   | boolean | false      |
+
+### CountDownSlots
+
+| 插槽    | 描述           | 属性                           |
+| ------- | -------------- | ------------------------------ |
+| default | 自定义默认内容 | { time: CountDownCurrentTime } |
+
+### CountDownEmits
+
+| 事件   | 描述             | 类型                                 |
+| ------ | ---------------- | ------------------------------------ |
+| change | 倒计时变化时触发 | (time: CountDownCurrentTime) => void |
+| finish | 倒计时结束时触发 | () => void                           |
+
+### CountDownExpose
+
+| 属性  | 描述       | 类型       |
+| ----- | ---------- | ---------- |
+| start | 开始倒计时 | () => void |
+| pause | 暂停倒计时 | () => void |
+| reset | 重置倒计时 | () => void |
+
+### CountDownCurrentTime
+
+| 属性         | 描述                   | 类型   |
+| ------------ | ---------------------- | ------ |
+| milliseconds | 剩余毫秒               | number |
+| seconds      | 剩余秒数               | number |
+| minutes      | 剩余分钟               | number |
+| hours        | 剩余小时               | number |
+| days         | 剩余天数               | number |
+| total        | 剩余总时间（单位毫秒） | number |

package/components/count-down/count-down.vue

@@ -14,6 +14,14 @@ import {
   formatTime,
   defaultCountDownProps
 } from "./common";
+/**
+ * @property {number} time 倒计时总时长，单位毫秒，默认值：0。
+ * @property {boolean} autoStart 是否自动开始倒计时，默认值：true。
+ * @property {string} format 时间格式，默认值：'HH:mm:ss'。
+ * @property {boolean} millisecond 是否开启毫秒级别渲染，默认值：false。
+ * @event {(time: CountDownCurrentTime) => void} change 倒计时变化时触发
+ * @event {() => void} finish 倒计时结束时触发
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/count-to/README.md

@@ -0,0 +1,61 @@
+---
+nav: 组件
+title: CountTo
+subtitle: 数字滚动
+group: 数据展示
+version: 1.2+
+---
+
+## 介绍
+
+从某一个数值动态递增或递减到另一个数值。
+
+## 引入
+
+```ts
+import CountTo from 'sard-uniapp/components/count-to/count-to.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+给 `value` 属性一个数字值即可启动滚动功能。
+
+@code('${DEMO_PATH}/count-to/demo/Basic.vue')
+
+### 小数位数
+
+使用 `precision` 属性设置小数位数。
+
+@code('${DEMO_PATH}/count-to/demo/Precision.vue')
+
+### 分隔符
+
+使用 `separator` 属性设置千分位分隔符。
+
+@code('${DEMO_PATH}/count-to/demo/Separator.vue')
+
+### 持续时间
+
+使用 `duration` 属性设置滚动时长。
+
+@code('${DEMO_PATH}/count-to/demo/Duration.vue')
+
+### 随机数字
+
+`value` 属性改变时会自动滚动到最新的值。
+
+@code('${DEMO_PATH}/count-to/demo/Random.vue')
+
+## API
+
+### CountToProps
+
+| 属性           | 描述                                   | 类型   | 默认值 |
+| -------------- | -------------------------------------- | ------ | ------ |
+| value          | 滚动到的目标数值                       | number | 0      |
+| precision      | 精度，即小数位数                       | number | 0      |
+| separator      | 千分位分隔符                           | string | -      |
+| separatorDigit | 默认每三位插入一个分隔符，也可以自定义 | number | 3      |
+| duration       | 滚动到目标值持续时间，单位 ms          | number | 2000   |

package/components/count-to/count-to.vue

@@ -7,6 +7,13 @@ import { mergeDefaults as _mergeDefaults, defineComponent as _defineComponent }
 import { computed, onUnmounted, ref, watch } from "vue";
 import { addSeparator, createAnimation } from "../../utils";
 import { defaultCountToProps } from "./common";
+/**
+ * @property {number} value 滚动到的目标数值，默认值：0。
+ * @property {number} precision 精度，即小数位数，默认值：0。
+ * @property {string} separator 千分位分隔符，默认值：-。
+ * @property {number} separatorDigit 默认每三位插入一个分隔符，也可以自定义，默认值：3。
+ * @property {number} duration 滚动到目标值持续时间，单位 ms，默认值：2000。
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/crop-image/README.md

@@ -0,0 +1,86 @@
+---
+nav: 组件
+title: CropImage
+subtitle: 裁剪图片
+group:
+  title: 工具组件
+  order: 7
+version: 1.12+
+---
+
+## 介绍
+
+对图片进行裁剪。
+
+## 引入
+
+```ts
+import CropImage from 'sard-uniapp/components/crop-image/crop-image.vue'
+import CropImageAgent from 'sard-uniapp/components/crop-image-agent/crop-image-agent.vue'
+import { cropImage } from 'sard-uniapp'
+```
+
+## 代码演示
+
+### 基础使用
+
+先在页面放置代理组件。
+
+接着便可以使用 `cropImage` 方法对图片进行裁剪。
+
+```tsx
+<sar-crop-image-agent />
+```
+
+@code('${DEMO_PATH}/crop-image/demo/Basic.vue')
+
+### 裁剪比例
+
+可以通过 `cropScale` 属性设置任意比例。
+
+@code('${DEMO_PATH}/crop-image/demo/CropScale.vue')
+
+### 修改裁剪尺寸
+
+可以通过 `beforeCrop` 方法修改裁剪尺寸，接收实际宽高，通过返回缩放比例来修改裁剪大小。
+
+@code('${DEMO_PATH}/crop-image/demo/BeforeCrop.vue')
+
+## API
+
+### CropImageProps
+
+| 属性        | 描述                                                   | 类型                                      | 默认值 |
+| ----------- | ------------------------------------------------------ | ----------------------------------------- | ------ |
+| root-class  | 组件根元素类名                                         | string                                    | -      |
+| root-style  | 组件根元素样式                                         | StyleValue                                | -      |
+| visible     | 是否显示裁剪弹框                                       | boolean                                   | false  |
+| src         | 要裁剪的图片                                           | string                                    | false  |
+| crop-scale  | 裁剪的比例                                             | string                                    | '1:1'  |
+| type        | 导出图片类型                                           | 'png' \| 'jpg'                            | 'png'  |
+| quality     | 导出图片的质量                                         | number                                    | 0.92   |
+| duration    | 弹窗显隐过渡时间（单位 ms）                            | number                                    | 150    |
+| success     | 裁剪成功回调                                           | (filePath: string) => void                | -      |
+| fail        | 裁剪成功回调                                           | (err: any) => void                        | -      |
+| complete    | 裁剪成功或失败回调                                     | () => void                                | -      |
+| before-crop | 裁剪前回调，可以修改裁剪的尺寸；接收宽高，返回缩放比例 | (width: number, height: number) => number | -      |
+
+### CropImageEmits
+
+| 事件           | 描述             | 类型                       |
+| -------------- | ---------------- | -------------------------- |
+| update:visible | 弹出框显隐时触发 | (visible: boolean) => void |
+
+### CropImageAgentProps / CropImageOptions
+
+继承 [`CropImageProps`](#CropImageProps) 并有以下额外属性。
+
+| 属性 | 描述          | 类型   | 默认值      |
+| ---- | ------------- | ------ | ----------- |
+| id   | 裁剪组件的 id | string | 'cropImage' |
+
+### 命令式方法
+
+| 名称      | 描述     | 类型                                |
+| --------- | -------- | ----------------------------------- |
+| cropImage | 裁剪图片 | (options: CropImageOptions) => void |

package/components/crop-image/crop-image.vue

@@ -118,6 +118,21 @@ import SarLoading from "../loading/loading.vue";
 const minGapX = 20;
 const bounceCoeff = 4;
 const maxScale = 5;
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示裁剪弹框，默认值：false。
+ * @property {string} src 要裁剪的图片，默认值：false。
+ * @property {string} cropScale 裁剪的比例，默认值：'1:1'。
+ * @property {'png' | 'jpg'} type 导出图片类型，默认值：'png'。
+ * @property {number} quality 导出图片的质量，默认值：0.92。
+ * @property {number} duration 弹窗显隐过渡时间（单位 ms），默认值：150。
+ * @property {(filePath: string) => void} success 裁剪成功回调，默认值：-。
+ * @property {(err: any) => void} fail 裁剪成功回调，默认值：-。
+ * @property {() => void} complete 裁剪成功或失败回调，默认值：-。
+ * @property {(width: number, height: number) => number} beforeCrop 裁剪前回调，可以修改裁剪的尺寸；接收宽高，返回缩放比例，默认值：-。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopup,

package/components/datetime-picker/README.md

@@ -0,0 +1,136 @@
+---
+nav: 组件
+title: DatetimePicker
+subtitle: 日期时间选择器
+group: 表单组件
+---
+
+## 介绍
+
+用于选择日期时间。
+
+## 引入
+
+```ts
+import DatetimePicker from 'sard-uniapp/components/datetime-picker/datetime-picker.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+通过 `v-model` 绑定当前值，通过 `type` 属性设置要展示的列类型。
+
+@code('${DEMO_PATH}/datetime-picker/demo/Basic.vue')
+
+更多案例，请参考 [DatetimePickerPopout 组件](./datetime-picker-popout)
+
+## API
+
+### DatetimePickerProps
+
+| 属性                          | 描述                                         | 类型                                                                                                            | 默认值  |
+| ----------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
+| root-class                    | 组件根元素类名                               | string                                                                                                          | -       |
+| root-style                    | 组件根元素样式                               | StyleValue                                                                                                      | -       |
+| type                          | 设置每一列要展示的数据类型，每个字母对应一列 | string [详见特殊符号](#DatetimeLetter)                                                                          | 'yMd'   |
+| calendar <sup>1.18+</sup>     | 历法类型，可选公历或农历                     | 'solar' \| 'lunar'                                                                                              | 'solar' |
+| min                           | 可选的最小日期                               | Date                                                                                                            | 十年前  |
+| max                           | 可选的最大日期                               | Date                                                                                                            | 十年后  |
+| model-value                   | 当前选中的日期                               | Date \| string                                                                                                  | -       |
+| filter                        | 选项的过滤函数                               | (letter: DatetimeLetter, value: number, date: Date, index: number) => boolean                                   | -       |
+| formatter                     | 选项的格式化函数                             | (letter: DatetimeLetter, option: DatetimeColumnOption, date: Date, index: number) => string \| void \|undefined | -       |
+| value-format <sup>1.10+</sup> | 绑定值的格式，不指定则绑定值为 Date 对象     | string [详见特殊符号](../guide/date#日期格式特殊符号)                                                           | -       |
+
+### DatetimePickerEmits
+
+| 事件                     | 描述                 | 类型                           |
+| ------------------------ | -------------------- | ------------------------------ |
+| update:model-value       | 选中的选项改变时触发 | (date: Date \| string) => void |
+| change <sup>1.9.2+</sup> | 选中的选项改变时触发 | (date: Date \| string) => void |
+
+### DatetimeLetter
+
+```ts
+type DatetimeLetter = 'y' | 'M' | 'd' | 'h' | 'm' | 's'
+```
+
+上面每个字母分别代表“年月日时分秒”。
+
+### DatetimeColumnOption
+
+| 属性     | 描述                                               | 类型                        |
+| -------- | -------------------------------------------------- | --------------------------- |
+| value    | 选项值，如果是农历闰月，此值会为负数               | number                      |
+| label    | 展示的文本，默认中文会在值的后面加上“年月日时分秒” | string \| number \| boolean |
+| zerofill | 填充前置 0 后的选项值字符串，可在格式化时使用      | string                      |
+
+### 农历相关API <sup>1.18+</sup>
+
+#### solarToLunar
+
+```ts
+function solarToLunar(
+  year: number,
+  month: number,
+  day: number,
+): {
+  year: number
+  month: number
+  day: number
+}
+```
+
+接收公历的年月日（月份从1开始），返回农历的年月日。如果返回的月份为负数，则为闰月。
+
+#### lunarToSolar
+
+```ts
+function lunarToSolar(
+  year: number,
+  month: number,
+  day: number,
+): {
+  year: number
+  month: number
+  day: number
+}
+```
+
+接收农历的年月日（月份从1开始），返回公历的年月日。如果农历月份为闰月，需传递负数。
+
+#### getLunarYearName
+
+```ts
+function getLunarYearName(year: number): string
+```
+
+接收数字年份，返回中文数字年份，例如：`2025 -> '二零二五年'`。
+
+#### getLunarMonthName
+
+```ts
+function getLunarMonthName(month: number, isLeapMonth?: boolean): string
+```
+
+- 参数
+  - month: 农历月份，从1开始；
+  - isLeapMonth: 是否为闰月。
+
+获取农历月份名称。
+
+#### getLunarDayName
+
+```ts
+function getLunarDayName(day: number): string
+```
+
+获取农历日期名称。
+
+#### getLunarHourName
+
+```ts
+function getLunarHourName(hour: number): string
+```
+
+获取农历时辰名称。

package/components/datetime-picker/datetime-picker.vue

@@ -31,6 +31,20 @@ import {
   defaultDatetimePickerProps
 } from "./common";
 import { useTranslate } from "../locale";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string [详见特殊符号](#DatetimeLetter)} type 设置每一列要展示的数据类型，每个字母对应一列，默认值：'yMd'。
+ * @property {'solar' | 'lunar'} calendar 历法类型，可选公历或农历，默认值：'solar'。
+ * @property {Date} min 可选的最小日期，默认值：十年前。
+ * @property {Date} max 可选的最大日期，默认值：十年后。
+ * @property {Date | string} modelValue 当前选中的日期，默认值：-。
+ * @property {(letter: DatetimeLetter, value: number, date: Date, index: number) => boolean} filter 选项的过滤函数，默认值：-。
+ * @property {(letter: DatetimeLetter, option: DatetimeColumnOption, date: Date, index: number) => string | void |undefined} formatter 选项的格式化函数，默认值：-。
+ * @property {string [详见特殊符号](../guide/date#日期格式特殊符号)} valueFormat 绑定值的格式，不指定则绑定值为 Date 对象，默认值：-。
+ * @event {(date: Date | string) => void} update 选中的选项改变时触发
+ * @event {(date: Date | string) => void} change 选中的选项改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPicker,