sard-uniapp 1.19.2 → 1.19.3

package/components/picker/README.md

@@ -0,0 +1,115 @@
+---
+nav: 组件
+title: Picker
+subtitle: 选择器
+group: 表单组件
+---
+
+## 介绍
+
+一个或多个可滚动列表选择器。
+
+## 引入
+
+```ts
+import Picker from 'sard-uniapp/components/picker/picker.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+通过 `v-model` 绑定当前值，通过 `columns` 配置选项数据。
+
+@code('${DEMO_PATH}/picker/demo/Basic.vue')
+
+### 对象类型
+
+列的每一项可以为一个对象，使用 `optionKeys` 属性可以指定对象中哪个属性值为选中的值，哪个属性值为要显示的标签。
+
+@code('${DEMO_PATH}/picker/demo/ObjectOption.vue')
+
+### 多列
+
+当 `columns` 属性值为一个二维数组时会显示为多列。
+
+@code('${DEMO_PATH}/picker/demo/Multiple.vue')
+
+### 对象类型多列
+
+`columns` 属性值为对象类型的二维数组。
+
+@code('${DEMO_PATH}/picker/demo/ObjectMultiple.vue')
+
+### 级联选择
+
+当 `columns` 第一个元素为对象且其 `children` 属性值为数组时会被当作级联选择。
+
+@code('${DEMO_PATH}/picker/demo/Cascaded.vue')
+
+### 插槽
+
+可通过 `custom` 插槽自定义每一个选项的内容。
+
+@info
+
+因小程序不支持循环中的插槽，因此循环逻辑要自行实现；
+
+因 `picker-view-column` 要为 `picker-view` 的直接子元素，因此要把 `picker-view` 提取出来，要自行绑定属性和事件。
+
+@endinfo
+
+@code('${DEMO_PATH}/picker/demo/Slot.vue')
+
+## API
+
+### PickerProps
+
+| 属性             | 描述                                               | 类型                               | 默认值                                                 |
+| ---------------- | -------------------------------------------------- | ---------------------------------- | ------------------------------------------------------ |
+| root-class       | 组件根元素类名                                     | string                             | -                                                      |
+| root-style       | 组件根元素样式                                     | StyleValue                         | -                                                      |
+| columns          | 配置每一列的数据                                   | PickerOption[] \| PickerOption[][] | []                                                     |
+| option-keys      | 自定义 `columns` 结构中的字段                      | PickerOptionKeys                   | {label: 'label', value: 'value', children: 'children'} |
+| model-value      | 选中项的值                                         | any                                | -                                                      |
+| immediate-change | 是否在手指松开时立即触发 `update:model-value` 事件 | boolean                            | false                                                  |
+
+### PickerSlots
+
+| 插槽                    | 描述             | 属性                                                                                                                                      |
+| ----------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| custom <sup>1.17+</sup> | 自定义选项的内容 | { columns: any[][]; value: number[]; pickerViewClass: string; maskClass: string; indicatorClass: string; onChange: (event: any) => void;} |
+
+### PickerEmits
+
+| 事件                     | 描述                 | 类型                                                                     |
+| ------------------------ | -------------------- | ------------------------------------------------------------------------ |
+| update:model-value       | 选中的选项改变时触发 | (value: any, selectedOptions: PickerOption[], indexes: number[]) => void |
+| change <sup>1.9.2+</sup> | 选中的选项改变时触发 | (value: any, selectedOptions: PickerOption[], indexes: number[]) => void |
+
+### PickerOption
+
+```tsx
+type PickerOption =
+  | {
+      [key: PropertyKey]: any
+    }
+  | number
+  | string
+```
+
+### PickerOptionKeys
+
+```tsx
+interface PickerOptionKeys {
+  label?: string
+  value?: string
+  children?: string
+}
+```
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/picker/picker.vue

@@ -52,6 +52,16 @@ import {
   defaultPickerProps
 } from "./common";
 import SarPickerItem from "../picker-item/picker-item.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {PickerOption[] | PickerOption[][]} columns 配置每一列的数据，默认值：[]。
+ * @property {PickerOptionKeys} optionKeys 自定义 `columns` 结构中的字段，默认值：{label: 'label', value: 'value', children: 'children'}。
+ * @property {any} modelValue 选中项的值，默认值：-。
+ * @property {boolean} immediateChange 是否在手指松开时立即触发 `update:model-value` 事件，默认值：false。
+ * @event {(value: any, selectedOptions: PickerOption[], indexes: number[]) => void} update 选中的选项改变时触发
+ * @event {(value: any, selectedOptions: PickerOption[], indexes: number[]) => void} change 选中的选项改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPickerItem,

package/components/picker-input/README.md

@@ -0,0 +1,51 @@
+---
+nav: 组件
+title: PickerInput
+subtitle: 选择器输入框
+group: 表单组件
+---
+
+## 介绍
+
+组合了选择器弹出框、输入框组件，实现了便捷快速的选择功能。
+
+## 引入
+
+```ts
+import PickerInput from 'sard-uniapp/components/picker-input/picker-input.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 绑定当前值，通过 `title` 和 `placeholder` 属性设置弹出框标题和输入框占位文本。
+
+在点击输入框后会显示包裹选择器的弹出框。
+
+@code('${DEMO_PATH}/picker-input/demo/Basic.vue')
+
+## API
+
+### PickerInputProps
+
+继承 [`PickerPopoutProps`](./picker-popout#PickerPopoutProps) 并有以下额外属性：
+
+| 属性                              | 描述                   | 类型       | 默认值          |
+| --------------------------------- | ---------------------- | ---------- | --------------- |
+| root-class                        | 弹出式输入框根元素类名 | string     | -               |
+| root-style                        | 弹出式输入框根元素样式 | StyleValue | -               |
+| disabled                          | 禁用状态               | boolean    | false           |
+| readonly                          | 只读状态               | boolean    | false           |
+| loading                           | 加载状态               | boolean    | false           |
+| clearable                         | 是否显示清空按钮       | boolean    | false           |
+| placeholder                       | 输入框占位符内容       | string     | -               |
+| value-on-clear <sup>1.19.2+</sup> | 设置点击清除按钮后的值 | () => any  | () => undefined |
+
+### PickerSlots
+
+继承 [`PickerPopoutSlots`](./picker-popout#PickerPopoutSlots)
+
+### PickerInputEmits
+
+继承 [`PickerPopoutEmits`](./picker-popout#PickerPopoutEmits) 并有以下额外属性：

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

@@ -65,6 +65,27 @@ import { usePopoutInput } from "../../use";
 import {
   defaultPickerInputProps
 } from "./common";
+/**
+ * @property {string} rootClass 弹出式输入框根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 弹出式输入框根元素样式，默认值：-。
+ * @property {PickerOption[] | PickerOption[][]} columns 配置每一列的数据，默认值：[]。
+ * @property {PickerOptionKeys} optionKeys 自定义 `columns` 结构中的字段，默认值：{label: 'label', value: 'value', children: 'children'}。
+ * @property {any} modelValue 选中项的值，默认值：-。
+ * @property {boolean} immediateChange 是否在手指松开时立即触发 `update:model-value` 事件，默认值：false。
+ * @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} loading 加载状态，默认值：false。
+ * @property {boolean} clearable 是否显示清空按钮，默认值：false。
+ * @property {string} placeholder 输入框占位符内容，默认值：-。
+ * @property {() => any} valueOnClear 设置点击清除按钮后的值，默认值：() => undefined。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: any) => void} change 选择器输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopoutInput,

package/components/picker-popout/README.md

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

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

@@ -57,6 +57,21 @@ import { isEmptyBinding, isNumber } from "../../utils";
 import { defaultOptionKeys, getInitialValue } from "../picker/common";
 import { computed } from "vue";
 import { useFormPopout } from "../../use";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {PickerOption[] | PickerOption[][]} columns 配置每一列的数据，默认值：[]。
+ * @property {PickerOptionKeys} optionKeys 自定义 `columns` 结构中的字段，默认值：{label: 'label', value: 'value', children: 'children'}。
+ * @property {any} modelValue 选中项的值，默认值：-。
+ * @property {boolean} immediateChange 是否在手指松开时立即触发 `update:model-value` 事件，默认值：false。
+ * @property {string} popoutClass 弹窗框根元素类名，默认值：-。
+ * @property {StyleValue} popoutStyle 弹窗框根元素样式，默认值：-。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} validateEvent 是否触发表单验证，默认值：true。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: any) => void} change 选择器输入组件值改变时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopout,

package/components/popout/README.md

@@ -0,0 +1,111 @@
+---
+nav: 组件
+title: Popout
+subtitle: 弹出框
+group: 数据展示
+---
+
+## 介绍
+
+底部弹出框，可以控制组件的展示与交互，可作为其他组件的弹出框容器。
+
+## 引入
+
+```ts
+import Popout from 'sard-uniapp/components/popout/popout.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `visible`属性控制显隐，使用 `title` 属性设置标题。
+
+@code('${DEMO_PATH}/popout/demo/Basic.vue')
+
+### 紧凑类型
+
+通过将 `type` 设为 `compact` 可以将确定/取消按钮放到标题两侧，以便节省空间。
+
+@code('${DEMO_PATH}/popout/demo/Compact.vue')
+
+### 异步关闭
+
+如果 `beforeClose` 返回 false，则取消关闭弹出框；如果返回 `Promise` 对象，则会在 `resolve` 时才关闭弹出框。
+
+@code('${DEMO_PATH}/popout/demo/BeforeClose.vue')
+
+## API
+
+### PopoutProps
+
+| 属性              | 描述                                                                 | 类型                 | 默认值  |
+| ----------------- | -------------------------------------------------------------------- | -------------------- | ------- |
+| root-class        | 组件根元素类名                                                       | string               | -       |
+| root-style        | 组件根元素样式                                                       | StyleValue           | -       |
+| title             | 弹出框标题                                                           | string               | -       |
+| show-cancel       | 是否显示取消按钮，适用 `loose` 类型                                  | boolean              | false   |
+| cancel-text       | 取消按钮文案                                                         | string               | '取消'  |
+| show-confirm      | 是否显示确定按钮，适用 `loose` 类型                                  | boolean              | true    |
+| confirm-text      | 确定按钮文案                                                         | string               | '确定'  |
+| show-close        | 是否显示关闭按钮，适用 `loose` 类型                                  | boolean              | true    |
+| show-footer       | 是否显示底部按钮                                                     | boolean              | true    |
+| type              | 弹出框按钮排版方式                                                   | 'compact' \| 'loose' | 'loose' |
+| visible (v-model) | 是否显示弹出框                                                       | boolean              | -       |
+| before-close      | 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭 | PopoutBeforeClose    | -       |
+| duration          | 显隐动画时长，单位 ms                                                | number               | 300     |
+| overlay-closable  | 点击遮罩是否关闭                                                     | boolean              | true    |
+
+### PopoutBeforeClose
+
+- 当点击确定按钮时，`type` 为 `confirm`；
+- 当点击取消按钮时，`type` 为 `cancel`；
+- 当点击关闭按钮或遮罩时，`type` 为 `close`。
+
+`loading` 表示当前哪个按钮处于异步关闭状态。
+
+```ts
+type PopoutBeforeClose = (
+  type: 'close' | 'cancel' | 'confirm',
+  loading: {
+    readonly cancel: boolean
+    readonly confirm: boolean
+    readonly close: boolean
+  },
+) => any | Promise<any>
+```
+
+### PopoutSlots
+
+| 插槽                             | 描述                                                                                                                                                       | 属性                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| default                          | 自定义主体内容                                                                                                                                             | -                                    |
+| title                            | 自定义标题                                                                                                                                                 | -                                    |
+| title-prepend <sup>1.19.2+</sup> | 自定义标题前面内容                                                                                                                                         | -                                    |
+| cancel                           | 自定义确定按钮内容                                                                                                                                         | -                                    |
+| confirm                          | 自定义取消按钮内容                                                                                                                                         | -                                    |
+| visible                          | 同默认插槽，额外接收一些判断弹出框显示状态的属性，用于小程序端多节点渲染的性能问题；`whole` 当开始显示到完全隐藏时为真，`already` 当开始显示时到以后都为真 | { whole: boolean, already: boolean } |
+
+### PopoutEmits
+
+| 事件                             | 描述                        | 类型                               |
+| -------------------------------- | --------------------------- | ---------------------------------- |
+| 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                         |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/popout/popout.vue

@@ -111,6 +111,35 @@ import { useTranslate } from "../locale";
 import {
   defaultPopoutProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} title 弹出框标题，默认值：-。
+ * @property {boolean} showCancel 是否显示取消按钮，适用 `loose` 类型，默认值：false。
+ * @property {string} cancelText 取消按钮文案，默认值：'取消'。
+ * @property {boolean} showConfirm 是否显示确定按钮，适用 `loose` 类型，默认值：true。
+ * @property {string} confirmText 确定按钮文案，默认值：'确定'。
+ * @property {boolean} showClose 是否显示关闭按钮，适用 `loose` 类型，默认值：true。
+ * @property {boolean} showFooter 是否显示底部按钮，默认值：true。
+ * @property {'compact' | 'loose'} type 弹出框按钮排版方式，默认值：'loose'。
+ * @property {boolean} visible 是否显示弹出框，默认值：-。
+ * @property {PopoutBeforeClose} beforeClose 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭，默认值：-。
+ * @property {number} duration 显隐动画时长，单位 ms，默认值：300。
+ * @property {boolean} overlayClosable 点击遮罩是否关闭，默认值：true。
+ * @event {(visible: boolean) => void} update 显隐时触发
+ * @event {() => void} close 点击关闭按钮或遮罩时触发
+ * @event {() => void} cancel 点击取消按钮时触发
+ * @event {() => void} confirm 点击确定按钮时触发
+ * @event {(name: TransitionHookName) => void} visible-hook 入场/退场动画状态改变时触发
+ * @event {() => void} before-enter 入场动画开始前触发
+ * @event {() => void} enter 入场动画开始时触发
+ * @event {() => void} after-enter 入场动画结束时触发
+ * @event {() => void} enter-cancelled 入场动画取消时触发
+ * @event {() => void} before-leave 退场动画开始前触发
+ * @event {() => void} leave 退场动画开始时触发
+ * @event {() => void} after-leave 退场动画结束时触发
+ * @event {() => void} leave-cancelled 退场动画取消时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopup,

package/components/popout-input/README.md

@@ -0,0 +1,55 @@
+---
+nav: 组件
+title: PopoutInput
+subtitle: 弹出式输入框
+group: 表单组件
+---
+
+## 介绍
+
+输入框组件，用于配合弹出框组件和表单控件一起使用。自定义了输入框样式。
+
+## 引入
+
+```ts
+import PopoutInput from 'sard-uniapp/components/popout-input/popout-input.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model` 绑定值， `click` 事件监听点击事件。
+
+@code('${DEMO_PATH}/popout-input/demo/Basic.vue')
+
+## API
+
+### PopoutInputProps
+
+| 属性        | 描述             | 类型       | 默认值 |
+| ----------- | ---------------- | ---------- | ------ |
+| root-class  | 组件根元素类名   | string     | -      |
+| root-style  | 组件根元素样式   | StyleValue | -      |
+| model-value | 输入框值         | string     | -      |
+| placeholder | 输入框占位符内容 | string     | -      |
+| disabled    | 禁用状态         | boolean    | false  |
+| readonly    | 只读状态         | boolean    | false  |
+| loading     | 加载状态         | boolean    | false  |
+| clearable   | 是否显示清空按钮 | boolean    | false  |
+| multiline   | 是否多行输入框   | boolean    | false  |
+
+### PopoutInputEmits
+
+| 事件                     | 描述                               | 类型                    |
+| ------------------------ | ---------------------------------- | ----------------------- |
+| click                    | 点击输入框时触发，只读和禁用不触发 | () => void              |
+| update:model-value       | 输入框值改变时触发                 | (value: string) => void |
+| change <sup>1.9.2+</sup> | 输入框值改变时触发                 | (value: string) => void |
+| clear                    | 点击清除按钮时触发                 | () => void              |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/popout-input/popout-input.vue

@@ -53,6 +53,21 @@ import SarInput from "../input/input.vue";
 import SarIcon from "../icon/icon.vue";
 import { useFormContext } from "../form/common";
 import SarLoading from "../loading/loading.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} modelValue 输入框值，默认值：-。
+ * @property {string} placeholder 输入框占位符内容，默认值：-。
+ * @property {boolean} disabled 禁用状态，默认值：false。
+ * @property {boolean} readonly 只读状态，默认值：false。
+ * @property {boolean} loading 加载状态，默认值：false。
+ * @property {boolean} clearable 是否显示清空按钮，默认值：false。
+ * @property {boolean} multiline 是否多行输入框，默认值：false。
+ * @event {() => void} click 点击输入框时触发，只读和禁用不触发
+ * @event {(value: string) => void} update 输入框值改变时触发
+ * @event {(value: string) => void} change 输入框值改变时触发
+ * @event {() => void} clear 点击清除按钮时触发
+ */
 export default  _defineComponent({
   components: {
     SarInput,