@zl-ui-kit/composables 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vik05
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @zl-ui-kit/composables
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ZL UI 组合式函数库（TypeScript）：
+
+| 模块 | 说明 |
+| --- | --- |
+| `useRequest/useDataRequest/usePaginationRequest/usePageableRequest` | 请求体系（插件机制：loading/ready/refreshDeps/download，可 `defineUseRequestPlugin` 自定义） |
+| `useGlobalMessage` | **Element Plus 版** ElMessage/ElMessageBox/ElNotification 封装；`Modal.confirmPromise` 语义与参考实现一致 |
+| `useMicroApp/useMicroAction/useMicroGlobalData` | micro-app 微前端通信层（globalData/事件派发/主子身份） |
+| `useDict/useDictStore/useDictProvider/setDictSource` | 字典（独立 Vue3 状态管理 store 缓存，不依赖微前端；支持组件直传 / 局部 source / 全局 source 三级注入） |
+| `useLocale` | vue-i18n + 主应用语言联动（`elLocaleMessages` 对接 EP locale） |
+| `usePageTabs` | 多应用页签管理 |
+| `useSash/useServiceType/useUKey/createCacheComputed` | 其他工具 hook |
+
+## 运行前提（微前端模块）
+
+`useMicro*`、`usePageTabs` 默认运行于 micro-app 微前端环境（决策 §12-Q11：保留并标注前提）。无主应用环境调试时可在**首次调用** `useMicroGlobalData()` 前执行 `enableGlobalDataMock()` 启用本地 mock。字典模块（`useDict` 等）已独立，不依赖微前端，可直接在任意项目中使用。
+
+## 本地调试
+
+playground alias 直指 `src/`；`pnpm build`（tsup）。详见 `docs/调试指南.md`。发布见 `docs/发布流程.md`。

package/dist/index.d.ts

@@ -0,0 +1,595 @@
+import * as vue from 'vue';
+import { ComputedRef, InjectionKey, WritableComputedRef, Ref, Component, VNode, MaybeRef, MaybeRefOrGetter, WatchSource, UnwrapRef, ref } from 'vue';
+export { ComputedRef } from 'vue';
+import { ElMessageBoxOptions, ElMessage, ElMessageBox, ElNotification } from 'element-plus';
+import { I18nOptions, I18n } from 'vue-i18n';
+import microApp from '@micro-zoe/micro-app';
+
+/**
+ * 带缓存的 computed 工厂：同一对象的计算结果缓存，作用域销毁时自动清理
+ */
+
+interface CacheComputed<T, R> {
+    (obj: T): ComputedRef<R>;
+    clear: () => void;
+}
+declare function createCacheComputed<T, R>(getter: (obj: T) => R): CacheComputed<T, R>;
+
+/**
+ * i18n 语言包深度合并工具。
+ *
+ * 语言包结构为「locale → key → 文案」，消费者只需写要覆盖的 key，
+ * 未提供的部分由组件库默认包保留。支持嵌套对象（vue-i18n 的层级 message）。
+ */
+type AnyRecord = Record<string, any>;
+/**
+ * 深度合并语言包，**后者覆盖前者**，未提供的 key 保留原值。
+ *
+ * ```ts
+ * mergeMessages(
+ *   { zh: { 'zl.a': '1', 'zl.b': '2' } },
+ *   { zh: { 'zl.b': '覆盖值' } },
+ * )
+ * // => { zh: { 'zl.a': '1', 'zl.b': '覆盖值' } }
+ * ```
+ */
+declare function mergeMessages<T extends AnyRecord>(base?: T, ...overrides: (AnyRecord | undefined)[]): T;
+
+/** 字典项 */
+interface DictItem {
+    label: string;
+    value: string;
+    icon?: string;
+    type?: string;
+}
+/** 字典数据源：静态字典表，或按 key 动态加载（可异步） */
+type DictSource = Record<string, DictItem[]> | ((key: string) => DictItem[] | Promise<DictItem[]>);
+/**
+ * 全局字典 store（Vue3 状态管理：createGlobalState 单例）
+ * - dictStore：已加载字典的缓存（key → DictItem[]）
+ * - loadingKeys：各 key 的加载态（同时充当「加载中」去重锁）
+ */
+declare const useDictStore: () => {
+    dictStore: vue.Ref<Record<string, DictItem[]>, Record<string, DictItem[]>>;
+    loadingKeys: vue.Ref<Record<string, boolean>, Record<string, boolean>>;
+    setDictSource: (source: DictSource | null) => void;
+    getDictSource: () => DictSource | null;
+    ensureDict: (key: string, localSource?: DictSource) => Promise<void>;
+};
+/**
+ * 全局注册字典数据源（应用入口调用一次）—— 委托给全局字典 store
+ * - 静态表：`setDictSource({ resourceType: [{label,value}], ... })`
+ * - 异步加载：`setDictSource(async (key) => await api.getDict(key))`
+ * - 传 `null` 清空
+ */
+declare function setDictSource(source: DictSource | null): void;
+/** 读取当前全局字典数据源（委托给全局字典 store） */
+declare function getDictSource(): DictSource | null;
+interface DictInjectContext {
+    /** 局部字典数据源（覆盖全局 source） */
+    source?: DictSource;
+}
+/** 字典数据源注入键（useDictProvider 提供） */
+declare const dictInjectKey: InjectionKey<DictInjectContext>;
+/**
+ * 为某棵组件子树提供局部字典数据源（覆盖全局 source，非微前端注入）。
+ * 在子树根组件 setup 中调用即可。
+ */
+declare function useDictProvider(source: DictSource): void;
+interface UseDictReturn extends ComputedRef<DictItem[]> {
+    /** value → label 映射 */
+    label: ComputedRef<Record<string, string>>;
+}
+interface UseDictOptions {
+    /** 直接传入该 key 的字典数据（组件级外部传入；写入缓存后统一解析，优先级最高） */
+    data?: DictItem[];
+}
+/**
+ * 字典 hook：读全局 dictStore 并解析。
+ * @param key 字典键
+ * @param options.data 组件级直传字典数据（可选，优先级最高）
+ */
+declare function useDict(key: string, options?: UseDictOptions): UseDictReturn;
+
+/**
+ * 全局消息（Element Plus 版）
+ * 对外保持参考实现 API：Message / Modal（含 confirmPromise 扩展）/ Notification
+ */
+
+interface ConfirmPromiseOptions extends ElMessageBoxOptions {
+    /** onOk 抛错时是否向上抛出（默认吞错并 resolve(false)） */
+    throwOnOk?: boolean;
+    /** 取消时是否 reject（默认 resolve('Cancel')） */
+    throwOnCancel?: boolean;
+}
+interface ConfirmPromiseContext {
+    close: (ignore?: boolean) => void;
+    resolve: (value?: unknown) => void;
+    reject: (reason?: unknown) => void;
+    instance: unknown;
+}
+type ConfirmPromise = (config: ConfirmPromiseOptions, onOk?: (ctx: ConfirmPromiseContext) => void | Promise<void>, onCancel?: (ctx: ConfirmPromiseContext) => void | Promise<void>) => Promise<'Ok' | 'Cancel' | false | unknown>;
+/** ElMessageBox 的 confirmPromise 扩展类型 */
+type MessageBoxExt = typeof ElMessageBox & {
+    confirmPromise: ConfirmPromise;
+};
+interface GlobalMessage {
+    Message: typeof ElMessage;
+    Modal: MessageBoxExt;
+    Notification: typeof ElNotification;
+}
+/**
+ * 全局消息快捷访问
+ * @param directMode 兼容参考实现的参数（直接返回原始实例）
+ */
+declare function useGlobalMessage(_directMode?: boolean): GlobalMessage;
+
+/**
+ * 国际化（vue-i18n）+ 微前端全局语言联动（elLocaleMessages 对接 Element Plus locale）
+ */
+
+interface LocaleLoaderResult {
+    localeMessages: Record<string, any>;
+    elLocaleMessages: Record<string, any>;
+}
+type LocaleLoader = (locale: string) => Promise<LocaleLoaderResult>;
+type UseLocaleOptions = I18nOptions & {
+    postTranslation?: (translated: string, key: string) => string;
+};
+interface UseLocaleReturn {
+    i18n: I18n;
+    locale: WritableComputedRef<string>;
+    isI18nKeyVisible: WritableComputedRef<boolean>;
+}
+/**
+ * 创建与主应用语言联动的 i18n 实例
+ * @param options i18n 选项（messages 等）
+ * @param loader 语言包按需加载器，返回业务语言包与 Element Plus 语言包
+ */
+declare function useLocale(options?: UseLocaleOptions, loader?: LocaleLoader): UseLocaleReturn;
+
+/**
+ * 安全的国际化翻译函数（组件库渐进式接入 vue-i18n 的桥梁）。
+ *
+ * - 若宿主已 `app.use(i18n)` 安装 vue-i18n：委托其全局 t 进行翻译；
+ * - 若宿主未接入 i18n（存量应用）：安全降级为 fallback / key，绝不抛错。
+ *
+ * 这样组件库可在「不破坏现有消费方」的前提下，逐步把硬编码中文替换为
+ * `t('zl.xxx', '中文兜底')`，待宿主统一安装 i18n 后即自动多语言化。
+ */
+/** 命名插值参数，如 t('zl.upload.accept', fallback, { accept: '.png' }) */
+type TranslateParams = Record<string, unknown>;
+/**
+ * @param key      语言包 key（规范：`zl.<组件>.<语义>`）
+ * @param fallback 兜底文案（宿主未装 i18n / key 未命中时使用；可传入已插值的字符串）
+ * @param params   命名插值参数（命中语言包时由 vue-i18n 插值 `{name}` 占位）
+ */
+type Translate = (key: string, fallback?: string, params?: TranslateParams) => string;
+declare function useZlT(): {
+    t: Translate;
+};
+
+/**
+ * micro-app 跨应用动作通信层（主/子应用事件总线语义）
+ */
+type MicroActionCallback = (...args: any[]) => void;
+interface UseMicroListenerReturn {
+    on: (action: string, callback: MicroActionCallback) => void;
+    off: (action: string, callback: MicroActionCallback) => void;
+    once: (action: string, callback: MicroActionCallback) => void;
+}
+declare const useMicroListener: () => UseMicroListenerReturn;
+/**
+ * 向子应用（或指定应用）派发动作，返回可直接调用的派发函数
+ */
+declare function useMicroAction(action: string, appName?: string): (...args: any[]) => void;
+/**
+ * 派发动作并等待 Promise 化结果
+ */
+declare function useMicroActionAsync(action: string, appName?: string): (...args: any[]) => Promise<unknown>;
+/**
+ * 监听动作的执行结果
+ */
+declare function useMicroResultListener(action: string, callback: MicroActionCallback): void;
+/**
+ * 向指定子应用派发动作（回调式）
+ */
+declare function dispatchMicroAction(action: string, appName: string, ...data: any[]): Promise<void>;
+
+/**
+ * micro-app 微应用管理（主/子应用身份判断、启动、活跃应用列表）
+ */
+
+interface StartMicroAppConfig {
+    [key: string]: any;
+    lifeCycles?: {
+        mounted?: (data?: any) => void;
+        unmounted?: (data?: any) => void;
+    };
+}
+interface UseMicroAppReturn {
+    apps: Ref<string[]>;
+    /** 是否主应用（多层嵌套时可同时为子应用） */
+    isMicroBase: () => boolean;
+    /** 是否子应用（多层嵌套时可同时为主应用） */
+    isMicroChild: () => boolean;
+    updateApps: () => void;
+    startMicroApp: (config?: StartMicroAppConfig) => typeof microApp;
+}
+declare const useMicroApp: () => UseMicroAppReturn;
+
+/**
+ * micro-app 全局数据（globalData）响应式访问层
+ * 脱敏/注入式改造（需求 §7.3、§12-Q3）：
+ * - 存储键 $zl_locale/$zl_theme/$zl_token
+ * - arcoLocaleMessages → elLocaleMessages（Element Plus locale）
+ * - 原 import.meta.env 开发的 mock 开关改为 enableGlobalDataMock() 显式开启（首次 useMicroGlobalData 前调用）
+ */
+
+/**
+ * 开发态启用本地 mock globalData（原实现经构建环境变量开启，现显式注入）
+ */
+declare function enableGlobalDataMock(enabled?: boolean): void;
+interface GlobalDataState {
+    initialed: boolean;
+    locale: string;
+    theme: string;
+    token: string | undefined;
+    isI18nKeyVisible: boolean;
+    roles: string[];
+    permissions: string[];
+    user: any;
+    localeMessages: Record<string, any>;
+    elLocaleMessages: any;
+    config: Record<string, any> | undefined;
+}
+interface UseMicroGlobalDataReturn extends Ref<Partial<GlobalDataState>> {
+    initialed: Readonly<Ref<boolean>>;
+    locale: WritableComputedRef<string>;
+    theme: WritableComputedRef<string>;
+    token: WritableComputedRef<string | undefined>;
+    isI18nKeyVisible: WritableComputedRef<boolean>;
+    roles: WritableComputedRef<string[]>;
+    permissions: WritableComputedRef<string[]>;
+    user: WritableComputedRef<any>;
+    localeMessages: WritableComputedRef<Record<string, any>>;
+    elLocaleMessages: WritableComputedRef<any>;
+    config: WritableComputedRef<Record<string, any> | undefined>;
+    getConfig: <T = any>(key: string, defaultValue?: T) => T;
+    isConfig: (key: string, compareValue?: string) => boolean;
+    setAndWaitUntil: (options: {
+        set?: Record<string, any>;
+        until?: (data: any) => boolean;
+    }) => Promise<void>;
+    resetUser: () => void;
+}
+declare const useMicroGlobalData: () => UseMicroGlobalDataReturn;
+
+type RootOptions = RootComponentOptions | RootMicroOptions;
+interface RootComponentOptions {
+    title: string;
+    key: string;
+    icon?: string;
+    component: Component;
+}
+interface RootMicroOptions {
+    title: string;
+    key: string;
+    icon?: string;
+    micro: string;
+    url: string;
+}
+interface RootStore {
+    tabs: TabStored[];
+    activeTabKey: string;
+    _parentTabMap?: Record<string, TabStored>;
+    _parentMap: Record<string, any>;
+}
+type Tab = ComponentTab | MicroTab;
+type TabStored = Tab & {
+    isRoot?: boolean;
+    isChildRoot?: boolean;
+    isChild?: boolean;
+    isChildMicro?: boolean;
+    rootKey?: string;
+    micro?: string;
+    url?: string;
+    children?: TabStored[];
+    parentTab?: TabStored;
+    /** 用于删除本 tab 时，获取父 Tab 的实例 */
+    _parentTabKey?: string;
+    /** 子 root 页签标识（micro__key） */
+    childRootTabKey?: string;
+    /** 组件页签对外暴露的实例（供回调获取） */
+    exposed?: any;
+};
+interface ComponentTab {
+    key: string;
+    title: string;
+    icon?: string;
+    beforeRemove?: () => boolean | void | Promise<boolean | void>;
+    component: Component;
+    props?: Record<string, any>;
+}
+interface MicroTab {
+    key: string;
+    title: string;
+    icon?: string;
+    beforeRemove?: () => boolean | void | Promise<boolean | void>;
+    micro: string;
+    url: string;
+}
+type ComponentTabVNode = VNode;
+
+/**
+ * 页签管理（micro-app 多应用页签模型：root 树 → 扁平页签 → 当前激活页签）
+ * 内部逻辑保持参考实现语义；类型签名见 ./types/usePageTabs
+ */
+
+interface UsePageTabsReturn {
+    roots: Record<string, RootStore | undefined>;
+    activeRoot: ComputedRef<RootStore | null>;
+    pageTabs: ComputedRef<TabStored[]>;
+    current: ComputedRef<TabStored | undefined>;
+    micros: Readonly<Record<string, string>>;
+    activeRootKey: Readonly<Ref<string | null>>;
+    addMicro: (option: {
+        micro?: string;
+        url?: string;
+    }) => boolean;
+    setRootChild: (tabs: TabStored[], activeChildTabKey: string, micro: string) => void;
+    createPageTabsRoot: (root: RootOptions) => void;
+    addPageTab: (tab: Tab & Record<string, any>, options?: {
+        update?: boolean;
+        childMicro?: boolean;
+    }) => boolean;
+    removePageTab: (tabOrKey?: TabStored | string) => Promise<void | [TabStored, TabStored] | false>;
+    removeCurrentTab: (callback?: (exposed?: any) => Promise<void> | void) => Promise<boolean | void>;
+    clearPageTab: (rootKey?: string) => void;
+    setCurrentTab: (tab: TabStored) => Promise<void>;
+}
+declare function usePageTabs(): UsePageTabsReturn;
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+interface RequestOptions<R, P extends unknown[]> {
+    manual?: boolean;
+    defaultParams?: P;
+    initialData?: R;
+    onBefore?: (params: P) => void;
+    onSuccess?: (data: R, params: P) => void;
+    onError?: (err: Error, params: P) => void;
+    onFinally?: (params: P) => void;
+}
+interface PluginDownloadOptions {
+    outputFile?: MaybeRefOrGetter<string>;
+}
+interface PluginLoadingOptions {
+    loadingDelay?: MaybeRef<number>;
+    loadingKeep?: MaybeRef<number>;
+}
+interface PluginReadyOptions {
+    ready?: Ref<boolean>;
+}
+interface PluginRefreshDepsOptions {
+    refreshDeps?: WatchSource | WatchSource[];
+    refreshDepsAction?: () => void;
+}
+type Options<R, P extends unknown[]> = Prettify<RequestOptions<R, P> & PluginDownloadOptions & PluginLoadingOptions & PluginReadyOptions & PluginRefreshDepsOptions>;
+type Service<R, P extends unknown[]> = (...args: P) => Promise<R>;
+type RequestStatus = '' | 'pending' | 'finished' | 'error';
+interface State<R, P extends unknown[]> {
+    loading: Ref<boolean>;
+    data: Ref<R | undefined>;
+    params: Ref<P>;
+    error: Ref<Error | undefined>;
+    status: Ref<RequestStatus>;
+}
+type UnwrapRefObject<T> = {
+    [P in keyof T]: UnwrapRef<T[P]>;
+};
+type UnwrapState<R, P extends unknown[]> = UnwrapRefObject<State<R, P>>;
+type MutateFunction<R> = (data: R) => R;
+interface FunctionContext<R, P extends unknown[]> {
+    run: (...args: P) => void;
+    runAsync: (...args: P) => Promise<R>;
+    refresh: () => void;
+    refreshAsync: () => Promise<R>;
+    cancel: () => void;
+    mutate: (data: R | MutateFunction<R>) => void;
+}
+interface RequestInstance<R, P extends unknown[]> extends State<R, P> {
+    context: FunctionContext<R, P>;
+    plugins: Ref<PluginReturn<R, P>[]>;
+}
+interface PluginOnBeforeReturn<R, P extends unknown[]> extends Partial<UnwrapState<R, P>> {
+    isBreak?: boolean;
+    isReturn?: boolean;
+}
+interface PluginReturn<R, P extends unknown[]> {
+    onBefore?: (params: P) => PluginOnBeforeReturn<R, P> | void;
+    onRequest?: (service: () => Promise<R>) => () => Promise<R>;
+    onSuccess?: (data: R, params: P) => void;
+    onError?: (error: Error, params: P) => void;
+    onFinally?: (params: P, data: R, error: Error) => void;
+    onCancel?: () => void;
+    onMutate?: (data: R) => void;
+}
+type PluginImplementType<R, P extends unknown[]> = (requestInstance: RequestInstance<R, P>, options?: Options<R, P>) => PluginReturn<R, P>;
+interface UseDataRequestOptions<R, P extends unknown[]> extends Options<R, P> {
+    /** @default `data` */
+    dataKey?: string;
+}
+interface PaginationExtendsOptions {
+    pagination: {
+        /** @default `pageNum` */
+        currentKey?: string;
+        /** @default `pageSize` */
+        pageSizeKey?: string;
+        /** @default `total` */
+        totalKey?: string;
+        /** @default `rows` */
+        dataKey?: string;
+    };
+}
+type UsePaginationRequestOptions<R, P extends unknown[]> = Prettify<Options<R, P> & {
+    pagination?: Partial<PaginationExtendsOptions['pagination']>;
+}>;
+type GlobalOptions = Partial<Prettify<PluginLoadingOptions & PaginationExtendsOptions>>;
+/** useRequest 返回值形态 */
+interface UseRequestReturn<R, P extends unknown[]> extends State<R, P> {
+    __is_use_request: true;
+    cancel: () => void;
+    mutate: (data: R | MutateFunction<R>) => void;
+    run: (...args: P) => void;
+    runAsync: (...args: P) => Promise<R>;
+    refresh: () => void;
+    refreshAsync: () => Promise<R>;
+}
+
+/**
+ * 插件定义工具（类型快捷方式）
+ */
+
+declare function definePlugin<R, P extends unknown[]>(plugin: PluginImplementType<R, P>): PluginImplementType<R, P>;
+
+/**
+ * useRequest 全局配置（全局默认项 + provide/inject 作用域默认项）
+ */
+
+declare function getGlobalOptions(): GlobalOptions;
+declare function setGlobalOptions(options: GlobalOptions): void;
+declare function clearGlobalOptions(): void;
+declare const GLOBAL_OPTIONS_PROVIDER_KEY: InjectionKey<GlobalOptions>;
+declare const DEFAULT_PAGINATION_OPTIONS: {
+    currentKey: string;
+    pageSizeKey: string;
+    totalKey: string;
+    dataKey: string;
+};
+
+/**
+ * useDataRequest：自动解包响应的 data 字段
+ */
+
+interface UseDataRequestReturn<R, P extends unknown[]> extends Omit<UseRequestReturn<R, P>, 'data'> {
+    data: ComputedRef<any>;
+}
+declare function useDataRequest<R, P extends unknown[]>(service: Service<R, P>, options?: UseDataRequestOptions<R, P>, plugins?: PluginImplementType<R, P>[]): UseDataRequestReturn<R, P>;
+
+/**
+ * usePaginationRequest：分页请求（current/pageSize/total/data 键名可配）
+ * usePageableRequest：本地分页数据补页码
+ */
+
+interface UsePaginationRequestReturn<R, P extends unknown[]> extends Omit<UseRequestReturn<R, P>, 'data'> {
+    data: ComputedRef<any[]>;
+    total: ComputedRef<number>;
+    current: WritableComputedRef<number | undefined>;
+    pageSize: WritableComputedRef<number | undefined>;
+    changeCurrent: (pageNum: number) => void;
+    changePageSize: (pageSize: number) => void;
+    changePagination: (current: number, pageSize: number) => void;
+}
+declare function usePaginationRequest<R, P extends unknown[]>(service: Service<R, P>, options?: UsePaginationRequestOptions<R, P>, plugins?: PluginImplementType<R, P>[]): UsePaginationRequestReturn<R, P>;
+interface UsePageableRequestReturn<R, P extends unknown[]> extends UseRequestReturn<R, P> {
+    data: ComputedRef<any>;
+}
+declare function usePageableRequest<R, P extends unknown[]>(service: Service<R, P>, options?: Options<R, P>, plugins?: PluginImplementType<R, P>[]): UsePageableRequestReturn<R, P>;
+
+/**
+ * useRequest：默认携带 loading/ready/refreshDeps/download 四个内置插件
+ */
+
+declare function useRequest<R, P extends unknown[] = []>(service: Service<R, P>, options?: Options<R, P>, plugins?: PluginImplementType<R, P>[]): UseRequestReturn<R, P>;
+
+/**
+ * useRequest 作用域配置（provide 全局默认项）
+ */
+
+declare function useRequestProvider(options: GlobalOptions): void;
+
+/**
+ * 拖拽分隔条（sash）交互
+ */
+
+interface UseSashOptions<Start> {
+    /** 拖拽起点快照（ref 或 getter） */
+    start?: () => Start;
+    onMousedown?: (e: MouseEvent) => void;
+    onMousemove?: (payload: {
+        dx: number;
+        dy: number;
+        start: Start;
+    }, e: MouseEvent) => void;
+    onMouseup?: (e: MouseEvent) => void;
+    onDoubleClick?: (e: MouseEvent) => void;
+}
+interface UseSashReturn {
+    sashElRef: Ref<HTMLElement | null>;
+}
+declare function useSash<Start = undefined>(refName: string, { start, onMousedown, onMousemove, onMouseup, onDoubleClick }?: UseSashOptions<Start>): UseSashReturn;
+
+/**
+ * 服务类型判断（读取主应用下发的 globalData.config）
+ * 默认配置键含业务语义（决策 2026-10-25 参数化保留）：
+ * - platformKey：'zl.service.type' === 'platform' → 平台版
+ * - blockchainKey：'blockchain.service.type' ∈ ['0','1'] → 区块链版
+ * 消费方可传任意键以适配自身 config 约定
+ */
+interface UseServiceTypeOptions {
+    /** 平台版判断的配置键，默认 'zl.service.type' */
+    platformKey?: string;
+    /** 区块链版判断的配置键，默认 'blockchain.service.type'（传空串跳过判断） */
+    blockchainKey?: string;
+}
+interface UseServiceTypeReturn {
+    /** 是否平台版（config[platformKey] === 'platform'） */
+    isPlatform: boolean;
+    /** 是否区块链版（config[blockchainKey] ∈ ['0','1']） */
+    isBlockchain: boolean;
+}
+declare function useServiceType(options?: UseServiceTypeOptions): UseServiceTypeReturn;
+
+/**
+ * UKey 硬件key（厂商 SDK 经 @zl-ui-kit/utils/vendor/mtoken.js 注入 window，此处封装轮询与签名流程）
+ * 运行前提（决策 2026-10-25：保留+标注）：需本机 UKey 厂商 HTTP 服务（默认 127.0.0.1:8080，
+ * 端口经 globalData.config['zl.feature.shufflePort'] 可配）；CSR 默认字段（C=CN/ST=Beijing、pin 111111）
+ * 为厂商协议约定。无 UKey 硬件环境的项目不应调用本 hook。
+ * 脱敏改造（需求 §7.3）：配置键前缀 zl.、设备信息接口 getDevice（原命名含来源前缀）
+ */
+
+interface UKeyRequestData {
+    function: string;
+    sn?: string;
+    pin?: string;
+    [key: string]: unknown;
+}
+interface UKeyCSRData {
+    partyName: string;
+    nodeLabel: string;
+    userName: string;
+}
+interface UKeyDeviceInfo {
+    [key: string]: any;
+    sn: string;
+}
+interface UseUKeyReturn {
+    sn: ReturnType<typeof ref<string>>;
+    getSn: () => Promise<string>;
+    getUser: (pin: string) => Promise<any>;
+    getDevice: () => Promise<UKeyDeviceInfo>;
+    isUserExists: () => Promise<boolean>;
+    getCSR: (data: UKeyCSRData) => Promise<any>;
+    writeCRT: (username: string, certbase64: string, newpin: string) => Promise<any>;
+    sendSign: (params: {
+        pin: string;
+        sn: string;
+        data: string;
+    }) => Promise<any>;
+    stopHeartbeat: () => void;
+}
+declare const useUKey: () => UseUKeyReturn;
+
+export { type CacheComputed, type ComponentTab, type ComponentTabVNode, type ConfirmPromise, type ConfirmPromiseContext, type ConfirmPromiseOptions, DEFAULT_PAGINATION_OPTIONS, type DictInjectContext, type DictItem, type DictSource, type FunctionContext, GLOBAL_OPTIONS_PROVIDER_KEY, type GlobalDataState, type GlobalMessage, type GlobalOptions, type LocaleLoader, type LocaleLoaderResult, type MessageBoxExt, type MicroActionCallback, type MicroTab, type MutateFunction, type Options, type PaginationExtendsOptions, type PluginDownloadOptions, type PluginImplementType, type PluginLoadingOptions, type PluginOnBeforeReturn, type PluginReadyOptions, type PluginRefreshDepsOptions, type PluginReturn, type Prettify, type RequestInstance, type RequestOptions, type RequestStatus, type RootComponentOptions, type RootMicroOptions, type RootOptions, type RootStore, type Service, type StartMicroAppConfig, type State, type Tab, type TabStored, type Translate, type TranslateParams, type UKeyCSRData, type UKeyDeviceInfo, type UKeyRequestData, type UnwrapRefObject, type UnwrapState, type UseDataRequestOptions, type UseDataRequestReturn, type UseDictOptions, type UseDictReturn, type UseLocaleOptions, type UseLocaleReturn, type UseMicroAppReturn, type UseMicroGlobalDataReturn, type UseMicroListenerReturn, type UsePageTabsReturn, type UsePageableRequestReturn, type UsePaginationRequestOptions, type UsePaginationRequestReturn, type UseRequestReturn, type UseSashOptions, type UseSashReturn, type UseServiceTypeOptions, type UseServiceTypeReturn, type UseUKeyReturn, clearGlobalOptions, createCacheComputed, definePlugin as defineUseRequestPlugin, dictInjectKey, dispatchMicroAction, enableGlobalDataMock, getDictSource, getGlobalOptions, mergeMessages, setDictSource, setGlobalOptions, useDataRequest, useDict, useDictProvider, useDictStore, useGlobalMessage, useLocale, useMicroAction, useMicroActionAsync, useMicroApp, useMicroGlobalData, useMicroListener, useMicroResultListener, usePageTabs, usePageableRequest, usePaginationRequest, useRequest, useRequestProvider, useSash, useServiceType, useUKey, useZlT };