sard-uniapp 1.19.2 → 1.19.4

package/components/dropdown/dropdown.vue

@@ -13,6 +13,17 @@ import {
   dropdownContextSymbol,
   defaultDropdownProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {'down' | 'up'} direction 菜单弹出方向，默认值：'down'。
+ * @property {boolean} disabled 是否禁用，默认值：false。
+ * @property {boolean} awayClosable 是否在点击外部区域后自动隐藏，默认值：true。
+ * @property {boolean} overlayClosable 是否在点击遮罩后自动隐藏，默认值：true。
+ * @property {number} duration 显隐动画时长，单位 ms，默认值：300。
+ * @property {boolean} togglable 是否可取消选中的选项，默认值：false。
+ * @property {any} valueOnClear 取消选项时设置的值，默认值：undefined。
+ */
 export default  _defineComponent({
   ...{
     options: {
@@ -28,7 +39,9 @@ export default  _defineComponent({
     disabled: { type: Boolean, required: false },
     awayClosable: { type: Boolean, required: false },
     overlayClosable: { type: Boolean, required: false },
-    duration: { type: Number, required: false }
+    duration: { type: Number, required: false },
+    togglable: { type: Boolean, required: false },
+    valueOnClear: { type: Function, required: false }
   }, defaultDropdownProps),
   setup(__props, { expose: __expose }) {
     __expose();
@@ -59,6 +72,8 @@ export default  _defineComponent({
         awayClosable: toRef(() => props.awayClosable),
         overlayClosable: toRef(() => props.overlayClosable),
         duration: toRef(() => props.duration),
+        togglable: toRef(() => props.togglable),
+        valueOnClear: toRef(() => props.valueOnClear),
         hideOthers,
         register,
         unregister

package/components/dropdown-item/dropdown-item.vue

@@ -102,9 +102,38 @@ import SarIcon from "../icon/icon.vue";
 import SarOverlay from "../overlay/overlay.vue";
 import {
   dropdownContextSymbol,
-  defaultDropdownItemProps
+  defaultDropdownItemProps,
+  defaultValueOnClear
 } from "../dropdown/common";
 import { useTransition, useZIndex } from "../../use";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} title 标题，用于自定义菜单内容，默认值：-。
+ * @property {string} label 标签说明，默认值：-。
+ * @property {DropdownOption[]} options 菜单选项，默认值：[]。
+ * @property {'down' | 'up'} direction 菜单弹出方向，默认值：'down'。
+ * @property {boolean} disabled 是否禁用，默认值：false。
+ * @property {any} modelValue 当前选择的菜单项的值，默认值：-。
+ * @property {boolean} visible 弹出框是否可见，默认值：-。
+ * @property {string} separator 标签后面分隔符，默认值：-。
+ * @property {string} placeholder 占位符，默认值：-。
+ * @property {boolean} togglable 是否可取消选中的选项，默认值：false。
+ * @property {any} valueOnClear 取消选项时设置的值，默认值：undefined。
+ * @property {() => any} beforeOpen 打开前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止打开，默认值：-。
+ * @property {DropdownBeforeClose} beforeClose 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭，默认值：-。
+ * @event {(visible: boolean) => void} update 弹出框显隐时触发
+ * @event {(value: any) => void} change 选中菜单选项时触发
+ * @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: {
     SarList,
@@ -130,6 +159,8 @@ export default  _defineComponent({
     visible: { type: Boolean, required: false },
     separator: { type: String, required: false },
     placeholder: { type: String, required: false },
+    togglable: { type: Boolean, required: false },
+    valueOnClear: { type: Function, required: false },
     beforeClose: { type: Function, required: false },
     beforeOpen: { type: Function, required: false }
   }, defaultDropdownItemProps),
@@ -148,6 +179,10 @@ export default  _defineComponent({
     const itemId = uniqid();
     const instance = getCurrentInstance();
     const innerValue = ref(props.modelValue);
+    const mergedTogglable = computed(() => props.togglable || context.togglable);
+    const mergedValueOnClear = computed(
+      () => props.valueOnClear || context.valueOnClear || defaultValueOnClear
+    );
     watch(
       () => props.modelValue,
       () => {
@@ -257,10 +292,22 @@ export default  _defineComponent({
       }
     };
     const onOptionClick = (option) => {
+      let changed = false;
       if (option.value !== innerValue.value) {
         innerValue.value = option.value;
-        emit("update:model-value", option.value);
-        emit("change", option.value);
+        changed = true;
+      } else {
+        if (mergedTogglable.value) {
+          const value = mergedValueOnClear.value();
+          if (value !== innerValue.value) {
+            innerValue.value = value;
+          }
+          changed = true;
+        }
+      }
+      if (changed) {
+        emit("update:model-value", innerValue.value);
+        emit("change", innerValue.value);
       }
       perhapsClose("option");
     };
@@ -346,7 +393,7 @@ export default  _defineComponent({
     const dropdownItemStyle = computed(() => {
       return stringifyStyle(props.rootStyle);
     });
-    const __returned__ = { props, emit, bem, context, itemId, instance, innerValue, innerVisible, wholeVisible, popupVisible, popupInset, awayInset, setPosition, setInnerVisible, get isClosing() {
+    const __returned__ = { props, emit, bem, context, itemId, instance, innerValue, mergedTogglable, mergedValueOnClear, innerVisible, wholeVisible, popupVisible, popupInset, awayInset, setPosition, setInnerVisible, get isClosing() {
       return isClosing;
     }, set isClosing(v) {
       isClosing = v;

package/components/empty/README.md

@@ -0,0 +1,71 @@
+---
+nav: 组件
+title: Empty
+subtitle: 空状态
+group: 数据展示
+---
+
+## 介绍
+
+空状态时的占位提示。
+
+## 引入
+
+```ts
+import { Empty } from 'sard'
+```
+
+## 代码演示
+
+### 基础使用
+
+@code('${DEMO_PATH}/empty/demo/Basic.vue')
+
+### 自定义描述信息
+
+@code('${DEMO_PATH}/empty/demo/Description.vue')
+
+### 自定义图标大小
+
+通过配置 `iconSize` 属性可以修改图标大小。
+
+@code('${DEMO_PATH}/empty/demo/Size.vue')
+
+### 自定义图标
+
+通过配置 `icon` 属性可以修改图标。
+
+@code('${DEMO_PATH}/empty/demo/Icon.vue')
+
+### 额外内容
+
+额外内容会显示在底部。
+
+@code('${DEMO_PATH}/empty/demo/Extra.vue')
+
+## API
+
+### EmptyProps
+
+| 属性        | 描述           | 类型       | 默认值     |
+| ----------- | -------------- | ---------- | ---------- |
+| root-class  | 组件根元素类名 | string     | -          |
+| root-style  | 组件根元素样式 | StyleValue | -          |
+| description | 描述信息       | string     | '暂无数据' |
+| icon        | 自定义图标     | string     | -          |
+| icon-family | 图标字体       | string     | -          |
+| icon-size   | 图标大小       | string     | -          |
+
+### EmptySlots
+
+| 插槽        | 描述           | 属性 |
+| ----------- | -------------- | ---- |
+| default     | 自定义额外内容 | -    |
+| icon        | 自定义图标内容 | -    |
+| description | 自定义描述内容 | -    |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/empty/empty.vue

@@ -23,6 +23,14 @@ import { classNames, stringifyStyle, createBem } from "../../utils";
 import SarIcon from "../icon/icon.vue";
 import { useTranslate } from "../locale";
 import { defaultEmptyProps } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} description 描述信息，默认值：'暂无数据'。
+ * @property {string} icon 自定义图标，默认值：-。
+ * @property {string} iconFamily 图标字体，默认值：-。
+ * @property {string} iconSize 图标大小，默认值：-。
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/fab/README.md

@@ -0,0 +1,111 @@
+---
+nav: 组件
+title: Fab
+subtitle: 悬浮按钮
+group: 反馈组件
+version: 1.5+
+---
+
+## 介绍
+
+悬浮按钮，点击可展开扩展按钮。
+
+## 引入
+
+```ts
+import Fab from 'sard-uniapp/components/fab/fab.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+设置 `item-list` 属性配置扩展按钮，监听 `select` 事件来知晓用户点击了哪个按钮。
+
+@code('${DEMO_PATH}/fab/demo/Basic.vue')
+
+### 修改背景色
+
+设置 `background` 属性以及按钮项的 `background` 自定义背景色。
+
+@code('${DEMO_PATH}/fab/demo/Color.vue')
+
+### 隐藏按钮名称
+
+默认会显示按钮项的 `name` 属性，可以设置 `hide-name` 属性进行隐藏。
+
+@code('${DEMO_PATH}/fab/demo/HideName.vue')
+
+### 左上角显示
+
+按钮默认显示在右下角，设置 `left` 或 `top` 可以让其显示在左上角。
+
+@code('${DEMO_PATH}/fab/demo/TopLeft.vue')
+
+### 右上角显示
+
+按钮默认显示在右下角，设置 `top` 会将其从底部显示在顶部。
+
+@code('${DEMO_PATH}/fab/demo/TopRight.vue')
+
+### 左下角显示
+
+按钮默认显示在右下角，设置 `left` 会将其从右边显示在左边。
+
+@code('${DEMO_PATH}/fab/demo/BottomLeft.vue')
+
+### 无扩展按钮显示
+
+当不设置 `item-list` 属性，或其数组长度为 0，则不显示扩展按钮。
+
+@code('${DEMO_PATH}/fab/demo/NonItemList.vue')
+
+## API
+
+### FabProps
+
+| 属性             | 描述                                         | 类型       | 默认值 |
+| ---------------- | -------------------------------------------- | ---------- | ------ |
+| root-class       | 组件根元素类名                               | string     | -      |
+| root-style       | 组件根元素样式                               | StyleValue | -      |
+| top              | 设置距离窗口顶部的距离，优先级比 `bottom` 高 | string     | -      |
+| right            | 设置距离窗口右边的距离                       | string     | -      |
+| bottom           | 设置距离窗口底部的距离                       | string     | -      |
+| left             | 设置距离窗口左边的距离，优先级比 `right` 高  | string     | -      |
+| color            | 设置按钮图标的颜色                           | string     | -      |
+| background       | 设置按钮的背景色                             | string     | -      |
+| icon             | 设置入口按钮的图标                           | string     | -      |
+| icon-family      | 设置入口按钮的图标族                         | string     | -      |
+| item-list        | 设置扩展按钮                                 | FabItem[]  | []     |
+| hide-name        | 是否隐藏按钮名称                             | boolean    | false  |
+| overlay-closable | 点击遮罩是否隐藏扩展按钮                     | boolean    | false  |
+| duration         | 扩展按钮显隐动画时长，单位 ms                | number     | 150    |
+
+### FabSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### FabEmits
+
+| 事件   | 描述               | 类型                                   |
+| ------ | ------------------ | -------------------------------------- |
+| click  | 点击入口按钮时触发 | (event: any) => void                   |
+| select | 点击扩展按钮时触发 | (item: FabItem, index: number) => void |
+
+### FabItem
+
+| 属性        | 描述         | 类型   | 默认值 |
+| ----------- | ------------ | ------ | ------ |
+| name        | 按钮名称     | string | -      |
+| color       | 按钮图标颜色 | string | -      |
+| background  | 按钮背景色   | string | -      |
+| icon        | 按钮图标     | string | -      |
+| icon-family | 按钮图标族   | string | -      |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/fab/fab.vue

@@ -49,6 +49,24 @@ import {
 import { useTransition, useZIndex } from "../../use";
 import SarIcon from "../icon/icon.vue";
 import SarOverlay from "../overlay/overlay.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} top 设置距离窗口顶部的距离，优先级比 `bottom` 高，默认值：-。
+ * @property {string} right 设置距离窗口右边的距离，默认值：-。
+ * @property {string} bottom 设置距离窗口底部的距离，默认值：-。
+ * @property {string} left 设置距离窗口左边的距离，优先级比 `right` 高，默认值：-。
+ * @property {string} color 设置按钮图标的颜色，默认值：-。
+ * @property {string} background 设置按钮的背景色，默认值：-。
+ * @property {string} icon 设置入口按钮的图标，默认值：-。
+ * @property {string} iconFamily 设置入口按钮的图标族，默认值：-。
+ * @property {FabItem[]} itemList 设置扩展按钮，默认值：[]。
+ * @property {boolean} hideName 是否隐藏按钮名称，默认值：false。
+ * @property {boolean} overlayClosable 点击遮罩是否隐藏扩展按钮，默认值：false。
+ * @property {number} duration 扩展按钮显隐动画时长，单位 ms，默认值：150。
+ * @event {(event: any) => void} click 点击入口按钮时触发
+ * @event {(item: FabItem, index: number) => void} select 点击扩展按钮时触发
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/floating-bubble/README.md

@@ -0,0 +1,70 @@
+---
+nav: 组件
+title: FloatingBubble
+subtitle: 浮动气泡
+group: 反馈组件
+version: 1.5+
+---
+
+## 介绍
+
+悬浮在窗口边缘的可点击的气泡。
+
+## 引入
+
+```ts
+import FloatingBubble from 'sard-uniapp/components/floating-bubble/floating-bubble.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+浮动气泡默认展示在右下角，并允许在 y 轴方向上下拖拽。
+
+@code('${DEMO_PATH}/floating-bubble/demo/Basic.vue')
+
+### 自由拖拽和磁吸
+
+`axis` 属性设置允许在 x 或 y 轴方向拖拽，`magnet` 属性设置松开手指后吸附到指定轴方向的最近一边。
+
+@code('${DEMO_PATH}/floating-bubble/demo/Magnet.vue')
+
+### 双向绑定
+
+使用 `v-model:offset` 控制气泡的位置。
+
+@code('${DEMO_PATH}/floating-bubble/demo/Offset.vue')
+
+## API
+
+### FloatingBubbleProps
+
+| 属性             | 描述                                    | 类型                           | 默认值 |
+| ---------------- | --------------------------------------- | ------------------------------ | ------ |
+| root-class       | 组件根元素类名                          | string                         | -      |
+| root-style       | 组件根元素样式                          | StyleValue                     | -      |
+| axis             | 允许拖拽的方向轴                        | 'x' \| 'y' \| 'both' \| 'none' | 'y'    |
+| magnet           | 吸附到指定轴最近的一边                  | 'x' \| 'y'                     | -      |
+| gap-x            | 气泡与窗口左右两边的最小间距，单位为 px | number                         | 24     |
+| gap-y            | 气泡与窗口上下两边的最小间距，单位为 px | number                         | 24     |
+| offset (v-model) | 控制气泡的位置                          | { x: number; y: number }       | -      |
+
+### FloatingBubbleSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### FloatingBubbleEmits
+
+| 事件          | 描述                         | 类型                                       |
+| ------------- | ---------------------------- | ------------------------------------------ |
+| click         | 点击时触发                   | (event: any) => void                       |
+| update:offset | 因用户拖拽导致位置改变时触发 | (offset: { x: number; y: number }) => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/floating-bubble/floating-bubble.vue

@@ -29,6 +29,17 @@ import {
   defaultFloatingBubbleProps
 } from "./common";
 import { useMouseDown, useTimeout } from "../../use";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {'x' | 'y' | 'both' | 'none'} axis 允许拖拽的方向轴，默认值：'y'。
+ * @property {'x' | 'y'} magnet 吸附到指定轴最近的一边，默认值：-。
+ * @property {number} gapX 气泡与窗口左右两边的最小间距，单位为 px，默认值：24。
+ * @property {number} gapY 气泡与窗口上下两边的最小间距，单位为 px，默认值：24。
+ * @property {{ x: number; y: number }} offset 控制气泡的位置，默认值：-。
+ * @event {(event: any) => void} click 点击时触发
+ * @event {(offset: { x: number; y: number }) => void} update 因用户拖拽导致位置改变时触发
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/floating-panel/README.md

@@ -0,0 +1,78 @@
+---
+nav: 组件
+title: FloatingPanel
+subtitle: 浮动面板
+group: 反馈组件
+version: 1.13+
+---
+
+## 介绍
+
+浮动在页面底部的面板，可以上下拖动来浏览内容，从而在不离开当前视图的情况下访问更多信息，常用于地图导航。
+
+## 引入
+
+```ts
+import FloatingPanel from 'sard-uniapp/components/floating-panel/floating-panel.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+`FloatingPanel` 的默认高度为 `100px`，用户可以拖动来展开面板，使高度达到 60% 的可用窗口高度。
+
+@code('${DEMO_PATH}/floating-panel/demo/Basic.vue')
+
+### 自定义锚点
+
+你可以通过 `anchors` 属性来设置 `FloatingPanel` 的锚点位置，并通过 `v-model:height` 来控制当前面板的显示高度。
+
+比如，使面板的高度在 100px、40% 可用窗口高度和 70% 可用窗口高度三个位置停靠：
+
+@code('${DEMO_PATH}/floating-panel/demo/Anchors.vue')
+
+### 仅头部拖拽
+
+默认情况下，`FloatingPanel` 的头部区域和内容区域都可以被拖拽，你可以通过 `content-draggable` 属性来禁用内容区域的拖拽。
+
+@warning
+
+支付宝端内容区域始终不能拖拽，无论有没有设置 `content-draggable` 属性。
+
+@endwarning
+
+@code('${DEMO_PATH}/floating-panel/demo/ContentDraggable.vue')
+
+## API
+
+### FloatingPanelProps
+
+| 属性                   | 描述                    | 类型       | 默认值                                        |
+| ---------------------- | ----------------------- | ---------- | --------------------------------------------- |
+| root-class             | 组件根元素类名          | string     | -                                             |
+| root-style             | 组件根元素样式          | StyleValue | -                                             |
+| height                 | 当前面板的显示高度      | number     | 0                                             |
+| anchors                | 设置自定义锚点, 单位 px | number[]   | [100, uni.getWindowInfo().windowHeight * 0.6] |
+| duration               | 动画时长，单位毫秒      | number     | 300                                           |
+| content-draggable      | 允许拖拽内容容器        | boolean    | true                                          |
+| safe-area-inset-bottom | 是否开启底部安全区适配  | boolean    | true                                          |
+
+### FloatingPanelSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### FloatingPanelEmits
+
+| 事件          | 描述                             | 类型            |
+| ------------- | -------------------------------- | --------------- |
+| update:height | 面板显示高度改变时触发           | {value: number} |
+| height-change | 面板显示高度改变且结束拖动后触发 | {value: number} |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/floating-panel/floating-panel.vue

@@ -40,6 +40,17 @@ import {
 } from "./common";
 import { useMouseDown } from "../../use";
 import { useInitialVelocity } from "../../use/useInitialVelocity";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {number} height 当前面板的显示高度，默认值：0。
+ * @property {number[]} anchors 设置自定义锚点, 单位 px，默认值：[100, uni.getWindowInfo().windowHeight * 0.6]。
+ * @property {number} duration 动画时长，单位毫秒，默认值：300。
+ * @property {boolean} contentDraggable 允许拖拽内容容器，默认值：true。
+ * @property {boolean} safeAreaInsetBottom 是否开启底部安全区适配，默认值：true。
+ * @event {{value: number}} update 面板显示高度改变时触发
+ * @event {{value: number}} height-change 面板显示高度改变且结束拖动后触发
+ */
 export default  _defineComponent({
   ...{
     options: {