sard-uniapp 1.19.2 → 1.19.3

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,

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

@@ -0,0 +1,53 @@
+---
+nav: 组件
+title: DatetimeRangePickerPopout
+subtitle: 日期时间范围弹出框
+group: 表单组件
+version: 1.16+
+---
+
+## 介绍
+
+组合了日期时间范围、弹出框组件，实现了便捷快速的日期时间范围选择功能。
+
+## 引入
+
+```ts
+import DatetimeRangePickerPopout from 'sard-uniapp/components/datetime-range-picker-popout/datetime-range-picker-popout.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 双向绑定当前值，使用 `v-model:visible` 控制弹出框显隐。
+
+@code('${DEMO_PATH}/datetime-range-picker-popout/demo/Basic.vue')
+
+## API
+
+### DatetimeRangePickerPopoutProps
+
+继承 [`DatetimeRangePickerProps`](./datetime-range-picker#DatetimeRangePickerProps) 并有以下额外属性：
+
+| 属性              | 描述             | 类型       | 默认值 |
+| ----------------- | ---------------- | ---------- | ------ |
+| popout-class      | 弹窗框根元素类名 | string     | -      |
+| popout-style      | 弹窗框根元素样式 | StyleValue | -      |
+| visible (v-model) | 是否显示弹出框   | boolean    | -      |
+| title             | 弹出框标题       | string     | -      |
+| validate-event    | 是否触发表单验证 | boolean    | true   |
+
+### DatetimeRangePickerPopoutEmits
+
+| 事件               | 描述                         | 类型                               |
+| ------------------ | ---------------------------- | ---------------------------------- |
+| update:model-value | 日期时间输入组件值改变时触发 | (date: (Date \| string)[]) => void |
+| change             | 日期时间输入组件值改变时触发 | (date: (Date \| string)[]) => void |
+| update:visible     | 弹出框显隐时触发             | (visible: boolean) => void         |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

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

@@ -40,6 +40,26 @@ 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[]} tabs 设置起始和结束标签页标题，默认值：-。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(date: (Date | string)[]) => void} change 日期时间输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopout,

package/components/dialog/README.md

@@ -0,0 +1,192 @@
+---
+nav: 组件
+title: Dialog
+subtitle: 对话框
+group: 反馈组件
+---
+
+## 介绍
+
+提示或接收用户的确认。
+
+## 引入
+
+```ts
+import Dialog from 'sard-uniapp/components/dialog/dialog.vue'
+import DialogAgent from 'sard-uniapp/components/dialog-agent/dialog-agent.vue'
+import { dialog } from 'sard-uniapp'
+```
+
+## 代码演示
+
+### 基础使用
+
+先在页面放置代理组件。
+
+```tsx
+<sar-dialog-agent />
+```
+
+接着便可以使用 `dialog` 等方法显示对话框。
+
+@code('${DEMO_PATH}/dialog/demo/Basic.vue')
+
+### 异步关闭
+
+如果 `beforeClose` 返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭。
+
+@code('${DEMO_PATH}/dialog/demo/AsyncClose.vue')
+
+### 圆角按钮
+
+`buttonType` 属性值为 `round` 可以将底部按钮显示为圆角的形式。
+
+@code('${DEMO_PATH}/dialog/demo/Round.vue')
+
+### 有头部的
+
+配置 `headed` 属性让对话框显示头部，此时的对话框更像一个模态框。
+
+@code('${DEMO_PATH}/dialog/demo/Headed.vue')
+
+### 自定义内容
+
+对话框里面可以放置任何内容，例如以模态的方式展示一个表单，通常要配合 `headed` 属性一起使用。
+
+@code('${DEMO_PATH}/dialog/demo/Content.vue')
+
+### 内容中包含弹出框
+
+`v1.4.1` 起，对话框底层的 `Popup` 组件包裹在了 `root-portal` (小程序)和 `teleport` (H5)中，因此基于 `Popup` 的可弹出组件都可以相互嵌套使用，也可以放置在 `scroll-view` 里面。
+
+@code('${DEMO_PATH}/dialog/demo/PopupContent.vue')
+
+### 自定义按钮属性
+
+使用 `cancelProps` 和 `confirmProps` 属性可以自定义取消和确定按钮组件的属性。
+
+@code('${DEMO_PATH}/dialog/demo/ButtonProps.vue')
+
+## API
+
+### DialogProps
+
+| 属性                           | 描述                                                                 | 类型              | 默认值  |
+| ------------------------------ | -------------------------------------------------------------------- | ----------------- | ------- |
+| root-class                     | 对话框根元素类名                                                     | string            | -       |
+| root-style                     | 对话框根元素样式                                                     | StyleValue        | -       |
+| popup-class <sup>1.14.1+</sup> | 弹窗框根元素类名                                                     | string            | -       |
+| popup-style <sup>1.14.1+</sup> | 弹窗框根元素样式                                                     | StyleValue        | -       |
+| visible (v-model)              | 是否可见                                                             | boolean           | false   |
+| title                          | 标题                                                                 | string            | -       |
+| message                        | 文本内容                                                             | string            | -       |
+| headed                         | 是否显示带头部类型                                                   | boolean           | true    |
+| button-type                    | 按钮类型                                                             | 'round' \| 'text' | 'round' |
+| show-cancel                    | 是否显示取消按钮                                                     | boolean           | true    |
+| cancel-text                    | 取消按钮文案                                                         | string            | '取消'  |
+| show-confirm                   | 是否显示确定按钮                                                     | boolean           | true    |
+| confirm-text                   | 确定按钮文案                                                         | string            | '确定'  |
+| overlay-closable               | 点击遮罩是否关闭                                                     | boolean           | false   |
+| before-close                   | 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭 | DialogBeforeClose | -       |
+| duration                       | 显隐动画时长，单位 ms                                                | number            | 300     |
+| confirm-props <sup>1.10+</sup> | 设置确定按钮 props                                                   | ButtonProps       | -       |
+| cancel-props <sup>1.10+</sup>  | 设置取消按钮 props                                                   | ButtonProps       | -       |
+
+#### DialogBeforeClose
+
+- 当点击确定按钮时，`type` 为 `confirm`；
+- 当点击取消按钮时，`type` 为 `cancel`；
+- 当点击关闭按钮或遮罩时，`type` 为 `close`。
+
+`loading` 表示当前哪个按钮处于异步关闭状态。
+
+```ts
+type DialogBeforeClose = (
+  type: 'close' | 'cancel' | 'confirm',
+  loading: {
+    readonly cancel: boolean
+    readonly confirm: boolean
+    readonly close: boolean
+  },
+) => any | Promise<any>
+```
+
+### DialogSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### DialogEmits
+
+| 事件                             | 描述                        | 类型                               |
+| -------------------------------- | --------------------------- | ---------------------------------- |
+| update:visible                   | 对话框显隐时触发            | (visible: boolean) => void         |
+| close                            | 点击关闭按钮或遮罩时触发    | () => void                         |
+| cancel                           | 点击取消按钮时触发          | () => void                         |
+| confirm                          | 点击确定按钮时触发          | () => void                         |
+| visible-hook                     | 入场/退场动画状态改变时触发 | (name: TransitionHookName) => void |
+| before-enter <sup>1.12+</sup>    | 入场动画开始前触发          | () => void                         |
+| enter <sup>1.12+</sup>           | 入场动画开始时触发          | () => void                         |
+| after-enter <sup>1.12+</sup>     | 入场动画结束时触发          | () => void                         |
+| enter-cancelled <sup>1.12+</sup> | 入场动画取消时触发          | () => void                         |
+| before-leave <sup>1.12+</sup>    | 退场动画开始前触发          | () => void                         |
+| leave <sup>1.12+</sup>           | 退场动画开始时触发          | () => void                         |
+| after-leave <sup>1.12+</sup>     | 退场动画结束时触发          | () => void                         |
+| leave-cancelled <sup>1.12+</sup> | 退场动画取消时触发          | () => void                         |
+
+### DialogAgentProps / DialogOptions
+
+继承 [`DialogProps`](#DialogProps) 并有以下额外属性。
+
+| 属性 | 描述            | 类型   | 默认值   |
+| ---- | --------------- | ------ | -------- |
+| id   | 对话框组件的 id | string | 'dialog' |
+
+### 命令式方法
+
+| 名称    | 描述                         | 类型                     |
+| ------- | ---------------------------- | ------------------------ |
+| dialog  | 显示对话框                   | DialogFunction           |
+| alert   | 显示警告框                   | DialogSimpleShowFunction |
+| confirm | 显示确认框                   | DialogSimpleShowFunction |
+| hide    | 隐藏指定 `id` 的命令式对话框 | (id = 'dialog') => void  |
+| hideAll | 隐藏所有命令式对话框         | () => void               |
+
+### DialogFunction
+
+```ts
+type DialogFunction = DialogSimpleShowFunction & {
+  alert: DialogSimpleShowFunction
+  confirm: DialogSimpleShowFunction
+  hide: (id?: string) => void
+  hideAll: () => void
+}
+```
+
+### DialogSimpleShowFunction
+
+```ts
+interface DialogSimpleShowFunction {
+  (options: DialogOptions): void
+  (title: string, options?: DialogOptions): void
+}
+```
+
+### defaultDialogOptions
+
+命令式默认值和声明式有所区别。
+
+```ts
+const defaultDialogOptions = {
+  headed: false,
+  buttonType: 'text',
+  showCancel: false,
+}
+```
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')