sard-uniapp 1.19.1 → 1.19.3

package/components/cascader-popout/cascader-popout.vue

@@ -34,8 +34,27 @@ import SarCascader from "../cascader/cascader.vue";
 import {
   defaultCascaderPopoutProps
 } from "./common";
-import { isNullish } from "../../utils";
+import { isEmptyBinding } from "../../utils";
 import { useFormPopout } from "../../use";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string | number} modelValue 选中项的值，默认值：-。
+ * @property {CascaderOption[]} options 可选项数据源，默认值：[]。
+ * @property {CascaderFieldKeys} fieldKeys 自定义 `options` 中的字段，默认值：defaultFieldKeys。
+ * @property {string} hintText 未选中时的提示文案，默认值：'请选择'。
+ * @property {(option: CascaderOption) => string} labelRender 自定义可选项渲染，默认值：-。
+ * @property {boolean} changeOnSelect 点击每级选项都会触发变化，默认值：false。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} showConfirm 是否显示确定按钮，隐藏按钮可用于快捷选择，默认值：true。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: string | number, selectedOptions: CascaderOption[]) => void} change 级联输入组件值改变时触发
+ * @event {(option: CascaderOption, tabIndex: number) => void} select 选择级联选择某一项时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopout,
@@ -74,7 +93,7 @@ export default  _defineComponent({
       emit,
       {
         onChange() {
-          if (!props.showConfirm && !isNullish(popoutValue.value)) {
+          if (!props.showConfirm && !isEmptyBinding(popoutValue.value)) {
             onConfirm();
             innerVisible.value = false;
           }

package/components/check-icon/variables.scss

@@ -3,7 +3,7 @@ page,
 .sar-portal {
   --sar-check-icon-size: 1em;
   --sar-check-icon-square-border-radius: 0.15em;
-  --sar-check-icon-border-color: var(--sar-quaternary-color);
+  --sar-check-icon-border-color: var(--sar-fourth-color);
 
   --sar-check-icon-disabled-color: var(--sar-disabled-color);
   --sar-check-icon-disabled-bg: var(--sar-disabled-shallow-bg);

package/components/checkbox/README.md

@@ -0,0 +1,185 @@
+---
+nav: 组件
+title: Checkbox
+subtitle: 复选框
+group: 表单组件
+---
+
+## 介绍
+
+在一组可选项中进行任意选择。
+
+## 引入
+
+```ts
+import Checkbox from 'sard-uniapp/components/checkbox/checkbox.vue'
+import CheckboxGroup from 'sard-uniapp/components/checkbox-group/checkbox-group.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `checked` 属性控制是否选中。
+
+@code('${DEMO_PATH}/checkbox/demo/Basic.vue')
+
+### 只读和禁用
+
+只读或禁用后不可点击。
+
+@code('${DEMO_PATH}/checkbox/demo/DisabledReadOnly.vue')
+
+### 图标大小
+
+使用 `size` 属性设置图标大小。
+
+@code('${DEMO_PATH}/checkbox/demo/Size.vue')
+
+### 图标颜色
+
+使用 `checked-color` 属性设置选中时的图标颜色。
+
+@code('${DEMO_PATH}/checkbox/demo/Color.vue')
+
+### 图标类型
+
+设置 `type` 属性为 `circle` 可以使图标变为圆形。
+
+@code('${DEMO_PATH}/checkbox/demo/Type.vue')
+
+### 自定义图标
+
+如果内置的图标不满足需求，可以使用 `icon` 插槽设置为任意的图标。
+插槽接收`checked`属性表示当前的选中状态。
+
+@code('${DEMO_PATH}/checkbox/demo/Icon.vue')
+
+### 复选框组
+
+复选框组用于收集选中状态的复选框的值。
+
+@code('${DEMO_PATH}/checkbox/demo/Group.vue')
+
+### 排列方向
+
+将 `direction` 属性设置为 `horizontal` 后，复选框组会变成水平排列。
+
+@code('${DEMO_PATH}/checkbox/demo/Direction.vue')
+
+### 自动渲染复选框
+
+使用 `options` 属性设置可选项。
+
+@code('${DEMO_PATH}/checkbox/demo/GroupOptions.vue')
+
+### 自定义 UI
+
+如果只想使用复选的逻辑，并想自定义 UI，可以使用复选框组的 `custom` 插槽。
+
+这个插槽接收 `toggle`方法和 `value` 属性作为参数。`toggle` 用于切换指定选项的选中状态，`value` 用于判断选中状态。
+
+@code('${DEMO_PATH}/checkbox/demo/Custom1.vue')
+
+结合 `list` 组件使用：
+
+@code('${DEMO_PATH}/checkbox/demo/Custom2.vue')
+
+复选框组里面 `checkbox` 组件，会自动判断选中状态；可以给 `checkbox` 组件添加 `readonly` 属性以便将点击操作交给其他组件。
+
+@code('${DEMO_PATH}/checkbox/demo/Custom3.vue')
+
+### 不确定状态
+
+@code('${DEMO_PATH}/checkbox/demo/Indeterminate.vue')
+
+## API
+
+### CheckboxProps
+
+| 属性                          | 描述                             | 类型                 | 默认值   |
+| ----------------------------- | -------------------------------- | -------------------- | -------- |
+| root-class                    | 组件根元素类名                   | string               | -        |
+| root-style                    | 组件根元素样式                   | StyleValue           | -        |
+| checked (v-model)             | 是否选中                         | boolean              | false    |
+| indeterminate <sup>1.6+</sup> | 是否处于不确定状态               | boolean              | false    |
+| value                         | 复选框的值，配合复选框组一起使用 | any                  | -        |
+| label                         | 复选框标签                       | string               | -        |
+| disabled                      | 禁用状态                         | boolean              | -        |
+| readonly                      | 只读状态                         | boolean              | -        |
+| size                          | 图标的尺寸                       | string               | -        |
+| type                          | 图标类型                         | 'square' \| 'circle' | 'square' |
+| checked-color                 | 选中时图标的颜色                 | string               | -        |
+| validate-event                | 是否触发表单验证                 | boolean              | true     |
+
+### CheckboxSlots
+
+| 插槽    | 描述           | 属性                 |
+| ------- | -------------- | -------------------- |
+| default | 自定义默认内容 | -                    |
+| icon    | 自定义图标     | { checked: boolean } |
+
+### CheckboxEmits
+
+| 事件           | 描述               | 类型                       |
+| -------------- | ------------------ | -------------------------- |
+| click          | 点击时触发         | (event: any) => void       |
+| update:checked | 选中状态改变时触发 | (checked: boolean) => void |
+| change         | 选中状态改变时触发 | (checked: boolean) => void |
+
+### CheckboxGroupProps
+
+| 属性                  | 描述                                  | 类型                    | 默认值                           |
+| --------------------- | ------------------------------------- | ----------------------- | -------------------------------- |
+| root-class            | 组件根元素类名                        | string                  | -                                |
+| root-style            | 组件根元素样式                        | StyleValue              | -                                |
+| model-value (v-model) | 指定选中的选项                        | any[]                   | -                                |
+| disabled              | 禁用状态                              | boolean                 | -                                |
+| readonly              | 只读状态                              | boolean                 | -                                |
+| size                  | 图标的尺寸                            | string                  | -                                |
+| type                  | 图标类型                              | 'square' \| 'circle'    | 'square'                         |
+| checked-color         | 选中时图标的颜色                      | string                  | -                                |
+| validate-event        | 是否触发表单验证                      | boolean                 | true                             |
+| options               | 自动设置复选框                        | CheckboxGroupOption[]   | -                                |
+| option-keys           | 自定义 options 的 label、value 的字段 | CheckboxGroupOptionKeys | {label: 'label', value: 'value'} |
+
+### CheckboxGroupOption
+
+```ts
+export type CheckboxGroupOption =
+  | {
+      [key: PropertyKey]: any
+    }
+  | string
+  | number
+  | boolean
+```
+
+### CheckboxGroupOptionKeys
+
+```ts
+export interface CheckboxGroupOptionKeys {
+  label?: string
+  value?: string
+}
+```
+
+### CheckboxGroupSlots
+
+| 插槽    | 描述                                                                           | 属性                                           |
+| ------- | ------------------------------------------------------------------------------ | ---------------------------------------------- |
+| default | 自定义默认内容                                                                 | -                                              |
+| custom  | 同默认插槽，额外可以接收 `toggle` 方法切换选中状态，用于自定义复选框结构和样式 | { toggle: (value: any) => void, value: any[] } |
+
+### CheckboxGroupEmits
+
+| 事件               | 描述                 | 类型                   |
+| ------------------ | -------------------- | ---------------------- |
+| update:model-value | 复选框组值改变时触发 | (value: any[]) => void |
+| change             | 复选框组值改变时触发 | (value: any[]) => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/checkbox/checkbox.vue

@@ -25,6 +25,23 @@ import {
 } from "./common";
 import SarCheckIcon from "../check-icon/check-icon.vue";
 import { useFormContext, useFormItemContext } from "../form/common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {boolean} checked 是否选中，默认值：false。
+ * @property {boolean} indeterminate 是否处于不确定状态，默认值：false。
+ * @property {any} value 复选框的值，配合复选框组一起使用，默认值：-。
+ * @property {string} label 复选框标签，默认值：-。
+ * @property {boolean} disabled 禁用状态，默认值：-。
+ * @property {boolean} readonly 只读状态，默认值：-。
+ * @property {string} size 图标的尺寸，默认值：-。
+ * @property {'square' | 'circle'} type 图标类型，默认值：'square'。
+ * @property {string} checkedColor 选中时图标的颜色，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @event {(event: any) => void} click 点击时触发
+ * @event {(checked: boolean) => void} update 选中状态改变时触发
+ * @event {(checked: boolean) => void} change 选中状态改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarCheckIcon,

package/components/checkbox/variables.scss

@@ -5,7 +5,7 @@ page,
   --sar-checkbox-group-row-gap: 16rpx;
 
   --sar-checkbox-icon-font-size: 40rpx;
-  --sar-checkbox-icon-color: var(--sar-quaternary-color);
+  --sar-checkbox-icon-color: var(--sar-fourth-color);
   --sar-checkbox-icon-checked-color: var(--sar-primary);
   --sar-checkbox-icon-disabled-color: var(--sar-disabled-color);
   --sar-checkbox-icon-transition-duration: var(--sar-duration);

package/components/checkbox-group/checkbox-group.vue

@@ -40,6 +40,21 @@ import {
 } from "../../utils";
 import { useFormItemContext } from "../form/common";
 import SarCheckbox from "../checkbox/checkbox.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {any[]} modelValue 指定选中的选项，默认值：-。
+ * @property {boolean} disabled 禁用状态，默认值：-。
+ * @property {boolean} readonly 只读状态，默认值：-。
+ * @property {string} size 图标的尺寸，默认值：-。
+ * @property {'square' | 'circle'} type 图标类型，默认值：'square'。
+ * @property {string} checkedColor 选中时图标的颜色，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @property {CheckboxGroupOption[]} options 自动设置复选框，默认值：-。
+ * @property {CheckboxGroupOptionKeys} optionKeys 自定义 options 的 label、value 的字段，默认值：{label: 'label', value: 'value'}。
+ * @event {(value: any[]) => void} update 复选框组值改变时触发
+ * @event {(value: any[]) => void} change 复选框组值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarCheckbox,

package/components/checkbox-input/README.md

@@ -0,0 +1,44 @@
+---
+nav: 组件
+title: CheckboxInput
+subtitle: 复选输入框
+group: 表单组件
+version: 1.3+
+---
+
+## 介绍
+
+组合了复选弹出框、列表、输入框组件，实现了在弹出框中多选的功能。
+
+## 引入
+
+```ts
+import CheckboxInput from 'sard-uniapp/components/checkbox-input/checkbox-input.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+通过 `title` 和 `placeholder` 属性设置弹出框标题和输入框占位文本，
+通过 `options` 属性设置可选项。
+
+@code('${DEMO_PATH}/checkbox-input/demo/Basic.vue')
+
+## API
+
+### CheckboxInputProps
+
+继承 [`CheckboxPopoutProps`](./checkbox-popout#CheckboxPopoutProps) 并有以下额外属性：
+
+| 属性                              | 描述                   | 类型       | 默认值          |
+| --------------------------------- | ---------------------- | ---------- | --------------- |
+| root-class                        | 弹出式输入框根元素类名 | string     | -               |
+| root-style                        | 弹出式输入框根元素样式 | StyleValue | -               |
+| clearable                         | 是否显示清空按钮       | boolean    | false           |
+| placeholder                       | 输入框占位符内容       | string     | -               |
+| value-on-clear <sup>1.19.2+</sup> | 设置点击清除按钮后的值 | () => any  | () => undefined |
+
+### CheckboxInputEmits
+
+继承 [`CheckboxPopoutEmits`](./checkbox-popout#CheckboxPopoutEmits)

package/components/checkbox-input/checkbox-input.d.ts

@@ -9,6 +9,7 @@ declare const _default: import("vue").DefineComponent<CheckboxInputProps, {}, {}
     "onUpdate:visible"?: ((visible: boolean) => any) | undefined;
 }>, {
     options: import("../checkbox/common").CheckboxGroupOption[];
+    valueOnClear: () => any;
     validateEvent: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/components/checkbox-input/checkbox-input.vue

@@ -40,8 +40,30 @@ import {
 import {
   defaultCheckboxInputProps
 } from "./common";
-import { getMayPrimitiveOption, isNullish } from "../../utils";
+import { getMayPrimitiveOption, isEmptyBinding } from "../../utils";
 import { usePopoutInput } from "../../use";
+/**
+ * @property {string} rootClass 弹出式输入框根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 弹出式输入框根元素样式，默认值：-。
+ * @property {any[]} modelValue 指定选中的选项，默认值：-。
+ * @property {boolean} disabled 禁用状态，默认值：-。
+ * @property {boolean} readonly 只读状态，默认值：-。
+ * @property {string} size 图标的尺寸，默认值：-。
+ * @property {'square' | 'circle'} type 图标类型，默认值：'square'。
+ * @property {string} checkedColor 选中时图标的颜色，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @property {CheckboxGroupOption[]} options 自动设置复选框，默认值：-。
+ * @property {CheckboxGroupOptionKeys} optionKeys 自定义 options 的 label、value 的字段，默认值：{label: 'label', value: 'value'}。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} clearable 是否显示清空按钮，默认值：false。
+ * @property {string} placeholder 输入框占位符内容，默认值：-。
+ * @property {() => any} valueOnClear 设置点击清除按钮后的值，默认值：() => undefined。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: any[] | undefined) => void} change 复选输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopoutInput,
@@ -55,6 +77,7 @@ export default  _defineComponent({
   },
   __name: "checkbox-input",
   props:  _mergeDefaults({
+    valueOnClear: { type: Function, required: false },
     visible: { type: Boolean, required: false },
     title: { type: String, required: false },
     popoutClass: { type: String, required: false },
@@ -91,7 +114,7 @@ export default  _defineComponent({
       ).map((option) => getMayPrimitiveOption(option, optionKeys.label)).join(", ");
     }
     function getInputValue() {
-      if (isNullish(innerValue.value) || innerValue.value.length === 0) {
+      if (isEmptyBinding(innerValue.value) || Array.isArray(innerValue.value) && innerValue.value.length === 0) {
         return "";
       }
       return getOutletText(props.options, fieldKeys.value, innerValue.value);

package/components/checkbox-input/common.d.ts

@@ -3,8 +3,10 @@ import { type PopoutInputProps } from '../popout-input/common';
 import { type CheckboxPopoutEmits, type CheckboxPopoutProps } from '../checkbox-popout/common';
 export type CheckboxInputOption = CheckboxGroupOption;
 export interface CheckboxInputProps extends CheckboxPopoutProps, Omit<PopoutInputProps, 'modelValue'> {
+    valueOnClear?: () => any;
 }
 export declare const defaultCheckboxInputProps: () => {
+    valueOnClear: CheckboxInputProps["valueOnClear"];
     options: () => never[];
     validateEvent: boolean;
 };

package/components/checkbox-input/common.js

@@ -1,2 +1,6 @@
 import { defaultCheckboxPopoutProps, } from '../checkbox-popout/common';
-export const defaultCheckboxInputProps = defaultCheckboxPopoutProps;
+import { defaultConfig } from '../config';
+export const defaultCheckboxInputProps = () => ({
+    ...defaultCheckboxPopoutProps(),
+    ...defaultConfig.checkboxInput,
+});

package/components/checkbox-popout/README.md

@@ -0,0 +1,52 @@
+---
+nav: 组件
+title: CheckboxPopout
+subtitle: 复选弹出框
+group: 表单组件
+version: 1.16+
+---
+
+## 介绍
+
+组合了复选框组、列表、弹出框组件，实现了在弹出框中多选的功能。
+
+## 引入
+
+```ts
+import CheckboxPopout from 'sard-uniapp/components/checkbox-popout/checkbox-popout.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 双向绑定当前值，使用 `v-model:visible` 控制弹出框显隐。
+
+@code('${DEMO_PATH}/checkbox-popout/demo/Basic.vue')
+
+## API
+
+### CheckboxPopoutProps
+
+继承 [`CheckboxGroupProps`](./checkbox#CheckboxGroupProps) 并有以下额外属性：
+
+| 属性              | 描述             | 类型       | 默认值 |
+| ----------------- | ---------------- | ---------- | ------ |
+| popout-class      | 弹窗框根元素类名 | string     | -      |
+| popout-style      | 弹窗框根元素样式 | StyleValue | -      |
+| visible (v-model) | 是否显示弹出框   | boolean    | -      |
+| title             | 弹出框标题       | string     | -      |
+
+### CheckboxPopoutEmits
+
+| 事件                     | 描述                     | 类型                                |
+| ------------------------ | ------------------------ | ----------------------------------- |
+| update:model-value       | 复选输入组件值改变时触发 | (value: any[] \| undefined) => void |
+| change <sup>1.9.2+</sup> | 复选输入组件值改变时触发 | (value: any[] \| undefined) => void |
+| update:visible           | 弹出框显隐时触发         | (visible: boolean) => void          |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/checkbox-popout/checkbox-popout.vue

@@ -70,6 +70,25 @@ import {
 } from "./common";
 import { useScrollSide, useFormPopout } from "../../use";
 import { defaultOptionKeys } from "../checkbox/common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {any[]} modelValue 指定选中的选项，默认值：-。
+ * @property {boolean} disabled 禁用状态，默认值：-。
+ * @property {boolean} readonly 只读状态，默认值：-。
+ * @property {string} size 图标的尺寸，默认值：-。
+ * @property {'square' | 'circle'} type 图标类型，默认值：'square'。
+ * @property {string} checkedColor 选中时图标的颜色，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @property {CheckboxGroupOption[]} options 自动设置复选框，默认值：-。
+ * @property {CheckboxGroupOptionKeys} optionKeys 自定义 options 的 label、value 的字段，默认值：{label: 'label', value: 'value'}。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: any[] | undefined) => void} change 复选输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopout,

package/components/col/col.vue

@@ -11,6 +11,13 @@ import {
   rowSymbol
 } from "../layout/common";
 import { classNames, stringifyStyle, createBem } from "../../utils";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {number | 'auto' | 'none'} span 列元素宽度，默认值：-。
+ * @property {number} offset 列元素偏移距离，默认值：-。
+ * @property {number} order 列元素顺序，默认值：-。
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/collapse/README.md

@@ -0,0 +1,45 @@
+---
+nav: 组件
+title: Collapse
+subtitle: 折叠
+group: 数据展示
+---
+
+## 介绍
+
+可以展开/折叠内容区域。
+
+## 引入
+
+```ts
+import Collapse from 'sard-uniapp/components/collapse/collapse.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+折叠组件是其他可折叠组件的基础组件。
+使用 `visible` 属性控制折叠框展开或折叠。
+
+@code('${DEMO_PATH}/collapse/demo/Basic.vue')
+
+## API
+
+### CollapseProps
+
+| 属性    | 描述     | 类型    | 默认值 |
+| ------- | -------- | ------- | ------ |
+| visible | 是否可见 | boolean | false  |
+
+### CollapseSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/collapse/collapse.vue

@@ -24,6 +24,9 @@ import {
   uniqid,
   getBoundingClientRect
 } from "../../utils";
+/**
+ * @property {boolean} visible 是否可见，默认值：false。
+ */
 export default  _defineComponent({
   ...{
     options: {