sard-uniapp 1.25.5 → 1.25.7

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [1.25.7](https://github.com/sutras/sard-uniapp/compare/v1.25.6...v1.25.7) (2026-01-01)
+
+
+### Bug Fixes
+
+* 修复notice-bar错位问题 ([f4a7e6b](https://github.com/sutras/sard-uniapp/commit/f4a7e6ba0840c9723d51f0add89677c1fe985b07))
+
+
+### Features
+
+* app端允许页面返回时关闭弹出框 ([c538d7f](https://github.com/sutras/sard-uniapp/commit/c538d7fd35ade7bb07f192f35aed2db2515456b9))
+* 小程序端允许页面返回操作关闭弹出框 ([a4fdc64](https://github.com/sutras/sard-uniapp/commit/a4fdc647ae5425ea5c4302493ca00852a7cc3a7a))
+
+
+
+## [1.25.6](https://github.com/sutras/sard-uniapp/compare/v1.25.5...v1.25.6) (2025-12-27)
+
+
+### Features
+
+* **ActionSheet:** 动作面板允许命令式使用 ([d17e03a](https://github.com/sutras/sard-uniapp/commit/d17e03abcb1d9179844a2d6856e4b6d34c0c3a0e))
+
+
+
 ## [1.25.5](https://github.com/sutras/sard-uniapp/compare/v1.25.4...v1.25.5) (2025-11-30)
 
 

package/components/action-sheet/README.md

@@ -15,6 +15,8 @@ group:
 
 ```ts
 import ActionSheet from 'sard-uniapp/components/action-sheet/action-sheet.vue'
+import ActionSheetAgent from 'sard-uniapp/components/action-sheet-agent/action-sheet-agent.vue'
+import { actionSheet } from 'sard-uniapp'
 ```
 
 ## 代码演示
@@ -27,7 +29,7 @@ import ActionSheet from 'sard-uniapp/components/action-sheet/action-sheet.vue'
 
 ### 取消按钮
 
-使用 `cancel` 属性展示取消按钮。
+设置 `show-cancel` 属性展示取消按钮，或者使用 `cancel` 属性在设置取消按钮文本的同时显示取消按钮。
 
 @code('${DEMO_PATH}/action-sheet/demo/Cancel.vue')
 
@@ -43,21 +45,64 @@ import ActionSheet from 'sard-uniapp/components/action-sheet/action-sheet.vue'
 
 @code('${DEMO_PATH}/action-sheet/demo/Status.vue')
 
+### 命令式 <sup>1.25.6+</sup>
+
+先在页面放置代理组件。
+
+```tsx
+<sar-action-sheet-agent />
+```
+
+接着便可以使用 `actionSheet` 方法显示动作面板。
+
+@code('${DEMO_PATH}/action-sheet/demo/Imperative.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    |
+| 属性                           | 描述                                                                 | 类型                   | 默认值 |
+| ------------------------------ | -------------------------------------------------------------------- | ---------------------- | ------ |
+| root-class                     | 组件根元素类名                                                       | string                 | -      |
+| root-style                     | 组件根元素样式                                                       | StyleValue             | -      |
+| description                    | 动作面板描述说明                                                     | string                 | -      |
+| item-list                      | 面板项列表                                                           | ActionSheetItem[]      | []     |
+| show-cancel <sup>1.25.6+</sup> | 是否显示取消按钮                                                     | boolean                | false  |
+| cancel                         | 自定义取消按钮文字                                                   | string                 | -      |
+| visible                        | 是否显示动作面板                                                     | boolean                | false  |
+| overlay-closable               | 点击遮罩后是否关闭                                                   | boolean                | true   |
+| before-close                   | 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭 | ActionSheetBeforeClose | -      |
+| duration                       | 显隐动画时长，单位 ms                                                | number                 | 300    |
+
+#### ActionSheetBeforeClose
+
+```ts
+type ActionSheetBeforeClose =
+  | ((
+      type: 'close' | 'cancel',
+      loading: {
+        readonly cancel: boolean
+        readonly select: boolean
+        readonly close: boolean
+      },
+    ) => any | Promise<any>)
+  | ((
+      type: 'select',
+      item: ActionSheetItem,
+      index: number,
+      loading: {
+        readonly cancel: boolean
+        readonly select: boolean
+        readonly close: boolean
+      },
+    ) => any | Promise<any>)
+```
+
+- 当点击动作项时，`type` 为 `select`；
+- 当点击取消按钮时，`type` 为 `cancel`；
+- 当点击遮罩时，`type` 为 `close`。
+
+`loading` 表示当前哪个按钮处于异步关闭状态。
 
 ### ActionSheetItem
 
@@ -87,6 +132,55 @@ import ActionSheet from 'sard-uniapp/components/action-sheet/action-sheet.vue'
 | after-leave <sup>1.22.1+</sup>     | 退场动画结束时触发          | () => void                                     |
 | leave-cancelled <sup>1.22.1+</sup> | 退场动画取消时触发          | () => void                                     |
 
+### ActionSheetAgentProps / ActionSheetOptions <sup>1.25.6+</sup>
+
+继承 [`ActionSheetProps`](#ActionSheetProps) 并有以下额外属性。
+
+| 属性             | 描述                        | 类型                                           | 默认值        |
+| ---------------- | --------------------------- | ---------------------------------------------- | ------------- |
+| id               | 动作面板组件的 id           | string                                         | 'actionSheet' |
+| onClose          | 点击遮罩时调用              | () => void                                     |
+| onCancel         | 点击取消按钮时调用          | () => void                                     |
+| onSelect         | 点击动作项时调用            | (item: ActionSheetItem, index: number) => void |
+| onVisibleHook    | 入场/退场动画状态改变时调用 | (name: TransitionHookName) => void             |
+| onBeforeEnter    | 入场动画开始前调用          | () => void                                     |
+| onEnter          | 入场动画开始时调用          | () => void                                     |
+| onAfterEnter     | 入场动画结束时调用          | () => void                                     |
+| onEnterCancelled | 入场动画取消时调用          | () => void                                     |
+| onBeforeLeave    | 退场动画开始前调用          | () => void                                     |
+| onLeave          | 退场动画开始时调用          | () => void                                     |
+| onAfterLeave     | 退场动画结束时调用          | () => void                                     |
+| onLeaveCancelled | 退场动画取消时调用          | () => void                                     |
+
+### ActionSheetAgentEmits <sup>1.25.6+</sup>
+
+继承 [`ActionSheetEmits`](#ActionSheetEmits)。
+
+### 命令式方法 <sup>1.25.6+</sup>
+
+| 名称        | 描述                           | 类型                         |
+| ----------- | ------------------------------ | ---------------------------- |
+| actionSheet | 显示动作面板                   | ActionSheetFunction          |
+| hide        | 隐藏指定 `id` 的命令式动作面板 | (id = 'actionSheet') => void |
+| hideAll     | 隐藏所有命令式动作面板         | () => void                   |
+
+### ActionSheetFunction <sup>1.25.6+</sup>
+
+```ts
+type ActionSheetFunction = ActionSheetSimpleShowFunction & {
+  hide: (id?: string) => void
+  hideAll: () => void
+}
+```
+
+### ActionSheetSimpleShowFunction <sup>1.25.6+</sup>
+
+```ts
+interface ActionSheetSimpleShowFunction {
+  (options: ActionSheetOptions): void
+}
+```
+
 ## 主题定制
 
 ### CSS 变量

package/components/action-sheet/action-sheet.d.ts

@@ -14,6 +14,7 @@ declare const _default: import("vue").DefineComponent<ActionSheetProps, {}, {},
     duration: number;
     overlayClosable: boolean;
     itemList: ActionSheetItem[];
-    beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+    showCancel: boolean;
+    beforeClose: import("./common").ActionSheetBeforeClose;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

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

@@ -3,8 +3,10 @@
     effect="slide-bottom"
     :visible="innerVisible"
     :duration="duration"
+    back-press="close"
     @overlay-click="onOverlayClick"
     @visible-hook="onVisibleHook"
+    @back-press="onBackPress"
   >
     <view :class="actionSheetClass" :style="actionSheetStyle">
       <view v-if="description" :class="bem.e('description')">
@@ -37,10 +39,10 @@
           </view>
         </view>
       </view>
-      <template v-if="cancel">
+      <template v-if="mergedShowCancel">
         <view :class="bem.e('gap')"></view>
         <view :class="bem.e('cancel')" @click="onCancel">
-          {{ cancel }}
+          {{ cancel || t('cancel') }}
         </view>
       </template>
     </view>
@@ -49,7 +51,7 @@
 
 <script>
 import { mergeDefaults as _mergeDefaults, defineComponent as _defineComponent } from "vue";
-import { computed, ref, watch } from "vue";
+import { computed, reactive, readonly, ref, watch } from "vue";
 import {
   classNames,
   stringifyStyle,
@@ -63,15 +65,17 @@ import SarLoading from "../loading/loading.vue";
 import {
   defaultActionSheetProps
 } from "./common";
+import { useTranslate } from "../locale";
 /**
  * @property {string} rootClass 组件根元素类名，默认值：-。
  * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
  * @property {string} description 动作面板描述说明，默认值：-。
  * @property {ActionSheetItem[]} itemList 面板项列表，默认值：[]。
- * @property {string} cancel 取消按钮文字，默认值：-。
+ * @property {boolean} showCancel 是否显示取消按钮，默认值：false。
+ * @property {string} cancel 自定义取消按钮文字，默认值：-。
  * @property {boolean} visible 是否显示动作面板，默认值：false。
  * @property {boolean} overlayClosable 点击遮罩后是否关闭，默认值：true。
- * @property {(type: 'close' | 'cancel' | 'select') => any} beforeClose 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭，默认值：-。
+ * @property {ActionSheetBeforeClose} beforeClose 关闭前的回调，返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭，默认值：-。
  * @property {number} duration 显隐动画时长，单位 ms，默认值：300。
  * @event {(visible: boolean) => void} update 动作面板显隐时触发
  * @event {() => void} close 点击遮罩时触发
@@ -105,6 +109,7 @@ export default  _defineComponent({
     description: { type: String, required: false },
     itemList: { type: Array, required: false },
     cancel: { type: String, required: false },
+    showCancel: { type: Boolean, required: false },
     visible: { type: Boolean, required: false },
     overlayClosable: { type: Boolean, required: false },
     beforeClose: { type: Function, required: false },
@@ -116,6 +121,7 @@ export default  _defineComponent({
     const props = __props;
     const emit = __emit;
     const bem = createBem("action-sheet");
+    const { t } = useTranslate("actionSheet");
     const innerVisible = ref(props.visible);
     watch(
       () => props.visible,
@@ -123,9 +129,35 @@ export default  _defineComponent({
         innerVisible.value = props.visible;
       }
     );
-    const perhapsClose = (type) => {
+    const mergedShowCancel = computed(() => props.showCancel || props.cancel);
+    const loading = reactive({
+      cancel: false,
+      select: false,
+      close: false
+    });
+    const readonlyLoading = readonly(loading);
+    const asyncSet =  new Set();
+    watch(
+      innerVisible,
+      () => {
+        if (innerVisible.value === false) {
+          asyncSet.forEach((obj) => {
+            obj.valid = false;
+          });
+          Object.assign(loading, {
+            cancel: false,
+            select: false,
+            close: false
+          });
+        }
+      },
+      {
+        flush: "sync"
+      }
+    );
+    function perhapsClose(type, item, index) {
       if (isFunction(props.beforeClose)) {
-        const result = props.beforeClose(type);
+        const result = type === "select" ? props.beforeClose(type, item, index, readonlyLoading) : props.beforeClose(type, readonlyLoading);
         if (isObject(result) && isFunction(result.then)) {
           return result.then(() => {
             innerVisible.value = false;
@@ -137,17 +169,17 @@ export default  _defineComponent({
       }
       innerVisible.value = false;
       emit("update:visible", false);
-    };
+    }
     const onOverlayClick = () => {
-      emit("close");
       if (props.overlayClosable) {
+        emit("close");
         perhapsClose("close");
       }
     };
     const onSelect = (item, index) => {
       if (!item.disabled && !item.loading) {
         emit("select", item, index);
-        perhapsClose("select");
+        perhapsClose("select", item, index);
       }
     };
     const onCancel = () => {
@@ -158,6 +190,10 @@ export default  _defineComponent({
       emit("visible-hook", name);
       emit(name);
     };
+    const onBackPress = () => {
+      innerVisible.value = false;
+      emit("update:visible", false);
+    };
     const actionSheetClass = computed(() => {
       return classNames(
         bem.b(),
@@ -168,7 +204,7 @@ export default  _defineComponent({
     const actionSheetStyle = computed(() => {
       return stringifyStyle(props.rootStyle);
     });
-    const __returned__ = { props, emit, bem, innerVisible, perhapsClose, onOverlayClick, onSelect, onCancel, onVisibleHook, actionSheetClass, actionSheetStyle, get classNames() {
+    const __returned__ = { props, emit, bem, t, innerVisible, mergedShowCancel, loading, readonlyLoading, asyncSet, perhapsClose, onOverlayClick, onSelect, onCancel, onVisibleHook, onBackPress, actionSheetClass, actionSheetStyle, get classNames() {
       return classNames;
     }, get stringifyStyle() {
       return stringifyStyle;

package/components/action-sheet/common.d.ts

@@ -1,14 +1,24 @@
 import { type StyleValue } from 'vue';
 import { type TransitionHookEmits } from '../popup/common';
+export type ActionSheetBeforeClose = ((type: 'close' | 'cancel', loading: {
+    readonly cancel: boolean;
+    readonly select: boolean;
+    readonly close: boolean;
+}) => any | Promise<any>) & ((type: 'select', item: ActionSheetItem, index: number, loading: {
+    readonly cancel: boolean;
+    readonly select: boolean;
+    readonly close: boolean;
+}) => any | Promise<any>);
 export interface ActionSheetProps {
     rootStyle?: StyleValue;
     rootClass?: string;
     description?: string;
     itemList?: ActionSheetItem[];
     cancel?: string;
+    showCancel?: boolean;
     visible?: boolean;
     overlayClosable?: boolean;
-    beforeClose?: (type: 'close' | 'cancel' | 'select') => boolean | Promise<any>;
+    beforeClose?: ActionSheetBeforeClose;
     duration?: number;
 }
 export declare const defaultActionSheetProps: {
@@ -18,9 +28,10 @@ export declare const defaultActionSheetProps: {
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => string | false | import("vue").CSSProperties | StyleValue[]) | null) | undefined;
     rootClass?: (string | ((props: {
@@ -29,9 +40,10 @@ export declare const defaultActionSheetProps: {
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => string)) | undefined;
     description?: (string | ((props: {
@@ -40,9 +52,10 @@ export declare const defaultActionSheetProps: {
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => string)) | undefined;
     itemList?: ((props: {
@@ -51,9 +64,10 @@ export declare const defaultActionSheetProps: {
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => ActionSheetItem[]) | undefined;
     cancel?: (string | ((props: {
@@ -62,20 +76,34 @@ export declare const defaultActionSheetProps: {
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => string)) | undefined;
+    showCancel?: (boolean | ((props: {
+        rootStyle: StyleValue;
+        rootClass: string;
+        description: string;
+        itemList: ActionSheetItem[];
+        cancel: string;
+        showCancel: boolean;
+        visible: boolean;
+        overlayClosable: boolean;
+        beforeClose: ActionSheetBeforeClose;
+        duration: number;
+    }) => boolean)) | undefined;
     visible?: (boolean | ((props: {
         rootStyle: StyleValue;
         rootClass: string;
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => boolean)) | undefined;
     overlayClosable?: (boolean | ((props: {
@@ -84,31 +112,42 @@ export declare const defaultActionSheetProps: {
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => boolean)) | undefined;
-    beforeClose?: (((type: "close" | "cancel" | "select") => boolean | Promise<any>) | ((props: {
+    beforeClose?: (ActionSheetBeforeClose | ((props: {
         rootStyle: StyleValue;
         rootClass: string;
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
-    }) => (type: "close" | "cancel" | "select") => boolean | Promise<any>)) | undefined;
+    }) => ((type: "close" | "cancel", loading: {
+        readonly cancel: boolean;
+        readonly select: boolean;
+        readonly close: boolean;
+    }) => any | Promise<any>) & ((type: "select", item: ActionSheetItem, index: number, loading: {
+        readonly cancel: boolean;
+        readonly select: boolean;
+        readonly close: boolean;
+    }) => any | Promise<any>))) | undefined;
     duration?: (number | ((props: {
         rootStyle: StyleValue;
         rootClass: string;
         description: string;
         itemList: ActionSheetItem[];
         cancel: string;
+        showCancel: boolean;
         visible: boolean;
         overlayClosable: boolean;
-        beforeClose: (type: "close" | "cancel" | "select") => boolean | Promise<any>;
+        beforeClose: ActionSheetBeforeClose;
         duration: number;
     }) => number)) | undefined;
 };

package/components/action-sheet-agent/action-sheet-agent.d.ts

@@ -0,0 +1,35 @@
+import { type ActionSheetAgentProps } from './common';
+import { type TransitionHookName } from '../../use';
+import { type ActionSheetItem } from '../action-sheet/common';
+declare const _default: import("vue").DefineComponent<ActionSheetAgentProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    [x: string]: any;
+} & {
+    [x: string]: any;
+}, string, import("vue").PublicProps, Readonly<ActionSheetAgentProps> & Readonly<{
+    [x: `on${Capitalize<any>}`]: ((...args: any) => any) | undefined;
+}>, {
+    cancel: string;
+    rootStyle: string | false | import("vue").CSSProperties | import("vue").StyleValue[] | null;
+    rootClass: string;
+    onSelect: (item: ActionSheetItem, index: number) => void;
+    description: string;
+    visible: boolean;
+    id: string;
+    duration: number;
+    overlayClosable: boolean;
+    itemList: ActionSheetItem[];
+    showCancel: boolean;
+    beforeClose: import("../action-sheet/common").ActionSheetBeforeClose;
+    onClose: () => void;
+    onCancel: () => void;
+    onVisibleHook: (name: TransitionHookName) => void;
+    onBeforeEnter: () => void;
+    onEnter: () => void;
+    onAfterEnter: () => void;
+    onEnterCancelled: () => void;
+    onBeforeLeave: () => void;
+    onLeave: () => void;
+    onAfterLeave: () => void;
+    onLeaveCancelled: () => void;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;