sard-uniapp 1.19.2 → 1.19.4

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,

package/components/datetime-picker-input/README.md

@@ -0,0 +1,82 @@
+---
+nav: 组件
+title: DatetimePickerInput
+subtitle: 日期时间输入框
+group: 表单组件
+---
+
+## 介绍
+
+组合了日期时间弹出框、输入框组件，实现了便捷快速的日期选择功能。
+
+## 引入
+
+```ts
+import DatetimePickerInput from 'sard-uniapp/components/datetime-picker-input/datetime-picker-input.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 绑定当前值，通过 `title` 和 `placeholder` 属性设置弹出框标题和输入框占位文本。
+
+在点击输入框后会显示日期时间弹出框。
+
+@code('${DEMO_PATH}/datetime-picker-input/demo/Basic.vue')
+
+### 输入框日期格式
+
+使用 `outlet-format` 属性自定义输入框日期展示的格式。
+
+@code('${DEMO_PATH}/datetime-picker-input/demo/OutletFormat.vue')
+
+### 绑定值的格式
+
+默认绑定的值为 `Date` 实例，提交到后端时需要手动转换为特定格式的字符串；使用 `value-format` 属性可以将这个转换交由组件库处理。
+
+@code('${DEMO_PATH}/datetime-picker-input/demo/ValueFormat.vue')
+
+### min、max 联动
+
+可以通过 `min` 和 `max` 属性使两个选择器联动。
+
+选择日期时间范围，使用 `DatetimeRangePickerInput` 是更好的选择。
+
+@code('${DEMO_PATH}/datetime-picker-input/demo/Range.vue')
+
+## API
+
+### DatetimePickerInputProps
+
+继承 [`DatetimePickerPopoutProps`](./datetime-picker-popout#DatetimePickerPopoutProps) 并有以下额外属性：
+
+| 属性                              | 描述                                                         | 类型                                                  | 默认值          |
+| --------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- | --------------- |
+| root-class                        | 弹出式输入框根元素类名                                       | string                                                | -               |
+| root-style                        | 弹出式输入框根元素样式                                       | StyleValue                                            | -               |
+| disabled                          | 禁用状态                                                     | boolean                                               | false           |
+| readonly                          | 只读状态                                                     | boolean                                               | false           |
+| clearable                         | 是否显示清空按钮                                             | boolean                                               | false           |
+| placeholder                       | 输入框占位符内容                                             | string                                                | -               |
+| outlet-format                     | 输出到输入框的日期格式，不指定则根据 `type` 属性自动生成格式 | string [详见特殊符号](../guide/date#日期格式特殊符号) | -               |
+| value-on-clear <sup>1.19.2+</sup> | 设置点击清除按钮后的值                                       | () => any                                             | () => undefined |
+
+### `type` 到 `outletFormat` 的映射：
+
+```ts
+const mapTypeFormat = {
+  y: 'YYYY',
+  yM: 'YYYY-MM',
+  yMd: 'YYYY-MM-DD',
+  yMdh: 'YYYY-MM-DD HH',
+  yMdhm: 'YYYY-MM-DD HH:mm',
+  yMdhms: 'YYYY-MM-DD HH:mm:ss',
+  hm: 'HH:mm',
+  hms: 'HH:mm:ss',
+}
+```
+
+### DatetimePickerInputEmits
+
+继承 [`DatetimePickerPopoutEmits`](./datetime-picker-popout#DatetimePickerPopoutEmits)

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

@@ -41,6 +41,31 @@ import {
   defaultDatetimePickerInputProps,
   mapTypeFormat
 } from "./common";
+/**
+ * @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 对象，默认值：-。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @property {boolean} disabled 禁用状态，默认值：false。
+ * @property {boolean} readonly 只读状态，默认值：false。
+ * @property {boolean} clearable 是否显示清空按钮，默认值：false。
+ * @property {string} placeholder 输入框占位符内容，默认值：-。
+ * @property {string [详见特殊符号](../guide/date#日期格式特殊符号)} outletFormat 输出到输入框的日期格式，不指定则根据 `type` 属性自动生成格式，默认值：-。
+ * @property {() => any} valueOnClear 设置点击清除按钮后的值，默认值：() => undefined。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: Date |string | undefined) => void} change 日期时间输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopoutInput,

package/components/datetime-picker-popout/README.md

@@ -0,0 +1,77 @@
+---
+nav: 组件
+title: DatetimePickerPopout
+subtitle: 日期时间弹出框
+group: 表单组件
+version: 1.16+
+---
+
+## 介绍
+
+组合了日期时间、弹出框组件，实现了便捷快速的日期选择功能。
+
+## 引入
+
+```ts
+import DatetimePickerPopout from 'sard-uniapp/components/datetime-picker-popout/datetime-picker-popout.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 双向绑定当前值，使用 `v-model:visible` 控制弹出框显隐。
+
+@code('${DEMO_PATH}/datetime-picker-popout/demo/Basic.vue')
+
+### 类型
+
+可以使用 `yMdhms`（年月日时分秒）进行任意组合，每个字母对应一列。
+
+@code('${DEMO_PATH}/datetime-picker-popout/demo/Type.vue')
+
+### 自定义日期时间范围
+
+可以使用 `min` 和 `max` 属性限制可以选择的日期时间的范围。
+
+@code('${DEMO_PATH}/datetime-picker-popout/demo/MinMax.vue')
+
+### 过滤器
+
+可以使用 `filter` 属性来仅展示想要的内容，只有返回真的值才会展示。
+
+@code('${DEMO_PATH}/datetime-picker-popout/demo/Filter.vue')
+
+### 格式化
+
+可以使用 `formatter` 属性格式化展示的内容。
+
+@code('${DEMO_PATH}/datetime-picker-popout/demo/Formatter.vue')
+
+### 农历
+
+可以设置 `calendar="lunar"` 将历法类型改为农历。农历仅用于展示，实际绑定的值还是公历。
+
+@code('${DEMO_PATH}/datetime-picker-popout/demo/Calendar.vue')
+
+## API
+
+### DatetimePickerPopoutProps
+
+继承 [`DatetimePickerProps`](./datetime-picker#DatetimePickerProps) 并有以下额外属性：
+
+| 属性              | 描述             | 类型       | 默认值 |
+| ----------------- | ---------------- | ---------- | ------ |
+| popout-class      | 弹窗框根元素类名 | string     | -      |
+| popout-style      | 弹窗框根元素样式 | StyleValue | -      |
+| visible (v-model) | 是否显示弹出框   | boolean    | -      |
+| title             | 弹出框标题       | string     | -      |
+| validate-event    | 是否触发表单验证 | boolean    | true   |
+
+### DatetimePickerPopoutEmits
+
+| 事件               | 描述                         | 类型                                         |
+| ------------------ | ---------------------------- | -------------------------------------------- |
+| update:model-value | 日期时间输入组件值改变时触发 | (value: Date \| string \| undefined) => void |
+| change             | 日期时间输入组件值改变时触发 | (value: Date \|string \| undefined) => void  |
+| update:visible     | 弹出框显隐时触发             | (visible: boolean) => void                   |

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

@@ -40,6 +40,25 @@ import {
   getMinDate
 } from "../datetime-picker/common";
 import { useFormPopout } from "../../use";
+/**
+ * @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 对象，默认值：-。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: Date |string | undefined) => void} change 日期时间输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopout,

package/components/datetime-range-picker/README.md

@@ -0,0 +1,49 @@
+---
+nav: 组件
+title: DatetimeRangePicker
+subtitle: 日期时间范围选择器
+group: 表单组件
+version: 1.11+
+---
+
+## 介绍
+
+用于选择日期时间范围。
+
+## 引入
+
+```ts
+import DatetimeRangePicker from 'sard-uniapp/components/datetime-range-picker/datetime-range-picker.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+和 `DatetimePicker` 组件用法类似，多了一个 `tabs` 属性设置起始和结束标签页标题。
+
+@code('${DEMO_PATH}/datetime-range-picker/demo/Basic.vue')
+
+## API
+
+### DatetimeRangePickerProps
+
+继承 [`DatetimePickerProps`](./datetime-picker#DatetimePickerProps) 并有以下额外属性：
+
+| 属性        | 描述                     | 类型               | 默认值 |
+| ----------- | ------------------------ | ------------------ | ------ |
+| model-value | 绑定的值                 | (Date \| string)[] | -      |
+| tabs        | 设置起始和结束标签页标题 | string[]           | -      |
+
+### DatetimeRangePickerEmits
+
+| 事件               | 描述                 | 类型                               |
+| ------------------ | -------------------- | ---------------------------------- |
+| update:model-value | 选中的选项改变时触发 | (date: (Date \| string)[]) => void |
+| change             | 选中的选项改变时触发 | (date: (Date \| string)[]) => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

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

@@ -51,6 +51,21 @@ import {
   getMaxDate,
   getMinDate
 } from "../datetime-picker/common";
+/**
+ * @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 对象，默认值：-。
+ * @property {string[]} tabs 设置起始和结束标签页标题，默认值：-。
+ * @event {(date: (Date | string)[]) => void} update 选中的选项改变时触发
+ * @event {(date: (Date | string)[]) => void} change 选中的选项改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarDatetimePicker,

package/components/datetime-range-picker-input/README.md

@@ -0,0 +1,58 @@
+---
+nav: 组件
+title: DatetimeRangePickerInput
+subtitle: 日期时间范围输入框
+group: 表单组件
+version: 1.11+
+---
+
+## 介绍
+
+组合了日期时间范围弹出框、输入框组件，实现了便捷快速的日期时间范围选择功能。
+
+## 引入
+
+```ts
+import DatetimeRangePickerInput from 'sard-uniapp/components/datetime-range-picker-input/datetime-range-picker-input.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+和 `DatetimePickerInput` 组件用法类似，多了一个 `tabs` 属性设置起始和结束标签页标题。
+
+@code('${DEMO_PATH}/datetime-range-picker-input/demo/Basic.vue')
+
+### 输入框日期格式
+
+使用 `outlet-format` 属性自定义输入框日期展示的格式。
+
+@code('${DEMO_PATH}/datetime-range-picker-input/demo/OutletFormat.vue')
+
+### 绑定值的格式
+
+默认绑定的值为 `Date` 实例，提交到后端时需要手动转换为特定格式的字符串；使用 `value-format` 属性可以将这个转换交由组件库处理。
+
+@code('${DEMO_PATH}/datetime-range-picker-input/demo/ValueFormat.vue')
+
+## API
+
+### DatetimeRangePickerInputProps
+
+继承 [`DatetimeRangePickerPopoutProps`](./datetime-range-picker-popout#DatetimeRangePickerPopoutProps) 并有以下额外属性：
+
+| 属性                              | 描述                                                         | 类型                                                  | 默认值          |
+| --------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- | --------------- |
+| root-class                        | 弹出式输入框根元素类名                                       | string                                                | -               |
+| root-style                        | 弹出式输入框根元素样式                                       | StyleValue                                            | -               |
+| disabled                          | 禁用状态                                                     | boolean                                               | false           |
+| readonly                          | 只读状态                                                     | boolean                                               | false           |
+| clearable                         | 是否显示清空按钮                                             | boolean                                               | false           |
+| placeholder                       | 输入框占位符内容                                             | string                                                | -               |
+| outlet-format                     | 输出到输入框的日期格式，不指定则根据 `type` 属性自动生成格式 | string [详见特殊符号](../guide/date#日期格式特殊符号) | -               |
+| value-on-clear <sup>1.19.2+</sup> | 设置点击清除按钮后的值                                       | () => any                                             | () => undefined |
+
+### DatetimeRangePickerInputEmits
+
+继承 [`DatetimeRangePickerPopoutEmits`](./datetime-range-picker-popout#DatetimeRangePickerPopoutEmits)

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

@@ -42,6 +42,32 @@ import {
 } from "./common";
 import { mapTypeFormat } from "../datetime-picker-input/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 对象，默认值：-。
+ * @property {string[]} tabs 设置起始和结束标签页标题，默认值：-。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @property {boolean} disabled 禁用状态，默认值：false。
+ * @property {boolean} readonly 只读状态，默认值：false。
+ * @property {boolean} clearable 是否显示清空按钮，默认值：false。
+ * @property {string} placeholder 输入框占位符内容，默认值：-。
+ * @property {string [详见特殊符号](../guide/date#日期格式特殊符号)} outletFormat 输出到输入框的日期格式，不指定则根据 `type` 属性自动生成格式，默认值：-。
+ * @property {() => any} valueOnClear 设置点击清除按钮后的值，默认值：() => undefined。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(date: (Date | string)[]) => void} change 日期时间输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopoutInput,