sard-uniapp 1.19.2 → 1.19.4

package/components/status-bar/README.md

@@ -0,0 +1,72 @@
+---
+nav: 组件
+title: StatusBar
+subtitle: 状态栏
+group: 布局
+version: 1.12+
+---
+
+## 介绍
+
+用于自定义导航栏时的状态栏占位，`Navbar`、`Notify` 等定位在顶部的元素会使用到。
+
+状态栏高度是通过 `uni.getSystemInfoSync().statusBarHeight` 获取的，在 `app`, `h5` 和小程序都可以直接使用，在 `h5` 端状态栏高度为 0，其他两个端为设备的状态栏的高度。
+
+@info
+如果应用是嵌套在 `app` 的 `webview` 中，`uniapp` 提供的接口获取的状态栏高度跟 `h5` 一样，都是 0；如果要全屏展示，则需要 `app` 原生那边提供接口来获取状态栏高度。
+
+针对此场景，要使 `StatusBar` 正常使用，需要全局设置 `StatusBar` 组件的 `height` 属性，且要设置为一个 `css` 变量，在获取到手机状态栏高度时，将其声明到 `html` 元素上。举例如下：
+
+```ts
+// main.ts
+
+// 1. 全局设置 `StatusBar` 组件的 `height` 属性
+// !!! 切记变量名不要设置为 `--status-bar-height`，避免被 uniapp 覆盖掉。
+import { setConfig } from 'sard-uniapp'
+setConfig({
+  statusBar: {
+    height: 'var(--app-status-bar-height)',
+  },
+})
+
+// 2. 获取状态栏高度
+// 假设接口如下
+const statusBarHeight = window.toggle.getBarHeight()
+
+// 3. 声明到 html 元素上
+document.documentElement.style.setProperty(
+  '--app-status-bar-height',
+  statusBarHeight + 'px',
+)
+```
+
+@endinfo
+
+## 引入
+
+```ts
+import StatusBar from 'sard-uniapp/components/status-bar/status-bar.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+@code('${DEMO_PATH}/status-bar/demo/Basic.vue')
+
+## API
+
+### StatusBarProps
+
+| 属性       | 描述                 | 类型       | 默认值 |
+| ---------- | -------------------- | ---------- | ------ |
+| root-class | 组件根元素类名       | string     | -      |
+| root-style | 组件根元素样式       | StyleValue | -      |
+| height     | 手动设置状态栏高度， | string     | -      |
+| reverse    | 设置宽度而不是高度   | boolean    | false  |
+
+### StatusBarSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |

package/components/status-bar/status-bar.vue

@@ -16,6 +16,12 @@ import {
 import {
   defaultStatusBarProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} height 手动设置状态栏高度，，默认值：-。
+ * @property {boolean} reverse 设置宽度而不是高度，默认值：false。
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/step/step.vue

@@ -5,7 +5,7 @@
       <view :class="bem.e('icon')">
         <slot name="icon" :status="currentStatus">
           <sar-icon
-            :family="context.iconFamily"
+            :family="context.iconFamily || 'sari'"
             :name="statusIcon"
             :size="context.iconSize"
           />
@@ -30,6 +30,14 @@ import { computed, inject } from "vue";
 import SarIcon from "../icon/icon.vue";
 import { classNames, stringifyStyle, createBem } from "../../utils";
 import { stepsContextSymbol } from "../steps/common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {StepsStatus} status 自定义状态，默认值：-。
+ * @property {string} name 步骤名称，默认值：-。
+ * @property {string} description 步骤描述，默认值：-。
+ * @property {number} index 步骤下标（必填），默认值：-。
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/stepper/README.md

@@ -0,0 +1,94 @@
+---
+nav: 组件
+title: Stepper
+subtitle: 步进器
+group: 表单组件
+---
+
+## 介绍
+
+通过键盘或按钮输入或改变数值。
+
+## 引入
+
+```ts
+import Stepper from 'sard-uniapp/components/stepper/stepper.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 绑定输入框值。
+
+@code('${DEMO_PATH}/stepper/demo/Basic.vue')
+
+### 最大最小值
+
+使用 `min` 和 `max` 属性限制可以输入的最大最小值。
+
+@code('${DEMO_PATH}/stepper/demo/MinMax.vue')
+
+### 步长
+
+使用 `step` 属性设置点击增加或减少按钮时变化的值。
+
+@code('${DEMO_PATH}/stepper/demo/Step.vue')
+
+### 精度
+
+使用 `precision` 属性设置数值的精度，即保留的小数位数，底层通过 `toFixed` 实现，因此需要设置大于等于 0 的整数。
+
+@code('${DEMO_PATH}/stepper/demo/Precision.vue')
+
+### 只读和禁用
+
+只读或禁用时无法输入。
+
+@code('${DEMO_PATH}/stepper/demo/DisabledReadOnly.vue')
+
+### 尺寸
+
+设置 `size="small"` 可以小尺寸展示步进器。
+
+@code('${DEMO_PATH}/stepper/demo/Size.vue')
+
+## API
+
+### StepperProps
+
+| 属性                  | 描述                                  | 类型                             | 默认值                  |
+| --------------------- | ------------------------------------- | -------------------------------- | ----------------------- |
+| root-class            | 组件根元素类名                        | string                           | -                       |
+| root-style            | 组件根元素样式                        | StyleValue                       | -                       |
+| model-value (v-model) | 当前输入值                            | number \| string                 | -                       |
+| min                   | 最小值                                | number                           | Number.MIN_SAFE_INTEGER |
+| max                   | 最大值                                | number                           | Number.MAX_SAFE_INTEGER |
+| value-on-clear        | 当输入框被清空时显示的值              | number \| null \| 'min' \| 'max' | null                    |
+| step                  | 点击按钮时增加或减少的数值            | number                           | 1                       |
+| precision             | 数值精度，即允许的小数位数            | number                           | -                       |
+| input-style           | 输入框样式                            | string                           | -                       |
+| input-type            | 输入框类型                            | 'number' \| 'digit' \| 'text'    | 'number'                |
+| placeholder           | 输入框占位符                          | string                           | -                       |
+| disabled              | 禁用状态                              | boolean                          | false                   |
+| readonly              | 只读状态                              | boolean                          | false                   |
+| press                 | 是否可以通过长按增加/减少按钮改变数值 | boolean                          | true                    |
+| press-time            | 触发长按事件的时间，单位毫秒          | boolean                          | 350                     |
+| interval              | 长按改变数值的时间间隔，单位毫秒      | number                           | 150                     |
+| validate-event        | 是否触发表单验证                      | boolean                          | true                    |
+| size                  | 步进器尺寸                            | 'medium' \| 'small'              | 'medium'                |
+
+### StepperEmits
+
+| 事件                     | 描述               | 类型                                           |
+| ------------------------ | ------------------ | ---------------------------------------------- |
+| update:model-value       | 输入框值改变时触发 | (value: number \| string \| undefined) => void |
+| change <sup>1.9.2+</sup> | 输入框值改变时触发 | (value: number \| string \| undefined) => void |
+| focus                    | 输入框聚焦时触发   | (event: any) => void                           |
+| blur                     | 输入框失焦时触发   | (event: any) => void                           |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/stepper/stepper.vue

@@ -64,6 +64,30 @@ import { useFormContext, useFormItemContext } from "../form/common";
 import {
   defaultStepperProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {number | string} modelValue 当前输入值，默认值：-。
+ * @property {number} min 最小值，默认值：Number.MIN_SAFE_INTEGER。
+ * @property {number} max 最大值，默认值：Number.MAX_SAFE_INTEGER。
+ * @property {number | null | 'min' | 'max'} valueOnClear 当输入框被清空时显示的值，默认值：null。
+ * @property {number} step 点击按钮时增加或减少的数值，默认值：1。
+ * @property {number} precision 数值精度，即允许的小数位数，默认值：-。
+ * @property {string} inputStyle 输入框样式，默认值：-。
+ * @property {'number' | 'digit' | 'text'} inputType 输入框类型，默认值：'number'。
+ * @property {string} placeholder 输入框占位符，默认值：-。
+ * @property {boolean} disabled 禁用状态，默认值：false。
+ * @property {boolean} readonly 只读状态，默认值：false。
+ * @property {boolean} press 是否可以通过长按增加/减少按钮改变数值，默认值：true。
+ * @property {boolean} pressTime 触发长按事件的时间，单位毫秒，默认值：350。
+ * @property {number} interval 长按改变数值的时间间隔，单位毫秒，默认值：150。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @property {'medium' | 'small'} size 步进器尺寸，默认值：'medium'。
+ * @event {(value: number | string | undefined) => void} update 输入框值改变时触发
+ * @event {(value: number | string | undefined) => void} change 输入框值改变时触发
+ * @event {(event: any) => void} focus 输入框聚焦时触发
+ * @event {(event: any) => void} blur 输入框失焦时触发
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/steps/README.md

@@ -0,0 +1,142 @@
+---
+nav: 组件
+title: Steps
+subtitle: 步骤条
+group: 导航组件
+---
+
+## 介绍
+
+引导用户按照流程完成任务的分步导航条。
+
+## 引入
+
+```ts
+import Steps from 'sard-uniapp/components/steps/steps.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `current` 属性指定步骤的下标，小于这个下标的步骤状态为 `finish`，等于这个下标的步骤状态为 `process`，大于这个下标的步骤状态为 `wait`。
+
+@code('${DEMO_PATH}/steps/demo/Basic.vue')
+
+### 居中
+
+居中每个步骤的图标和文案。
+
+@code('${DEMO_PATH}/steps/demo/Center.vue')
+
+### 垂直步骤条
+
+设置 `direction="vertical"` 可以垂直排列。
+
+@code('${DEMO_PATH}/steps/demo/Vertical.vue')
+
+### 垂直居中
+
+将图标和文案垂直居中。
+
+@code('${DEMO_PATH}/steps/demo/VerticalCenter.vue')
+
+### 自定义图标
+
+使用 `finishIcon, processIcon, waitIcon, errorIcon` 属性设置不通状态下的图标。
+
+@code('${DEMO_PATH}/steps/demo/Icon.vue')
+
+### 自定义颜色
+
+使用 `css` 变量设置元素样式。
+
+@code('${DEMO_PATH}/steps/demo/Color.vue')
+
+### 当前步骤状态
+
+可以设置当前处理中的步骤的状态为 `finish` 来模拟只有“未处理”和“已处理”两个状态的步骤条。
+
+@code('${DEMO_PATH}/steps/demo/Status.vue')
+
+### 错误步骤
+
+可以设置当前处理中的步骤的状态为 `error` 表示步骤运行错误。
+
+@code('${DEMO_PATH}/steps/demo/ErrorStatus.vue')
+
+### 自定义各步骤状态
+
+每个步骤都可以使用 `status` 属性设置其状态。
+
+@code('${DEMO_PATH}/steps/demo/StepStatus.vue')
+
+### 默认插槽
+
+版本 `1.17.1+` 可使用 `Step` 组件实现自定义内容，必须传递 `index` 属性。
+
+@code('${DEMO_PATH}/steps/demo/Slot.vue')
+
+## API
+
+### StepsProps
+
+| 属性         | 描述                 | 类型                       | 默认值       |
+| ------------ | -------------------- | -------------------------- | ------------ |
+| root-class   | 组件根元素类名       | string                     | -            |
+| root-style   | 组件根元素样式       | StyleValue                 | -            |
+| current      | 当前步骤对应的索引值 | number                     | 0            |
+| item-list    | 所有步骤的数据       | StepsItem[]                | []           |
+| center       | 是否居中             | boolean                    | false        |
+| direction    | 排列方向             | 'vertical' \| 'horizontal' | 'horizontal' |
+| status       | 指定当前步骤的状态   | StepsStatus                | -            |
+| icon-family  | 图标字体             | string                     | -            |
+| icon-size    | 图标字号             | string                     | -            |
+| finish-icon  | 已完成状态的图标名称 | string                     | -            |
+| process-icon | 处理中状态的图标名称 | string                     | -            |
+| wait-icon    | 等待中状态的图标名称 | string                     | -            |
+| error-icon   | 错误状态的图标名称   | string                     | -            |
+
+### StepsSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### StepProps
+
+| 属性        | 描述             | 类型        | 默认值 |
+| ----------- | ---------------- | ----------- | ------ |
+| root-class  | 组件根元素类名   | string      | -      |
+| root-style  | 组件根元素样式   | StyleValue  | -      |
+| status      | 自定义状态       | StepsStatus | -      |
+| name        | 步骤名称         | string      | -      |
+| description | 步骤描述         | string      | -      |
+| index       | 步骤下标（必填） | number      | -      |
+
+### StepSlots
+
+| 插槽    | 描述           | 属性                    |
+| ------- | -------------- | ----------------------- |
+| default | 自定义默认内容 | { status: StepsStatus } |
+| icon    | 自定义图标内容 | { status: StepsStatus } |
+
+### StepsItem
+
+| 属性        | 描述       | 类型        | 默认值 |
+| ----------- | ---------- | ----------- | ------ |
+| status      | 自定义状态 | StepsStatus | -      |
+| name        | 步骤名称   | string      | -      |
+| description | 步骤描述   | string      | -      |
+
+### StepsStatus
+
+```ts
+type StepsStatus = 'wait' | 'process' | 'error' | 'finish'
+```
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/steps/steps.vue

@@ -22,6 +22,21 @@ import {
   defaultStepsProps,
   stepsContextSymbol
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {number} current 当前步骤对应的索引值，默认值：0。
+ * @property {StepsItem[]} itemList 所有步骤的数据，默认值：[]。
+ * @property {boolean} center 是否居中，默认值：false。
+ * @property {'vertical' | 'horizontal'} direction 排列方向，默认值：'horizontal'。
+ * @property {StepsStatus} status 指定当前步骤的状态，默认值：-。
+ * @property {string} iconFamily 图标字体，默认值：-。
+ * @property {string} iconSize 图标字号，默认值：-。
+ * @property {string} finishIcon 已完成状态的图标名称，默认值：-。
+ * @property {string} processIcon 处理中状态的图标名称，默认值：-。
+ * @property {string} waitIcon 等待中状态的图标名称，默认值：-。
+ * @property {string} errorIcon 错误状态的图标名称，默认值：-。
+ */
 export default  _defineComponent({
   components: {
     SarStep,

package/components/style/README.md

@@ -0,0 +1,20 @@
+---
+nav: 组件
+title: Style
+subtitle: 样式
+group: 基础组件
+---
+
+## 介绍
+
+`sard-uniapp` 为了避免视觉传达差异，各组件用到的一些公用的颜色值、字号、圆角等统一进行了定义，并将变量值添加到 `page, .sar-portal` 选择器以便引用和自定义样式覆盖。
+
+可以通过 `CSS` 变量 来组织样式，通过覆盖这些 `CSS` 变量来实现定制样式、动态切换主题等效果。
+
+## 通用 CSS 变量
+
+@code('./variables.scss#variables')
+
+## 通用 CSS 变量 - 暗黑模式
+
+@code('./variables-dark.scss#variables')

package/components/swipe-action/README.md

@@ -0,0 +1,82 @@
+---
+nav: 组件
+title: SwipeAction
+subtitle: 滑动操作
+group: 反馈组件
+version: 1.19+
+---
+
+## 介绍
+
+可以左右滑动来展示操作按钮。
+
+## 引入
+
+```ts
+import SwipeAction from 'sard-uniapp/components/swipe-action/swipe-action.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `left`、`right` 插槽向左右两边添加操作按钮。
+
+插槽接收 `hide` 方法来隐藏操作按钮。
+
+@code('${DEMO_PATH}/swipe-action/demo/Basic.vue')
+
+### 控制显隐
+
+使用 `v-model:visible` 属性控制显隐。
+
+@code('${DEMO_PATH}/swipe-action/demo/Visible.vue')
+
+### 禁止滑动
+
+使用 `disabled` 属性来禁用滑动，同时也会禁用点击内容区域隐藏。
+
+@code('${DEMO_PATH}/swipe-action/demo/Visible.vue')
+
+### 异步关闭
+
+插槽按钮可任意定制；利用好 `hide` 方法和 `disabled` 属性，可实现复杂的效果。
+
+@code('${DEMO_PATH}/swipe-action/demo/Async.vue')
+
+### 结合表单使用
+
+下面演示了滑动操作组件如何与表单组件一起使用。
+
+@code('${DEMO_PATH}/swipe-action/demo/Form.vue')
+
+## API
+
+### SwipeActionProps
+
+| 属性              | 描述           | 类型                       | 默认值 |
+| ----------------- | -------------- | -------------------------- | ------ |
+| root-class        | 组件根元素类名 | string                     | -      |
+| root-style        | 组件根元素样式 | StyleValue                 | -      |
+| disabled          | 是否禁用滑动   | boolean                    | false  |
+| visible (v-model) | 控制显隐       | 'left' \| 'right' \| false | false  |
+
+### SwipeActionSlots
+
+| 插槽    | 描述               | 属性                 |
+| ------- | ------------------ | -------------------- |
+| default | 自定义默认内容     | -                    |
+| left    | 自定义左边操作按钮 | { hide: () => void } |
+| right   | 自定义右边操作按钮 | { hide: () => void } |
+
+### SwipeActionEmits
+
+| 事件           | 描述               | 类型                                          |
+| -------------- | ------------------ | --------------------------------------------- |
+| update:visible | 操作按钮显隐时触发 | (visible: 'left' \| 'right' \| false) => void |
+
+### SwipeActionExpose
+
+| 属性 | 描述         | 类型       |
+| ---- | ------------ | ---------- |
+| hide | 隐藏操作按钮 | () => void |

package/components/swipe-action/swipe-action.vue

@@ -44,6 +44,13 @@ import {
   getBoundingClientRect
 } from "../../utils";
 import { useMouseDown, useInitialVelocity, useStopMovedClick } from "../../use";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {boolean} disabled 是否禁用滑动，默认值：false。
+ * @property {'left' | 'right' | false} visible 控制显隐，默认值：false。
+ * @event {(visible: 'left' | 'right' | false) => void} update 操作按钮显隐时触发
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/swiper-dot/README.md

@@ -0,0 +1,45 @@
+---
+nav: 组件
+title: SwiperDot
+subtitle: 轮播图指示点
+group: 数据展示
+---
+
+## 介绍
+
+自定义轮播图指示点。
+
+## 引入
+
+```ts
+import SwiperDot from 'sard-uniapp/components/swiper-dot/swiper-dot.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用一个相对定位的容器包裹轮播图组件和轮播图指示点组件，
+使用 `current` 属性设置活动指示点，使用 `type` 属性设置指示点类型，使用 `total` 属性设置指示点总数或者使用 `list` 属性设置指示文本（用于 `title` 类型）。
+
+@code('${DEMO_PATH}/swiper-dot/demo/Basic.vue')
+
+## API
+
+### SwiperDotProps
+
+| 属性       | 描述                                 | 类型                                                   | 默认值  |
+| ---------- | ------------------------------------ | ------------------------------------------------------ | ------- |
+| root-class | 组件根元素类名                       | string                                                 | -       |
+| root-style | 组件根元素样式                       | StyleValue                                             | -       |
+| type       | 指示点类型                           | 'dot' \| 'dot-bar' \| 'index' \| 'title' \| 'fraction' | 'dot'   |
+| current    | 当前指示点索引                       | number                                                 | 0       |
+| total      | 指示点总数                           | number                                                 | 0       |
+| list       | 用于 `title` 类型的文本数据          | any[]                                                  | -       |
+| field      | `type` 为 `title` 时，显示的内容字段 | string                                                 | 'title' |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/swiper-dot/swiper-dot.vue

@@ -28,6 +28,15 @@ import { mergeDefaults as _mergeDefaults, defineComponent as _defineComponent }
 import { computed } from "vue";
 import { classNames, stringifyStyle, createBem } from "../../utils";
 import { defaultSwiperDotProps } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {'dot' | 'dot-bar' | 'index' | 'title' | 'fraction'} type 指示点类型，默认值：'dot'。
+ * @property {number} current 当前指示点索引，默认值：0。
+ * @property {number} total 指示点总数，默认值：0。
+ * @property {any[]} list 用于 `title` 类型的文本数据，默认值：-。
+ * @property {string} field `type` 为 `title` 时，显示的内容字段，默认值：'title'。
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/switch/README.md

@@ -0,0 +1,89 @@
+---
+nav: 组件
+title: Switch
+subtitle: 开关
+group: 表单组件
+---
+
+## 介绍
+
+用于打开/关闭两种状态间的切换。
+
+## 引入
+
+```ts
+import Switch from 'sard-uniapp/components/switch/switch.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+通过 `v-model` 绑定开关的选中状态，`true` 表示开，`false` 表示关。
+
+@code('${DEMO_PATH}/switch/demo/Basic.vue')
+
+### 自定义尺寸
+
+使用 `size` 属性设置开关尺寸。
+
+@code('${DEMO_PATH}/switch/demo/Size.vue')
+
+### 自定义颜色
+
+使用 `checkedColor` 属性设置打开时的颜色，使用 `uncheckedColor` 属性设置关闭时的颜色。
+
+@code('${DEMO_PATH}/switch/demo/Color.vue')
+
+### 不同状态的值
+
+可以设置 `checkedValue` 和 `uncheckedValue` 属性代替默认的 `true` 和 `false`。
+
+@code('${DEMO_PATH}/switch/demo/Value.vue')
+
+### 只读和禁用
+
+只读或禁用时不可操作。
+
+@code('${DEMO_PATH}/switch/demo/DisabledReadOnly.vue')
+
+### 加载状态
+
+当提供 `beforeUpdate` 函数，会在 `fulfilled` 状态后才切换，期间显示加载状态。
+
+@code('${DEMO_PATH}/switch/demo/Loading.vue')
+
+## API
+
+### SwitchProps
+
+| 属性                  | 描述             | 类型                          | 默认值 |
+| --------------------- | ---------------- | ----------------------------- | ------ |
+| root-class            | 组件根元素类名   | string                        | -      |
+| root-style            | 组件根元素样式   | StyleValue                    | -      |
+| model-value (v-model) | 开关选中状态     | any                           | -      |
+| disabled              | 禁用状态         | boolean                       | false  |
+| readonly              | 只读状态         | boolean                       | false  |
+| loading (v-model)     | 加载状态         | boolean                       | -      |
+| size                  | 开关大小         | string                        | -      |
+| checked-color         | 开启时的颜色     | string                        | -      |
+| unchecked-color       | 关闭时的颜色     | string                        | -      |
+| checked-value         | 开启时的值       | any                           | true   |
+| unchecked-value       | 关闭时的值       | any                           | false  |
+| before-update         | 用于异步切换     | (value: any) => Promise\<any> | -      |
+| validate-event        | 是否触发表单验证 | boolean                       | true   |
+
+### SwitchEmits
+
+| 事件                     | 描述                                   | 类型                       |
+| ------------------------ | -------------------------------------- | -------------------------- |
+| click                    | 点击按钮时触发，加载和禁用状态不会触发 | (event: any) => void       |
+| update:model-value       | 开关状态切换时触发                     | (value: any) => void       |
+| change <sup>1.9.2+</sup> | 开关状态切换时触发                     | (value: any) => void       |
+| update:loading           | 加载状态切换时触发                     | (loading: boolean) => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')