sard-uniapp 1.19.2 → 1.19.4

package/components/tag/tag.vue

@@ -15,6 +15,20 @@ import SarIcon from "../icon/icon.vue";
 import {
   defaultTagProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'danger'} theme 主题色，默认值：'primary'。
+ * @property {boolean} round 圆角按标签，默认值：false。
+ * @property {boolean} plain 镂空标签，默认值：false。
+ * @property {boolean | 'left' | 'right'} mark 标记标签，默认值：false。
+ * @property {'small' | 'medium' | 'large'} size 标签尺寸，默认值：'medium'。
+ * @property {string} color 标签颜色，默认值：-。
+ * @property {string} textColor 文本颜色，默认值：-。
+ * @property {boolean} closable 是否可关闭，默认值：false。
+ * @event {(event: any) => void} click 点击标签时触发
+ * @event {(event: any) => void} close 点击关闭按钮时触发
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/timeline/README.md

@@ -0,0 +1,66 @@
+---
+nav: 组件
+title: Timeline
+subtitle: 时间轴
+group: 数据展示
+version: 1.6+
+---
+
+## 介绍
+
+垂直展示的时间流信息。
+
+## 引入
+
+```ts
+import Timeline from 'sard-uniapp/components/timeline/timeline.vue'
+import TimelineItem from 'sard-uniapp/components/timeline-item/timeline-item.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+@code('${DEMO_PATH}/timeline/demo/Basic.vue')
+
+## API
+
+### TimelineProps
+
+| 属性       | 描述           | 类型       | 默认值 |
+| ---------- | -------------- | ---------- | ------ |
+| root-class | 组件根元素类名 | string     | -      |
+| root-style | 组件根元素样式 | StyleValue | -      |
+
+### TimelineSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### TimelineItemProps
+
+| 属性        | 描述           | 类型       | 默认值 |
+| ----------- | -------------- | ---------- | ------ |
+| root-class  | 组件根元素类名 | string     | -      |
+| root-style  | 组件根元素样式 | StyleValue | -      |
+| title       | 标题内容       | string     | -      |
+| time        | 时间内容       | string     | -      |
+| icon        | 自定义图标     | string     | -      |
+| icon-family | 图标字体       | string     | -      |
+| icon-color  | 图标颜色       | string     | -      |
+
+### TimelineItemSlots
+
+| 插槽    | 描述                                | 属性 |
+| ------- | ----------------------------------- | ---- |
+| default | 自定义默认内容                      | -    |
+| icon    | 自定义图标内容，会覆盖 `icon` 属性  | -    |
+| title   | 自定义标题内容，会覆盖 `title` 属性 | -    |
+| time    | 自定义时间内容，会覆盖 `time` 属性  | -    |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/timeline/timeline.vue

@@ -8,6 +8,10 @@
 import { defineComponent as _defineComponent } from "vue";
 import { computed } from "vue";
 import { classNames, stringifyStyle, createBem } from "../../utils";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/timeline-item/timeline-item.vue

@@ -31,6 +31,15 @@ import { defineComponent as _defineComponent } from "vue";
 import { computed } from "vue";
 import { classNames, stringifyStyle, createBem } from "../../utils";
 import SarIcon from "../icon/icon.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} title 标题内容，默认值：-。
+ * @property {string} time 时间内容，默认值：-。
+ * @property {string} icon 自定义图标，默认值：-。
+ * @property {string} iconFamily 图标字体，默认值：-。
+ * @property {string} iconColor 图标颜色，默认值：-。
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/toast/README.md

@@ -0,0 +1,111 @@
+---
+nav: 组件
+title: Toast
+subtitle: 轻提示
+group: 反馈组件
+---
+
+## 介绍
+
+在页面中间弹出黑色半透明提示，表示提示、结果、加载中状态。
+
+## 引入
+
+```ts
+import Toast from 'sard-uniapp/components/toast/toast.vue'
+import ToastAgent from 'sard-uniapp/components/toast-agent/toast-agent.vue'
+import { toast } from 'sard-uniapp'
+```
+
+## 代码演示
+
+### 基础使用
+
+先在页面放置代理组件。
+
+```tsx
+<sar-toast-agent />
+```
+
+接着便可以使用 `toast` 等方法显示提示。
+
+@code('${DEMO_PATH}/toast/demo/Basic.vue')
+
+### 自定义位置
+
+`Toast` 默认渲染在屏幕正中位置，通过 `position` 属性可以控制提示展示的位置。
+
+@code('${DEMO_PATH}/toast/demo/Placement.vue')
+
+### 加载中的背景
+
+默认显示加载类型的提示不会显示遮罩背景，设置 `overlay: true` 会显示黑色遮罩， 设置 `transparent: true` 会让背景变透明。
+
+@code('${DEMO_PATH}/toast/demo/Mask.vue')
+
+## API
+
+### ToastProps
+
+| 属性        | 描述                     | 类型                                       | 默认值   |
+| ----------- | ------------------------ | ------------------------------------------ | -------- |
+| type        | 提示框类型               | 'text' \| 'loading' \| 'success' \| 'fail' | 'text'   |
+| title       | 标题                     | string \| number                           | -        |
+| visible     | 是否可见                 | boolean                                    | -        |
+| position    | 提示框垂直方向放置的位置 | 'top' \| 'center' \| 'bottom'              | 'center' |
+| overlay     | 是否显示背景遮罩         | boolean                                    | false    |
+| transparent | 使背景透明               | boolean                                    | false    |
+| timeout     | 提示的延迟时间，单位 ms  | number                                     | 1500     |
+| duration    | 显隐动画时长，单位 ms    | number                                     | 300      |
+
+### ToastEmits
+
+| 事件           | 描述             | 类型                       |
+| -------------- | ---------------- | -------------------------- |
+| update:visible | 对话框显隐时触发 | (visible: boolean) => void |
+
+### ToastAgentProps / ToastOptions
+
+继承 [`ToastProps`](#ToastProps) 并有以下额外属性。
+
+| 属性 | 描述          | 类型   | 默认值  |
+| ---- | ------------- | ------ | ------- |
+| id   | 提示组件的 id | string | 'toast' |
+
+### 命令式方法
+
+| 名称    | 描述                       | 类型                    |
+| ------- | -------------------------- | ----------------------- |
+| toast   | 显示提示                   | ToastFunction           |
+| success | 显示成功类型提示           | ToastSimpleShowFunction |
+| fail    | 显示失败类型提示           | ToastSimpleShowFunction |
+| loading | 显示加载类型提示           | ToastSimpleShowFunction |
+| hide    | 隐藏指定 `id` 的命令式提示 | (id = 'toast') => void  |
+| hideAll | 隐藏所有命令式提示         | () => void              |
+
+### ToastFunction
+
+```ts
+type ToastFunction = ToastSimpleShowFunction & {
+  success: ToastSimpleShowFunction
+  fail: ToastSimpleShowFunction
+  loading: ToastSimpleShowFunction
+  hide: (id?: string) => void
+  hideAll: () => void
+}
+```
+
+### ToastSimpleShowFunction
+
+```ts
+interface ToastSimpleShowFunction {
+  (options: ToastOptions): void
+  (title?: string | number, options?: ToastOptions): void
+}
+```
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/toast/toast.vue

@@ -35,6 +35,17 @@ const __default__ = {
   }
 };
 export const mapIdToast = {};
+/**
+ * @property {'text' | 'loading' | 'success' | 'fail'} type 提示框类型，默认值：'text'。
+ * @property {string | number} title 标题，默认值：-。
+ * @property {boolean} visible 是否可见，默认值：-。
+ * @property {'top' | 'center' | 'bottom'} position 提示框垂直方向放置的位置，默认值：'center'。
+ * @property {boolean} overlay 是否显示背景遮罩，默认值：false。
+ * @property {boolean} transparent 使背景透明，默认值：false。
+ * @property {number} timeout 提示的延迟时间，单位 ms，默认值：1500。
+ * @property {number} duration 显隐动画时长，单位 ms，默认值：300。
+ * @event {(visible: boolean) => void} update 对话框显隐时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopup,

package/components/toast-agent/toast-agent.vue

@@ -23,6 +23,17 @@ import {
   defaultToastAgentProps
 } from "./common";
 import { useImperative } from "../../use/useImperative";
+/**
+ * @property {'text' | 'loading' | 'success' | 'fail'} type 提示框类型，默认值：'text'。
+ * @property {string | number} title 标题，默认值：-。
+ * @property {boolean} visible 是否可见，默认值：-。
+ * @property {'top' | 'center' | 'bottom'} position 提示框垂直方向放置的位置，默认值：'center'。
+ * @property {boolean} overlay 是否显示背景遮罩，默认值：false。
+ * @property {boolean} transparent 使背景透明，默认值：false。
+ * @property {number} timeout 提示的延迟时间，单位 ms，默认值：1500。
+ * @property {number} duration 显隐动画时长，单位 ms，默认值：300。
+ * @property {string} id 提示组件的 id，默认值：'toast'。
+ */
 export default  _defineComponent({
   components: {
     SarToast,

package/components/tree/README.md

@@ -0,0 +1,208 @@
+---
+nav: 组件
+title: Tree
+subtitle: 树形
+group: 数据展示
+version: 1.6+
+---
+
+## 介绍
+
+用于显示层次结构数据，可展开或折叠。
+
+## 引入
+
+```ts
+import Tree from 'sard-uniapp/components/tree/tree.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+通过 `data` 属性设置数据，通过 `node-keys` 属性告知如何从传入的数据中获取每个节点的数据。
+
+@code('${DEMO_PATH}/tree/demo/Basic.vue')
+
+### 手风琴
+
+对于同一级的节点，每次只能展开一个。
+
+@code('${DEMO_PATH}/tree/demo/Accordion.vue')
+
+### 可选择的
+
+设置 `selectable` 属性可以显示复选框让用户选择节点，还可以禁用节点的选择。
+
+节点的 `key` 属性是非常重要的（可以自定义 `key` 的键名），必须保证节点的 `key` 在所有节点中的唯一性。
+如果没有设置 `key`，则由程序生成一个全局唯一的标识作为 `key`。
+
+@code('${DEMO_PATH}/tree/demo/Selectable.vue')
+
+### 严格选择
+
+在显示复选框的情况下，设置 `check-strictly` 属性来严格遵循父子不互相关联规则。
+
+@code('${DEMO_PATH}/tree/demo/CheckStrictly.vue')
+
+### 默认展开以及默认选中
+
+树节点可以在初始化阶段被设置为展开和选中。
+
+@code('${DEMO_PATH}/tree/demo/DefaultExpandedAndChecked.vue')
+
+### 单一选择
+
+设置 `single-selectable` 属性即可实现单选，选择后会触发 `select` 事件，可使用 `current` 属性设置当前选择的节点。
+
+@code('${DEMO_PATH}/tree/demo/Single.vue')
+
+### 仅选择叶子节点
+
+设置 `leaf-only` 属性让其仅能选择叶子节点。
+
+此时，点击节点任意位置都能选择节点，而不仅仅是单选按钮，因为折叠和选择操作不冲突。
+
+@code('${DEMO_PATH}/tree/demo/LeafOnly.vue')
+
+### 可拖拽的
+
+设置 `draggable` 属性使节点可拖拽，短按拖拽按钮便可进入拖拽状态；
+单击拖拽按钮，还可以设置节点的层级。
+
+@code('${DEMO_PATH}/tree/demo/Draggable.vue')
+
+### 可编辑的
+
+设置 `editable` 属性使节点可编辑（增删改），配合 `draggable` 属性便可以随意编辑树形数据。
+
+@code('${DEMO_PATH}/tree/demo/Editable.vue')
+
+### 树节点过滤
+
+树节点是可以被过滤的。
+
+调用 `filter` 方法来过滤树节点。方法的参数就是过滤关键字。
+通过设置 `filter-method` 属性还可以实现自定义的过滤。
+
+@code('${DEMO_PATH}/tree/demo/Filter.vue')
+
+### 严格的树节点过滤
+
+默认的过滤是宽松的，即匹配到一个节点后便停止后代节点的匹配，其后代节点都会被显示出来。
+
+设置 `filter-mode="strict"` 进入严格模式，即所有节点都要进行匹配，只有匹配成功的节点才会显示出来。
+
+@code('${DEMO_PATH}/tree/demo/StrictFilter.vue')
+
+## API
+
+### TreeProps
+
+| 属性                               | 描述                                       | 类型                                            | 默认值          |
+| ---------------------------------- | ------------------------------------------ | ----------------------------------------------- | --------------- |
+| root-class                         | 组件根元素类名                             | string                                          | -               |
+| root-style                         | 组件根元素样式                             | StyleValue                                      | -               |
+| data                               | 树形数据                                   | TreeNode[]                                      | -               |
+| node-keys                          | 节点对象的键名                             | TreeNodeKeys                                    | defaultNodeKeys |
+| default-expand-all                 | 是否默认展开所有节点                       | boolean                                         | false           |
+| default-expanded-keys              | 默认展开的节点的 key                       | (string \| number)[]                            | -               |
+| accordion                          | 是否每次只展示一个同级树节点               | boolean                                         | false           |
+| selectable                         | 节点是否可被选择（复选）                   | boolean                                         | false           |
+| check-strictly                     | 可选时是否严格遵循父子不关联的做法（复选） | boolean                                         | false           |
+| default-checked-keys               | 默认勾选的节点的 key 的数组（复选）        | (string \| number)[]                            | -               |
+| single-selectable <sup>1.17+</sup> | 节点是否可被选择（单选）                   | boolean                                         | false           |
+| leaf-only <sup>1.17+</sup>         | 是否只能选择叶子节点（单选）               | boolean                                         | false           |
+| current (v-model) <sup>1.17+</sup> | 当前选择的节点的 key（单选）               | string \| number                                | -               |
+| draggable                          | 是否可以拖拽节点                           | boolean                                         | false           |
+| editable                           | 是否可编辑节点（增删改）                   | boolean                                         | false           |
+| filter-mode                        | 节点过滤模式                               | 'lenient' \| 'strict'                           | 'lenient'       |
+| filter-method                      | 自定义过滤方法                             | (value: string, node: TreeStateNode) => boolean | -               |
+
+### TreeEmits
+
+| 事件                            | 描述                   | 类型                                                 |
+| ------------------------------- | ---------------------- | ---------------------------------------------------- |
+| update:current <sup>1.17+</sup> | 选择节点后触发（单选） | (key: string \| number, node: TreeStateNode) => void |
+| select <sup>1.17+</sup>         | 选择节点后触发（单选） | (key: string \| number, node: TreeStateNode) => void |
+
+### TreeExpose
+
+| 属性               | 描述                   | 类型                                               |
+| ------------------ | ---------------------- | -------------------------------------------------- |
+| getCheckedKeys     | 获取所有选中节点的 key | () => (string \| number)[]                         |
+| getHalfCheckedKeys | 获取所有半选节点的 key | () => (string \| number)[]                         |
+| setCheckedKeys     | 设置指定节点为选中状态 | (keys: (string \| number)[]) => void               |
+| setChecked         | 设置节点是否选中       | (key: string \| number, checked: boolean) => void  |
+| setExpandedKeys    | 设置指定节点为展开状态 | (keys: (string \| number)[]) => void               |
+| setExpanded        | 设置节点是否展开       | (key: string \| number, expanded: boolean) => void |
+| toggleExpanded     | 切换节点展开状态       | (key: string \| number) => void                    |
+| addRootNode        | 添加根节点             | () => void                                         |
+| getCleanTreeData   | 获取干净的当前树形数据 | () => TreeCleanNode[]                              |
+| filter             | 过滤树节点             | (searchString: string) => void                     |
+
+### TreeNode
+
+```ts
+interface TreeNode {
+  title?: string | number
+  key?: any
+  children?: TreeNode[]
+  disabled?: boolean
+  [prop: string]: any
+}
+```
+
+### TreeCleanNode
+
+```ts
+interface TreeCleanNode {
+  title: string | number
+  key: string | number
+  children?: TreeCleanNode[]
+}
+```
+
+### TreeStateNode
+
+```ts
+interface TreeStateNode {
+  title: string | number
+  key: string | number
+  expanded: boolean
+  checked: boolean
+  children?: TreeStateNode[]
+  parent: TreeStateNode | null
+  indeterminate: boolean
+  level: number
+  offsetLevel: number
+  visible: boolean
+  disabled: boolean
+}
+```
+
+### TreeNodeKeys
+
+```ts
+interface TreeNodeKeys {
+  title?: string
+  key?: string
+  children?: string
+}
+```
+
+### defaultNodeKeys
+
+```ts
+const defaultNodeKeys = {
+  title: 'title',
+  key: 'key',
+  children: 'children',
+}
+```
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/tree/tree.vue

@@ -55,6 +55,27 @@ import SarDialog from "../dialog/dialog.vue";
 import SarToast from "../toast/toast.vue";
 import { useTranslate } from "../locale";
 import { recurAncestor, recurDescendant, recurNodes } from "./utils";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {TreeNode[]} data 树形数据，默认值：-。
+ * @property {TreeNodeKeys} nodeKeys 节点对象的键名，默认值：defaultNodeKeys。
+ * @property {boolean} defaultExpandAll 是否默认展开所有节点，默认值：false。
+ * @property {(string | number)[]} defaultExpandedKeys 默认展开的节点的 key，默认值：-。
+ * @property {boolean} accordion 是否每次只展示一个同级树节点，默认值：false。
+ * @property {boolean} selectable 节点是否可被选择（复选），默认值：false。
+ * @property {boolean} checkStrictly 可选时是否严格遵循父子不关联的做法（复选），默认值：false。
+ * @property {(string | number)[]} defaultCheckedKeys 默认勾选的节点的 key 的数组（复选），默认值：-。
+ * @property {boolean} singleSelectable 节点是否可被选择（单选），默认值：false。
+ * @property {boolean} leafOnly 是否只能选择叶子节点（单选），默认值：false。
+ * @property {string | number} current 当前选择的节点的 key（单选），默认值：-。
+ * @property {boolean} draggable 是否可以拖拽节点，默认值：false。
+ * @property {boolean} editable 是否可编辑节点（增删改），默认值：false。
+ * @property {'lenient' | 'strict'} filterMode 节点过滤模式，默认值：'lenient'。
+ * @property {(value: string, node: TreeStateNode) => boolean} filterMethod 自定义过滤方法，默认值：-。
+ * @event {(key: string | number, node: TreeStateNode) => void} update 选择节点后触发（单选）
+ * @event {(key: string | number, node: TreeStateNode) => void} select 选择节点后触发（单选）
+ */
 export default  _defineComponent({
   components: {
     SarTreeNode,

package/components/upload/README.md

@@ -0,0 +1,154 @@
+---
+nav: 组件
+title: Upload
+subtitle: 上传
+group: 表单组件
+---
+
+## 介绍
+
+控制文件的上传及状态展示。
+
+## 引入
+
+```ts
+import Upload from 'sard-uniapp/components/upload/upload.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+选择文件后通过 `afterRead` 将文件上传到服务器。期间通过 `UploadFileItem['status']` 和 `UploadFileItem['message']` 修改上传的状态。
+
+@code('${DEMO_PATH}/upload/demo/Basic.vue')
+
+### 上传视频
+
+默认只能选择图片，可以设置 `accept="video"` 来选择上传视频。
+
+@code('${DEMO_PATH}/upload/demo/Video.vue')
+
+### 限定上传数量
+
+通过 `maxCount` 属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏选择区域。
+
+@code('${DEMO_PATH}/upload/demo/MaxCount.vue')
+
+### 多选
+
+默认一次只能选择一张图片，设置 `multiple` 允许图片多选。
+
+@code('${DEMO_PATH}/upload/demo/Multiple.vue')
+
+### 选择文件前置处理 <sup>1.19.2+</sup>
+
+通过传入 `beforeChoose` 函数可以在选择之前做处理，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择。
+
+@code('${DEMO_PATH}/upload/demo/BeforeChoose.vue')
+
+### 上传前置处理
+
+通过传入 `beforeRead` 函数可以在上传前进行校验和处理，返回 `true` 表示校验通过，返回 `false` 表示校验失败。支持返回 `Promise` 对 `file` 对象进行自定义处理。
+
+@code('${DEMO_PATH}/upload/demo/BeforeRead.vue')
+
+### 限定上传大小
+
+通过 `maxSize` 属性可以限制上传文件的大小，超过大小的文件会被自动过滤，这些文件信息可以通过 `overSize` 事件获取。
+
+@code('${DEMO_PATH}/upload/demo/Size.vue')
+
+### 上传状态
+
+通过 `status` 属性可以标识上传状态，`uploading` 表示上传中，`failed` 表示上传失败，`done` 表示上传完成。
+
+@code('${DEMO_PATH}/upload/demo/Status.vue')
+
+### 只读和禁用
+
+只读会隐藏选择区域，禁用则不允许用户点击选择。
+
+@code('${DEMO_PATH}/upload/demo/DisabledReadOnly.vue')
+
+### 自定义选区样式
+
+使用 `select` 插槽自定义选区内容。
+
+@code('${DEMO_PATH}/upload/demo/CustomSelect.vue')
+
+## API
+
+### UploadProps
+
+| 属性                             | 描述                                                                                                              | 类型                                                                   | 默认值                     |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------- |
+| root-class                       | 组件根元素类名                                                                                                    | string                                                                 | -                          |
+| root-style                       | 组件根元素样式                                                                                                    | StyleValue                                                             | -                          |
+| accept                           | 允许上传的文件类型                                                                                                | 'image' \| 'video'                                                     | 'image'                    |
+| multiple                         | 是否开启图片多选                                                                                                  | boolean                                                                | false                      |
+| source-type                      | 文件选择来源                                                                                                      | ('album' \| 'camera')[]                                                | ['album', 'camera']        |
+| size-type                        | 所选的图片的尺寸                                                                                                  | ('original' \| 'compressed')[]                                         | ['original', 'compressed'] |
+| max-duration                     | 拍摄视频最长拍摄时间，单位秒                                                                                      | number                                                                 | 60                         |
+| camera                           | 默认拉起的是前置或者后置摄像头。部分 Android 手机下由于系统 ROM 不支持无法生效                                    | 'back' \| 'front'                                                      | 'back'                     |
+| model-value (v-model)            | 已上传的文件列表                                                                                                  | UploadFileItem[]                                                       | -                          |
+| max-count                        | 文件上传数量限制                                                                                                  | number                                                                 | Number.MAX_SAFE_INTEGER    |
+| max-size                         | 文件大小限制，单位为 `byte`                                                                                       | number \| ((file: File) => boolean)                                    | Number.MAX_SAFE_INTEGER    |
+| over-size                        | 文件大小超过限制时触发                                                                                            | (fileItem: UploadFileItem \| UploadFileItem[]) => void                 | -                          |
+| disabled                         | 是否禁用文件上传                                                                                                  | boolean                                                                | false                      |
+| readonly                         | 是否将上传区域设置为只读状态                                                                                      | boolean                                                                | false                      |
+| before-choose <sup>1.19.2+</sup> | 文件选择前的回调，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择 | (fileList: UploadFileItem[], next: (allowed: boolean) => void) => void | -                          |
+| before-read                      | 文件读取前的回调，返回 false 可终止文件读取，支持返回 Promise                                                     | (file: File) => boolean \| Promise\<File>                              | -                          |
+| after-read                       | 文件读取完成后的回调                                                                                              | (fileItem: UploadFileItem \| UploadFileItem[]) => void                 | -                          |
+| removable                        | 是否可删除                                                                                                        | boolean                                                                | true                       |
+| before-remove                    | 文件删除前的回调，返回 false 可终止文件读取，支持返回 Promise                                                     | (...args: any[]) => boolean \| Promise\<void>                          | -                          |
+| validate-event                   | 是否触发表单验证                                                                                                  | boolean                                                                | true                       |
+
+### UploadSlots
+
+| 插槽   | 描述           | 属性 |
+| ------ | -------------- | ---- |
+| select | 自定义选取内容 | -    |
+
+### ButtonEmits
+
+| 事件                     | 描述                     | 类型                                          |
+| ------------------------ | ------------------------ | --------------------------------------------- |
+| update:model-value       | 选择的文件列表改变时触发 | (value: UploadFileItem[]) => void             |
+| change <sup>1.9.2+</sup> | 选择的文件列表改变时触发 | (value: UploadFileItem[]) => void             |
+| remove                   | 删除文件时触发           | (index: number, item: UploadFileItem) => void |
+
+### UploadFileItem
+
+| 属性     | 描述                                                                              | 类型         | 默认值    |
+| -------- | --------------------------------------------------------------------------------- | ------------ | --------- |
+| file     | 用户选择的文件                                                                    | UploadFile   | -         |
+| name     | 图片和视频之外的文件要展示的文件名，如果不指定且有 `file`，则获取 `file` 的文件名 | string       | -         |
+| url      | 图片的 `url`                                                                      | string       | -         |
+| is-image | 当无法从 `url` 中判断为图片时，可以显式指定为图片，以便可以对图片进行预览         | boolean      | false     |
+| is-video | 当无法从 `url` 中判断为视频时，可以显式指定为视频，以便可以对视频进行预览         | boolean      | false     |
+| status   | 指定预览图片的状态                                                                | UploadStatus | 'pending' |
+| message  | 展示预览图片在 `uploading`, `failed` 等状态下的说明文本                           | string       | -         |
+
+### UploadStatus
+
+```ts
+type UploadStatus = 'pending' | 'uploading' | 'failed' | 'done'
+```
+
+### UploadFile
+
+| 属性     | 描述               | 类型               | 默认值 |
+| -------- | ------------------ | ------------------ | ------ |
+| type     | 文件类型           | 'image' \| 'video' | -      |
+| size     | 文件大小，单位字节 | number             | -      |
+| path     | 本地临时文件路径   | string             | -      |
+| duration | 选定视频的时间长度 | number             | 0      |
+| width    | 返回选定视频的宽度 | number             | 0      |
+| height   | 返回选定视频的高度 | number             | 0      |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')