sard-uniapp 1.19.1 → 1.19.3

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [1.19.3](https://github.com/sutras/sard-uniapp/compare/v1.19.2...v1.19.3) (2025-06-17)
+
+
+### Features
+
+* dropdown 新增 togglable 属性 ([e46291e](https://github.com/sutras/sard-uniapp/commit/e46291e99307ad977801153547b593ef97a56ee8))
+* icon 添加 separate 属性 ([b20d069](https://github.com/sutras/sard-uniapp/commit/b20d0697ec4ef16fabf50e4bae3eab6908d6a572))
+
+
+
+## [1.19.2](https://github.com/sutras/sard-uniapp/compare/v1.19.1...v1.19.2) (2025-06-14)
+
+
+### Bug Fixes
+
+* picker 值为空时滚到第一个位置 ([f033ccc](https://github.com/sutras/sard-uniapp/commit/f033ccc713ec1260d1cb761769ab31ccbc39d808))
+* 修复 picker-popout 首次选择不能获取选项列表问题 ([50cebc7](https://github.com/sutras/sard-uniapp/commit/50cebc75c036c8b0bf7ed32cb46338d68716385d))
+
+
+### Features
+
+* *-input 系列组件新增valueOnClear属性 ([42275cd](https://github.com/sutras/sard-uniapp/commit/42275cd5beec09d7d5fe669c560ae6ad7dfc1b13))
+* calendar-popout组件新增title和title-prepend插槽 ([f6f8404](https://github.com/sutras/sard-uniapp/commit/f6f84042f2924f6547bb6273078ada5e08039fd5))
+* upload 组件新增 beforeChoose 属性 ([22e3137](https://github.com/sutras/sard-uniapp/commit/22e3137c72e3a16f298dcabbffd2db43268f8a74))
+* 增加 tag 组件的 mark 属性，支持 'left' 和 'right' 值以控制标记方向 ([77f9fb7](https://github.com/sutras/sard-uniapp/commit/77f9fb724040d99f7aa2612ccd03c8c6f175de52))
+* 新增css变量 ([f1b081e](https://github.com/sutras/sard-uniapp/commit/f1b081ef65c66794dec1d7b4bc6d769676cbdf7f))
+* 新增图标属性和长按菜单功能 ([62c0d7f](https://github.com/sutras/sard-uniapp/commit/62c0d7f9d4e085f91c0c745f85b02d90d0cd246e))
+
+
+
 ## [1.19.1](https://github.com/sutras/sard-uniapp/compare/v1.19.0...v1.19.1) (2025-06-11)
 
 

package/components/accordion/README.md

@@ -0,0 +1,91 @@
+---
+nav: 组件
+title: Accordion
+subtitle: 手风琴
+group:
+  title: 数据展示
+  order: 3
+---
+
+## 介绍
+
+通过折叠收纳内容，允许同时展开一个或多个。
+
+## 引入
+
+```ts
+import Accordion from 'sard-uniapp/components/accordion/accordion.vue'
+import AccordionItem from 'sard-uniapp/components/accordion-item/accordion-item.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+为手风琴每一个面板添加一个 `name` 属性，使用 `v-model` 绑定展开的面板。
+
+@code('${DEMO_PATH}/accordion/demo/Basic.vue')
+
+### 展开多个
+
+设置 `multiple` 属性可以同时展开多个面板，此时 `v-model` 要绑定一个数组。
+
+@code('${DEMO_PATH}/accordion/demo/Multiple.vue')
+
+### 禁用
+
+使用 `disabled` 属性可以禁用指定单个面板。
+
+@code('${DEMO_PATH}/accordion/demo/Disabled.vue')
+
+## API
+
+### AccordionProps
+
+| 属性        | 描述                   | 类型                                     | 默认值 |
+| ----------- | ---------------------- | ---------------------------------------- | ------ |
+| root-class  | 组件根元素类名         | string                                   | -      |
+| root-style  | 组件根元素样式         | StyleValue                               | -      |
+| model-value | 当前展开面板的 `name`  | string \| number \| (string \| number)[] | -      |
+| multiple    | 是否可同时展开多个面板 | boolean                                  | false  |
+
+### AccordionSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### AccordionEmits
+
+| 事件               | 描述           | 类型                                                      |
+| ------------------ | -------------- | --------------------------------------------------------- |
+| update:model-value | 切换面板时触发 | (value: string \| number \| (string \| number)[]) => void |
+
+### AccordionItemProps
+
+| 属性       | 描述           | 类型             | 默认值 |
+| ---------- | -------------- | ---------------- | ------ |
+| root-class | 组件根元素类名 | string           | -      |
+| root-style | 组件根元素样式 | StyleValue       | -      |
+| title      | 面板标题       | string           | -      |
+| value      | 面板的值       | string           | -      |
+| name       | 面板的唯一标识 | string \| number | -      |
+| disabled   | 禁用面板       | boolean          | false  |
+
+### AccordionItemSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### AccordionItemEmits
+
+| 事件  | 描述               | 类型                 |
+| ----- | ------------------ | -------------------- |
+| click | 点击面板头部时触发 | (event: any) => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/accordion/accordion.vue

@@ -11,6 +11,13 @@ import { classNames, stringifyStyle, createBem } from "../../utils";
 import {
   accoridonContextSymbol
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string | number | (string | number)[]} modelValue 当前展开面板的 `name`，默认值：-。
+ * @property {boolean} multiple 是否可同时展开多个面板，默认值：false。
+ * @event {(value: string | number | (string | number)[]) => void} update 切换面板时触发
+ */
 export default  _defineComponent({
   ...{
     options: {

package/components/accordion-item/accordion-item.vue

@@ -24,6 +24,15 @@ import {
 } from "../accordion/common";
 import SarCollapse from "../collapse/collapse.vue";
 import SarIcon from "../icon/icon.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} title 面板标题，默认值：-。
+ * @property {string} value 面板的值，默认值：-。
+ * @property {string | number} name 面板的唯一标识，默认值：-。
+ * @property {boolean} disabled 禁用面板，默认值：false。
+ * @event {(event: any) => void} click 点击面板头部时触发
+ */
 export default  _defineComponent({
   components: {
     SarCollapse,

package/components/action-sheet/README.md

@@ -0,0 +1,85 @@
+---
+nav: 组件
+title: ActionSheet
+subtitle: 动作面板
+group:
+  title: 反馈组件
+  order: 5
+---
+
+## 介绍
+
+从底部向上弹出动作菜单。
+
+## 引入
+
+```ts
+import ActionSheet from 'sard-uniapp/components/action-sheet/action-sheet.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+使用 `v-model:visible` 属性控制显隐，使用 `itemList` 属性配置动作项。
+
+@code('${DEMO_PATH}/action-sheet/demo/Basic.vue')
+
+### 取消按钮
+
+使用 `cancel` 属性展示取消按钮。
+
+@code('${DEMO_PATH}/action-sheet/demo/Cancel.vue')
+
+### 描述信息
+
+使用 `description` 属性对整个动作面板做一个解释说明。使用动作项的 `description` 属性对某个动作做一个解释说明。
+
+@code('${DEMO_PATH}/action-sheet/demo/Description.vue')
+
+### 动作状态
+
+每个动作项都可以配置 `color`、`disabled`、`loading` 等属性来展示当前的状态。
+
+@code('${DEMO_PATH}/action-sheet/demo/Status.vue')
+
+## API
+
+### ActionSheetProps
+
+| 属性             | 描述                                                                 | 类型                                           | 默认值 |
+| ---------------- | -------------------------------------------------------------------- | ---------------------------------------------- | ------ |
+| root-class       | 组件根元素类名                                                       | string                                         | -      |
+| root-style       | 组件根元素样式                                                       | StyleValue                                     | -      |
+| description      | 动作面板描述说明                                                     | string                                         | -      |
+| item-list        | 面板项列表                                                           | ActionSheetItem[]                              | []     |
+| cancel           | 取消按钮文字                                                         | string                                         | -      |
+| visible          | 是否显示动作面板                                                     | boolean                                        | false  |
+| overlay-closable | 点击遮罩后是否关闭                                                   | boolean                                        | true   |
+| before-close     | 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭 | (type: 'close' \| 'cancel' \| 'select') => any | -      |
+| duration         | 显隐动画时长，单位 ms                                                | number                                         | 300    |
+
+### ActionSheetItem
+
+| 属性        | 描述           | 类型    | 默认值 |
+| ----------- | -------------- | ------- | ------ |
+| name        | 动作名称       | string  | -      |
+| description | 动作的描述说明 | string  | -      |
+| color       | 字体颜色       | string  | -      |
+| disabled    | 禁用状态       | boolean | false  |
+| loading     | 加载状态       | boolean | false  |
+
+### ActionSheetEmits
+
+| 事件           | 描述               | 类型                                           |
+| -------------- | ------------------ | ---------------------------------------------- |
+| update:visible | 动作面板显隐时触发 | (visible: boolean) => void                     |
+| close          | 点击遮罩时触发     | () => void                                     |
+| cancel         | 点击取消按钮时触发 | () => void                                     |
+| select         | 点击动作按钮时触发 | (item: ActionSheetItem, index: number) => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/action-sheet/action-sheet.vue

@@ -62,6 +62,21 @@ import SarLoading from "../loading/loading.vue";
 import {
   defaultActionSheetProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {string} description 动作面板描述说明，默认值：-。
+ * @property {ActionSheetItem[]} itemList 面板项列表，默认值：[]。
+ * @property {string} cancel 取消按钮文字，默认值：-。
+ * @property {boolean} visible 是否显示动作面板，默认值：false。
+ * @property {boolean} overlayClosable 点击遮罩后是否关闭，默认值：true。
+ * @property {(type: 'close' | 'cancel' | 'select') => any} beforeClose 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭，默认值：-。
+ * @property {number} duration 显隐动画时长，单位 ms，默认值：300。
+ * @event {(visible: boolean) => void} update 动作面板显隐时触发
+ * @event {() => void} close 点击遮罩时触发
+ * @event {() => void} cancel 点击取消按钮时触发
+ * @event {(item: ActionSheetItem, index: number) => void} select 点击动作按钮时触发
+ */
 export default  _defineComponent({
   components: {
     SarPopup,

package/components/action-sheet/variables.scss

@@ -23,7 +23,7 @@ page,
   --sar-action-sheet-item-description-color: var(--sar-tertiary-color);
 
   --sar-action-sheet-loading-size: 40rpx;
-  --sar-action-sheet-loading-color: var(--sar-quaternary-color);
+  --sar-action-sheet-loading-color: var(--sar-fourth-color);
 
   --sar-action-sheet-cancel-min-height: 96rpx;
   --sar-action-sheet-cancel-padding: 16rpx 32rpx;

package/components/alert/README.md

@@ -0,0 +1,74 @@
+---
+nav: 组件
+title: Alert
+subtitle: 警告提示
+group: 反馈组件
+version: 1.3+
+---
+
+## 介绍
+
+突出显示要重点提示用户的信息。警告提示会一直显示，除非用户手动关闭。
+
+## 引入
+
+```ts
+import Alert from 'sard-uniapp/components/alert/alert.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+@code('${DEMO_PATH}/alert/demo/Basic.vue')
+
+### 类型
+
+使用 `type` 属性设置不同的类型。
+
+@code('${DEMO_PATH}/alert/demo/Type.vue')
+
+### 显示图标
+
+设置 `show-icon` 属性显示图标。
+
+@code('${DEMO_PATH}/alert/demo/ShowIcon.vue')
+
+### 可关闭的
+
+设置 `closable` 属性显示关闭按钮。
+
+@code('${DEMO_PATH}/alert/demo/Closable.vue')
+
+## API
+
+### AlertProps
+
+| 属性       | 描述             | 类型                                            | 默认值    |
+| ---------- | ---------------- | ----------------------------------------------- | --------- |
+| root-class | 组件根元素类名   | string                                          | -         |
+| root-style | 组件根元素样式   | StyleValue                                      | -         |
+| type       | 警告提示样式类型 | 'primary' \| 'success' \| 'warning' \| 'danger' | 'primary' |
+| show-icon  | 是否显示图标     | StyleValue                                      | -         |
+| closable   | 是否显示关闭按钮 | boolean                                         | false     |
+| color      | 字体颜色         | string                                          | -         |
+| background | 背景颜色         | string                                          | -         |
+
+### AlertSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+| icon    | 自定义图标     | -    |
+
+### AlertEmits
+
+| 事件  | 描述             | 类型       |
+| ----- | ---------------- | ---------- |
+| close | 点击关闭按钮触发 | () => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/alert/alert.vue

@@ -21,6 +21,16 @@ import {
   mapTypeIcon
 } from "./common";
 import SarIcon from "../icon/icon.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {'primary' | 'success' | 'warning' | 'danger'} type 警告提示样式类型，默认值：'primary'。
+ * @property {StyleValue} showIcon 是否显示图标，默认值：-。
+ * @property {boolean} closable 是否显示关闭按钮，默认值：false。
+ * @property {string} color 字体颜色，默认值：-。
+ * @property {string} background 背景颜色，默认值：-。
+ * @event {() => void} close 点击关闭按钮触发
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/avatar/README.md

@@ -0,0 +1,86 @@
+---
+nav: 组件
+title: Avatar
+subtitle: 头像
+group: 数据展示
+---
+
+## 介绍
+
+用图片、图标或字符等来展示头像、群、库等事物信息。
+
+## 引入
+
+```ts
+import Avatar from 'sard-uniapp/components/avatar/avatar.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+默认展示一个人头图标。
+
+@code('${DEMO_PATH}/avatar/demo/Basic.vue')
+
+### 形状
+
+设置 `shape="square" ` 将其改为带圆角的方形。
+
+@code('${DEMO_PATH}/avatar/demo/Shape.vue')
+
+### 尺寸
+
+`size` 设置头像大小，`iconSize` 设置图标大小。
+
+@code('${DEMO_PATH}/avatar/demo/Size.vue')
+
+### 自定义样式
+
+`background` 设置头像背景色，`color` 设置图标颜色。
+
+@code('${DEMO_PATH}/avatar/demo/Style.vue')
+
+### 图片类型
+
+设置 `src` 图片路径将展示一个完全覆盖框框的图片。
+
+@code('${DEMO_PATH}/avatar/demo/Picture.vue')
+
+### 自定义内容
+
+默认插槽配置的内容会代替默认的内容。
+
+@code('${DEMO_PATH}/avatar/demo/Children.vue')
+
+### 额外内容
+
+`extra` 属性可以展示例如徽标等组件。要使徽标固定在圆角形状头像右上角边上可以使用 `14.6447%` 的固定值。
+
+@code('${DEMO_PATH}/avatar/demo/Extra.vue')
+
+## API
+
+### AvatarProps
+
+| 属性       | 描述                   | 类型                 | 默认值   |
+| ---------- | ---------------------- | -------------------- | -------- |
+| root-class | 组件根元素类名         | string               | -        |
+| root-style | 组件根元素样式         | StyleValue           | -        |
+| shape      | 头像形状               | 'circle' \| 'square' | 'circle' |
+| size       | 头像尺寸               | string               | -        |
+| icon-size  | 图标尺寸               | string               | -        |
+| src        | 图片类型头像的图片地址 | string               | -        |
+
+### AvatarSlots
+
+| 插槽    | 描述                     | 属性 |
+| ------- | ------------------------ | ---- |
+| default | 自定义默认内容           | -    |
+| extra   | 额外内容，常用于展示徽标 | -    |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/avatar/avatar.vue

@@ -27,6 +27,14 @@ import SarIcon from "../icon/icon.vue";
 import {
   defaultAvatarProps
 } from "./common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {'circle' | 'square'} shape 头像形状，默认值：'circle'。
+ * @property {string} size 头像尺寸，默认值：-。
+ * @property {string} iconSize 图标尺寸，默认值：-。
+ * @property {string} src 图片类型头像的图片地址，默认值：-。
+ */
 export default  _defineComponent({
   components: {
     SarIcon,

package/components/back-top/README.md

@@ -0,0 +1,134 @@
+---
+nav: 组件
+title: BackTop
+subtitle: 回到顶部
+group:
+  title: 导航组件
+  order: 4
+version: 1.6+
+---
+
+## 介绍
+
+返回页面顶部的操作按钮。
+
+## 引入
+
+```ts
+import BackTop from 'sard-uniapp/components/back-top/back-top.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+返回页面顶部时，`BackTop` 组件需要配合 `usePageBackTop` 组合式函数使用。
+
+`BackTop` 组件需要绑定 `usePageBackTop` 返回的 `scrollTop` 属性值和 `onClick` 回调。
+
+另外，为了让 `uniapp` 编译器能够初始化 `onPageScroll` 页面钩子，需要显式在页面组件调用 `onPageScroll` 组合式函数。
+
+@code('${DEMO_PATH}/back-top/demo/Basic.vue')
+
+### scroll-view 组件滚动
+
+返回 `scroll-view` 顶部时，`BackTop` 组件需要配合 `useScrollViewBackTop` 组合式函数使用。
+
+`BackTop` 组件需要绑定 `useScrollViewBackTop` 返回的 `scrollTop` 属性值和 `onClick` 回调。
+
+`scroll-view` 组件需要绑定 `useScrollViewBackTop` 返回的 `scrollTop` 属性值和 `onScroll` 回调。
+
+@code('${DEMO_PATH}/back-top/demo/ScrollView.vue')
+
+### 按钮位置
+
+通过设置 `right` 和 `bottom` 属性可以自定义按钮距离右下角的距离。
+
+@code('${DEMO_PATH}/back-top/demo/Position.vue')
+
+### 滚动时长
+
+`usePageBackTop` 组合式函数可以接收一个数值类型参数，表示滚动到页面顶部的动画时长。
+
+`scroll-view` 默认没有滚动动画，通过设置 `scroll-with-animation` 属性可以添加滚动动画。
+
+@code('${DEMO_PATH}/back-top/demo/Duration.vue')
+
+### 可见时的高度
+
+默认情况下，当页面或 `scroll-view` 滚动到一定距离时，按钮才会显示。
+
+可以设置 `visible-height` 为 0 让按钮一直显示。
+
+@code('${DEMO_PATH}/back-top/demo/VisibleHeight.vue')
+
+### 自定义按钮内容
+
+使用默认插槽自定义组件展示的内容。
+
+@code('${DEMO_PATH}/back-top/demo/CustomContent.vue')
+
+## API
+
+### BackTopProps
+
+| 属性           | 描述                                                  | 类型       | 默认值 |
+| -------------- | ----------------------------------------------------- | ---------- | ------ |
+| root-class     | 组件根元素类名                                        | string     | -      |
+| root-style     | 组件根元素样式                                        | StyleValue | -      |
+| scroll-top     | 当前页面或 scroll-view 滚动的高度                     | number     | 0      |
+| visible-height | 回到顶部按钮显示时的页面或 scroll-view 滚动的最小高度 | number     | 200    |
+| right          | 回到顶部按钮距离右边的距离                            | string     | -      |
+| bottom         | 回到顶部按钮距离底部的距离                            | string     | -      |
+
+### BackTopSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### BackTopEmits
+
+| 事件  | 描述       | 类型                 |
+| ----- | ---------- | -------------------- |
+| click | 点击时触发 | (event: any) => void |
+
+### usePageBackTop
+
+```ts
+function usePageBackTop(duration?: number): {
+  scrollTop: Ref<number>
+  onClick: () => void
+}
+```
+
+| 参数     | 描述                  | 类型   | 默认值 |
+| -------- | --------------------- | ------ | ------ |
+| duration | 滚动动画时长，单位 ms | number | 300    |
+
+| 返回对象的属性 | 描述                                            | 类型         |
+| -------------- | ----------------------------------------------- | ------------ |
+| scrollTop      | 需要绑定到 `BackTop` 组件 `scroll-top` 属性的值 | Ref\<number> |
+| onClick        | 需要绑定到 `BackTop` 组件 `click` 事件的回调    | () => void   |
+
+### useScrollViewBackTop
+
+```ts
+function useScrollViewBackTop(): {
+  scrollTop: Ref<number>
+  onScroll: (event: any) => void
+  onClick: () => void
+}
+```
+
+| 返回对象的属性 | 描述                                                            | 类型                 |
+| -------------- | --------------------------------------------------------------- | -------------------- |
+| scrollTop      | 需要绑定到 `BackTop` 和 `ScrollView` 组件 `scroll-top` 属性的值 | Ref\<number>         |
+| onScroll       | 需要绑定到 `ScrollView` 组件 `scroll` 事件的回调                | (event: any) => void |
+| onClick        | 需要绑定到 `BackTop` 组件 `click` 事件的回调                    | () => void           |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/back-top/back-top.vue

@@ -14,6 +14,15 @@ import {
   defaultBackTopProps
 } from "./common";
 import SarIcon from "../icon/icon.vue";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {number} scrollTop 当前页面或 scroll-view 滚动的高度，默认值：0。
+ * @property {number} visibleHeight 回到顶部按钮显示时的页面或 scroll-view 滚动的最小高度，默认值：200。
+ * @property {string} right 回到顶部按钮距离右边的距离，默认值：-。
+ * @property {string} bottom 回到顶部按钮距离底部的距离，默认值：-。
+ * @event {(event: any) => void} click 点击时触发
+ */
 export default  _defineComponent({
   components: {
     SarIcon,