@puresnake/snake-ui 0.0.0-stage → 0.0.1

package/libs/form/types.ts

@@ -0,0 +1,51 @@
+export type FormTrigger = 'change' | 'blur';
+export type FormRuleType =
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'method'
+    | 'regexp'
+    | 'integer'
+    | 'float'
+    | 'array'
+    | 'object'
+    | 'date'
+    | 'url'
+    | 'hex'
+    | 'email'
+    | 'any';
+export type FormValidatorResult = boolean | string | Error | void;
+export type FormValidatorCallback = (error?: string | Error) => void;
+
+export interface FormRule {
+    required?: boolean;
+    type?: FormRuleType;
+    min?: number;
+    max?: number;
+    len?: number;
+    enum?: unknown[];
+    pattern?: RegExp | string;
+    whitespace?: boolean;
+    message?: string;
+    trigger?: FormTrigger | FormTrigger[];
+    transform?: (value: unknown) => unknown;
+    validator?: (
+        rule: FormRule,
+        value: unknown,
+        callback: FormValidatorCallback
+    ) => FormValidatorResult | Promise<FormValidatorResult>;
+    asyncValidator?: (
+        rule: FormRule,
+        value: unknown,
+        callback: FormValidatorCallback
+    ) => FormValidatorResult | Promise<FormValidatorResult>;
+    fields?: FormRules;
+    defaultField?: FormRule | FormRule[];
+}
+
+export type FormRules = Record<string, FormRule | FormRule[]>;
+export interface FormError {
+    prop: string;
+    message: string;
+    rule?: FormRule;
+}

package/libs/form/validate.ts

@@ -0,0 +1,149 @@
+import type {
+    FormError,
+    FormRule,
+    FormRules,
+    FormTrigger,
+    FormValidatorCallback,
+    FormValidatorResult
+} from './types';
+
+const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const urlPattern = /^(https?|ftp):\/\/[^\s]+$/i;
+const hexPattern = /^#?(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i;
+
+function empty(value: unknown): boolean {
+    return value == null || value === '' || (Array.isArray(value) && value.length === 0);
+}
+function lengthOf(value: unknown): number | undefined {
+    if (typeof value === 'number') return value;
+    if (typeof value === 'string' || Array.isArray(value)) return value.length;
+    return undefined;
+}
+function defaultMessage(rule: FormRule): string {
+    if (rule.required) return '此项为必填项';
+    if (rule.len != null) return `长度必须为 ${rule.len}`;
+    if (rule.min != null && rule.max != null) return `长度或数值应在 ${rule.min}-${rule.max} 之间`;
+    if (rule.min != null) return `长度或数值不能小于 ${rule.min}`;
+    if (rule.max != null) return `长度或数值不能大于 ${rule.max}`;
+    return '格式不正确';
+}
+function typeMatches(type: FormRule['type'], value: unknown): boolean {
+    if (!type || type === 'any') return true;
+    if (type === 'array') return Array.isArray(value);
+    if (type === 'date') {
+        const date = typeof value === 'number' ? new Date(value) : value;
+        return date instanceof Date && !Number.isNaN(date.getTime());
+    }
+    if (type === 'regexp') return value instanceof RegExp;
+    if (type === 'integer') return typeof value === 'number' && Number.isInteger(value);
+    if (type === 'float') return typeof value === 'number' && Number.isFinite(value);
+    if (type === 'method') return typeof value === 'function';
+    if (type === 'url') return typeof value === 'string' && urlPattern.test(value);
+    if (type === 'email') return typeof value === 'string' && emailPattern.test(value);
+    if (type === 'hex') return typeof value === 'string' && hexPattern.test(value);
+    if (type === 'number') return typeof value === 'number' && !Number.isNaN(value);
+    return typeof value === type;
+}
+function normalizeCustomResult(result: FormValidatorResult, fallback: string): string | undefined {
+    if (result === false) return fallback;
+    if (typeof result === 'string') return result;
+    if (result instanceof Error) return result.message || fallback;
+    return undefined;
+}
+
+async function runCustom(rule: FormRule, value: unknown): Promise<string | undefined> {
+    const validator = rule.asyncValidator || rule.validator;
+    if (!validator) return undefined;
+    return new Promise(resolve => {
+        let completed = false;
+        const done: FormValidatorCallback = error => {
+            if (completed) return;
+            completed = true;
+            resolve(typeof error === 'string' ? error : error?.message);
+        };
+        try {
+            const result = validator(rule, value, done);
+            if (result && typeof (result as Promise<FormValidatorResult>).then === 'function') {
+                void (result as Promise<FormValidatorResult>)
+                    .then(value => {
+                        if (!completed) {
+                            completed = true;
+                            resolve(normalizeCustomResult(value, rule.message || '校验失败'));
+                        }
+                    })
+                    .catch(error => done(error instanceof Error ? error : String(error)));
+            } else if (result !== undefined) {
+                completed = true;
+                resolve(normalizeCustomResult(result as FormValidatorResult, rule.message || '校验失败'));
+            } else if (validator.length < 3) {
+                completed = true;
+                resolve(undefined);
+            }
+        } catch (error) {
+            done(error instanceof Error ? error : String(error));
+        }
+    });
+}
+
+export function ruleMatchesTrigger(rule: FormRule, trigger?: FormTrigger): boolean {
+    if (!trigger || !rule.trigger) return true;
+    return (Array.isArray(rule.trigger) ? rule.trigger : [rule.trigger]).includes(trigger);
+}
+
+export async function validateFormValue(
+    prop: string,
+    rawValue: unknown,
+    rules: FormRule | FormRule[],
+    trigger?: FormTrigger
+): Promise<FormError[]> {
+    const list = (Array.isArray(rules) ? rules : [rules]).filter(rule => ruleMatchesTrigger(rule, trigger));
+    const errors: FormError[] = [];
+    for (const rule of list) {
+        const value = rule.transform ? rule.transform(rawValue) : rawValue;
+        let message: string | undefined;
+        if (rule.required && empty(value)) message = rule.message || defaultMessage(rule);
+        else if (!empty(value)) {
+            const length = lengthOf(value);
+            if (!typeMatches(rule.type, value)) message = rule.message || defaultMessage(rule);
+            else if (rule.len != null && length !== rule.len) message = rule.message || defaultMessage(rule);
+            else if (rule.min != null && length != null && length < rule.min)
+                message = rule.message || defaultMessage(rule);
+            else if (rule.max != null && length != null && length > rule.max)
+                message = rule.message || defaultMessage(rule);
+            else if (rule.enum && !rule.enum.includes(value)) message = rule.message || defaultMessage(rule);
+            else if (rule.pattern) {
+                const pattern = typeof rule.pattern === 'string' ? new RegExp(rule.pattern) : rule.pattern;
+                pattern.lastIndex = 0;
+                if (!pattern.test(String(value))) message = rule.message || defaultMessage(rule);
+            } else if (rule.whitespace && typeof value === 'string' && /^\s+$/.test(value)) {
+                message = rule.message || defaultMessage(rule);
+            } else message = await runCustom(rule, value);
+
+            if (!message && value && (rule.fields || rule.defaultField) && typeof value === 'object') {
+                const childRules: FormRules = { ...(rule.fields || {}) };
+                if (rule.defaultField) {
+                    for (const key of Object.keys(value as Record<string, unknown>)) {
+                        if (!childRules[key]) childRules[key] = rule.defaultField;
+                    }
+                }
+                for (const [key, childRule] of Object.entries(childRules)) {
+                    const childErrors = await validateFormValue(
+                        `${prop}.${key}`,
+                        (value as Record<string, unknown>)[key],
+                        childRule,
+                        trigger
+                    );
+                    if (childErrors.length) {
+                        message = childErrors[0].message;
+                        break;
+                    }
+                }
+            }
+        }
+        if (message) {
+            errors.push({ prop, message, rule });
+            break;
+        }
+    }
+    return errors;
+}

package/libs/foundation.ts

@@ -0,0 +1,96 @@
+/**
+ * Snake UI 全局 API 聚合与插件初始化。
+ *
+ * foundation 汇总工具函数、hooks、主题、国际化、HTTP 与全局配置，
+ * 经根入口挂载为 $snake；宿主注入的 request / cache 等运行时适配器
+ * 由 libs/runtime 负责，不经此文件。
+ */
+import type { App } from 'vue';
+import type { RuntimeOptions } from './runtime';
+import { config, setConfig, SNAKE_UI_VERSION } from './config/state';
+import zIndex from './config/zIndex';
+import {
+    currentTheme,
+    initTheme,
+    isDarkMode,
+    setDarkMode,
+    setTheme,
+    setThemeColor,
+    color,
+    cssVars,
+    darkMode,
+    themes,
+    toggleDarkMode
+} from './config/theme';
+import * as functions from './function';
+import { emitter } from './function/emitter';
+import * as hooks from './hooks';
+import { currentLocale, initLocale, setLocale, locales, translate } from '../locale';
+import { configureHttp, http } from './request';
+import { configureCms } from './cms';
+
+/**
+ * 全局 API 聚合：工具函数与 hooks 全量展开，再显式补上配置、
+ * 主题、国际化、HTTP 等具名成员，并保留 date / isInDarkMode / t 等短别名。
+ */
+export const foundation = {
+    ...functions,
+    ...hooks,
+    color: color,
+    config: config,
+    zIndex,
+    version: SNAKE_UI_VERSION,
+    /** 语义色类型清单，toast / modal 等组件按它约束 type 取值。 */
+    type: ['primary', 'success', 'error', 'warning', 'info'],
+    /** date 是 formatTime 的短别名。 */
+    date: functions.formatTime,
+    emitter: emitter,
+    http,
+    themes: themes,
+    currentTheme: currentTheme,
+    darkMode: darkMode,
+    cssVars: cssVars,
+    locales: locales,
+    currentLocale: currentLocale,
+    initTheme: initTheme,
+    setTheme: setTheme,
+    setThemeColor: setThemeColor,
+    setDarkMode: setDarkMode,
+    toggleDarkMode: toggleDarkMode,
+    isInDarkMode: isDarkMode,
+    initLocales: initLocale,
+    setLocale: setLocale,
+    /** t 是 translate 的短别名。 */
+    t: translate
+};
+
+/** foundation 的公开类型视图，供宿主对 $snake 做类型标注。 */
+export type FoundationAPI = typeof foundation;
+/** Snake UI 的唯一全局 API 聚合。运行时适配器不在这里安装。 */
+export const snake = foundation;
+
+/**
+ * 安装 UI 基座：由根入口（index.ts 的 install）调用，在 $snake
+ * 挂载到全局属性之前完成配置、主题、语言、HTTP 与 CMS 的初始化。
+ *
+ * - `$http`：请求全局属性，与 snake.http 同一单例。
+ * - `$themeStyle`：用 getter 定义而非直接赋值，模板每次读取都取
+ *   cssVars 当前值，主题切换后不需要重新挂属性、也不会固化快照。
+ * - provide 的 theme / locale 面向宿主业务组件 inject 使用；
+ *   snake-ui 自身组件直接消费 config/theme 与 locale 模块，
+ *   不依赖这两个注入。
+ */
+export function installUIFoundation(app: App, options: RuntimeOptions = {}): void {
+    setConfig({ debugMode: options.debugMode ?? false });
+    initTheme(options.theme);
+    initLocale(options.locale);
+    configureHttp(options.http, options.request);
+    (app.config.globalProperties as Record<string, unknown>).$http = http;
+    configureCms(options.cms);
+    Object.defineProperty(app.config.globalProperties, '$themeStyle', {
+        configurable: true,
+        get: () => cssVars.value
+    });
+    app.provide('snake-ui-theme', currentTheme);
+    app.provide('snake-ui-locale', currentLocale);
+}

package/libs/function/$parent.ts

@@ -0,0 +1,33 @@
+// 获取父组件实例，因为支付宝小程序不支持 provide/inject 的写法
+// 在非 H5 中 instance.parent 可以准确获取到父组件，但在 H5 中需要多层 parent.parent.xxx
+// componentName 默认 undefined 有其含义：最顶层元素的 parent 就是 undefined，
+// 不传 name 即查找最顶层的父实例。
+//
+// 注意：本文件属于 function/ 基础层，会被 node 直载测试加载，禁止 import 'vue'；
+// 调用方（组件内）自行传入 getCurrentInstance() 结果，与 getRect(selector, instance) 约定一致。
+
+export interface ParentLike {
+    parent?: ParentLike | null;
+    type?: { name?: string };
+}
+
+export function $parent(
+    componentName?: string,
+    instance?: ParentLike | null
+): ParentLike | null | undefined {
+    let parent = instance?.parent ?? null;
+
+    if (!componentName) return parent;
+
+    while (parent) {
+        const name = parent.type?.name;
+        if (name === componentName) {
+            return parent;
+        }
+        parent = parent.parent ?? null;
+    }
+    return null;
+}
+
+// 兼容默认导入习惯：import $parent from '.../$parent'
+export default $parent;

package/libs/function/clipboard.ts

@@ -0,0 +1,13 @@
+/**
+ * 复制文本到剪贴板（Promise 版）：成功 resolve，平台无该 API 或调用失败 reject。
+ * 不接管提示——小程序端由 uni 默认行为弹「已复制」。
+ */
+export function clipboard(value: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        if (typeof uni === 'undefined' || typeof uni.setClipboardData !== 'function') {
+            reject(new Error('[Snake UI] clipboard is unavailable on this platform.'));
+            return;
+        }
+        uni.setClipboardData({ data: value, success: () => resolve(), fail: reject });
+    });
+}

package/libs/function/color.ts

@@ -0,0 +1,55 @@
+/** 归一化 hex：接受 3 / 6 位（可带 #），3 位展开为 6 位，其余返回 undefined。 */
+function normalizeHex(value: string): string | undefined {
+    const color = value.trim().replace('#', '');
+    if (/^[0-9a-f]{3}$/i.test(color))
+        return color
+            .split('')
+            .map(item => item.repeat(2))
+            .join('');
+    return /^[0-9a-f]{6}$/i.test(color) ? color : undefined;
+}
+
+/** hex → { r, g, b }；无法解析时返回 undefined。 */
+export function hexToRgb(value: string): { r: number; g: number; b: number } | undefined {
+    const color = normalizeHex(value);
+    if (!color) return undefined;
+    return {
+        r: Number.parseInt(color.slice(0, 2), 16),
+        g: Number.parseInt(color.slice(2, 4), 16),
+        b: Number.parseInt(color.slice(4, 6), 16)
+    };
+}
+
+/** rgb → #rrggbb；各通道先收敛到 [0, 255] 再取整，输出恒为 6 位。 */
+export function rgbToHex(r: number, g: number, b: number): string {
+    const channel = (value: number) =>
+        Math.min(255, Math.max(0, Math.round(value)))
+            .toString(16)
+            .padStart(2, '0');
+    return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+
+/** hex → rgba(...)：alpha 收敛到 [0, 1]，无法解析的输入原样返回。 */
+export function colorToRgba(value: string, alpha = 1): string {
+    const rgb = hexToRgb(value);
+    return rgb ? `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${Math.min(1, Math.max(0, alpha))})` : value;
+}
+
+/**
+ * 两色之间的线性渐变阶梯，首尾正好是起止色。
+ * @param steps 阶梯数：<=0 返回空数组，1 只返回起点色
+ */
+export function colorGradient(start: string, end: string, steps: number): string[] {
+    const from = hexToRgb(start);
+    const to = hexToRgb(end);
+    if (!from || !to || steps <= 0) return [];
+    if (steps === 1) return [rgbToHex(from.r, from.g, from.b)];
+    return Array.from({ length: steps }, (_, index) => {
+        const ratio = index / (steps - 1);
+        return rgbToHex(
+            from.r + (to.r - from.r) * ratio,
+            from.g + (to.g - from.g) * ratio,
+            from.b + (to.b - from.b) * ratio
+        );
+    });
+}

package/libs/function/debounce.ts

@@ -0,0 +1,34 @@
+/** 包装后的函数：保留原调用能力，另提供 cancel() 取消未触发的定时执行。 */
+export interface CancelableFunction<Args extends unknown[]> {
+    (...args: Args): void;
+    cancel(): void;
+}
+
+/**
+ * 防抖：wait 毫秒内只有最后一次调用生效，静默期结束后执行。
+ * @param callback 目标回调，参数由包装函数透传
+ * @param wait 防抖窗口，单位 ms，默认 300
+ * @param immediate true 时首次调用立即执行并进入冷却，默认 false
+ * @returns 带 cancel() 的包装函数
+ */
+export function debounce<Args extends unknown[]>(
+    callback: (...args: Args) => void,
+    wait = 300,
+    immediate = false
+): CancelableFunction<Args> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const wrapped = ((...args: Args) => {
+        const callNow = immediate && !timer;
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (!immediate) callback(...args);
+        }, wait);
+        if (callNow) callback(...args);
+    }) as CancelableFunction<Args>;
+    wrapped.cancel = () => {
+        if (timer) clearTimeout(timer);
+        timer = undefined;
+    };
+    return wrapped;
+}

package/libs/function/deepClone.ts

@@ -0,0 +1,30 @@
+/**
+ * 深拷贝：WeakMap 记录「原对象 → 克隆」以支持循环引用，
+ * Reflect.ownKeys 连 Symbol 键与不可枚举键一起复制，
+ * Date / Map / Set 重建新实例，其余引用类型按对象 / 数组重构。
+ * @param value 任意值，原始类型直接返回
+ * @param seen 循环引用缓存，递归内部使用
+ */
+export function deepClone<T>(value: T, seen = new WeakMap<object, unknown>()): T {
+    if (value == null || typeof value !== 'object') return value;
+    if (seen.has(value as object)) return seen.get(value as object) as T;
+    if (value instanceof Date) return new Date(value.getTime()) as T;
+    if (value instanceof Map) {
+        const result = new Map();
+        seen.set(value, result);
+        value.forEach((item, key) => result.set(deepClone(key, seen), deepClone(item, seen)));
+        return result as T;
+    }
+    if (value instanceof Set) {
+        const result = new Set();
+        seen.set(value, result);
+        value.forEach(item => result.add(deepClone(item, seen)));
+        return result as T;
+    }
+    const result: unknown[] | Record<PropertyKey, unknown> = Array.isArray(value) ? [] : {};
+    seen.set(value as object, result);
+    Reflect.ownKeys(value as object).forEach(key => {
+        (result as Record<PropertyKey, unknown>)[key] = deepClone((value as Record<PropertyKey, unknown>)[key], seen);
+    });
+    return result as T;
+}

package/libs/function/deepMerge.ts

@@ -0,0 +1,25 @@
+import { deepClone } from './deepClone';
+
+/** 纯对象判定（原型为 null 或 Object.prototype），非纯对象不参与递归合并。 */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (!value || Object.prototype.toString.call(value) !== '[object Object]') return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype === Object.prototype;
+}
+
+/**
+ * 多源深合并：target 深拷贝后作为基底（不改动入参），sources 依次覆盖。
+ * 只有两侧都是纯对象才递归合并；数组等其余值整体替换为深拷贝。
+ */
+export function deepMerge<T extends Record<string, any>>(target: T, ...sources: Array<Partial<T>>): T {
+    const result = deepClone(target);
+    sources.forEach(source => {
+        Object.entries(source || {}).forEach(([key, value]) => {
+            const previous = result[key];
+            result[key as keyof T] = (
+                isPlainObject(previous) && isPlainObject(value) ? deepMerge(previous, value) : deepClone(value)
+            ) as T[keyof T];
+        });
+    });
+    return result;
+}

package/libs/function/emitter.ts

@@ -0,0 +1,30 @@
+export type EventHandler<Payload = unknown> = (payload: Payload) => void;
+
+/**
+ * 轻量事件总线：同一 handler 用 Set 去重，on 返回解绑函数，
+ * off 不传 handler 时清空整个事件，clear() 清空全部事件。
+ */
+export function createEmitter() {
+    const events = new Map<string, Set<EventHandler>>();
+    return {
+        on<Payload>(name: string, handler: EventHandler<Payload>) {
+            const handlers = events.get(name) || new Set();
+            handlers.add(handler as EventHandler);
+            events.set(name, handlers);
+            return () => handlers.delete(handler as EventHandler);
+        },
+        off<Payload>(name: string, handler?: EventHandler<Payload>) {
+            if (!handler) events.delete(name);
+            else events.get(name)?.delete(handler as EventHandler);
+        },
+        emit<Payload>(name: string, payload: Payload) {
+            events.get(name)?.forEach(handler => handler(payload));
+        },
+        clear() {
+            events.clear();
+        }
+    };
+}
+
+/** 库内共享的事件总线单例。 */
+export const emitter = createEmitter();

package/libs/function/format.ts

@@ -0,0 +1,27 @@
+/**
+ * 价格格式化：剥离非数字字符后按 decimals 保留小数、整数部分加千分位；
+ * 非有限数值按 0 处理。
+ * @param value 数字或数字字符串
+ * @param decimals 小数位数，默认 0
+ * @param decimalPoint 小数点符号，默认 '.'
+ * @param thousandsSeparator 千分位符号，默认 ','
+ */
+export function formatPrice(
+    value: string | number,
+    decimals = 0,
+    decimalPoint = '.',
+    thousandsSeparator = ','
+): string {
+    const numeric = Number(String(value).replace(/[^0-9+\-Ee.]/g, ''));
+    const safe = Number.isFinite(numeric) ? numeric : 0;
+    const fixed = safe.toFixed(Math.max(0, decimals)).split('.');
+    fixed[0] = fixed[0].replace(/\B(?=(\d{3})+(?!\d))/g, thousandsSeparator);
+    return fixed.join(decimalPoint);
+}
+
+/** 姓名脱敏：单字原样，两字保首打 *，三字以上首尾保留、中间打 *。 */
+export function formatName(value: string): string {
+    if (value.length <= 1) return value;
+    if (value.length === 2) return `${value[0]}*`;
+    return `${value[0]}${'*'.repeat(value.length - 2)}${value.at(-1)}`;
+}

package/libs/function/getParent.ts

@@ -0,0 +1,53 @@
+// 获取父组件的参数，因为支付宝小程序不支持 provide/inject 的写法
+// this.$parent 在非 H5 中可以准确获取到父组件，但在 H5 中需要多层 this.$parent.$parent.xxx
+interface VueInstance {
+    $parent?: VueInstance;
+    $options?: { name?: string };
+    [key: string]: any;
+}
+
+/**
+ * 沿 $parent 链查找指定 name 的父组件并按 keys 取参。
+ * @param this 当前组件实例（Options API 调用方用 getParent.call(this, ...)）
+ * @param name 父组件 name
+ * @param keys 需要获取的参数名数组或对象；对象形态时子组件已有值优先（false 也算已传）
+ * @returns 父组件参数对象
+ */
+export function getParent(
+    this: VueInstance,
+    name: string,
+    keys: string[] | Record<string, any>
+): Record<string, any> {
+    let parent = this.$parent;
+    // 通过 while 历遍，这里主要是为了 H5 需要多层解析的问题
+    while (parent) {
+        if (parent.$options?.name !== name) {
+            // 如果组件的 name 不相等，继续上一级寻找
+            parent = parent.$parent;
+        } else {
+            const data: Record<string, any> = {};
+            // 传数组时直接用数组元素值当做键值去父组件寻找
+            if (Array.isArray(keys)) {
+                keys.forEach(val => {
+                    data[val] = parent?.[val] ? parent[val] : '';
+                });
+            } else {
+                for (const key in keys) {
+                    const childValue = keys[key];
+                    // 空数组/空对象视为未传，回落父组件的值
+                    if (Array.isArray(childValue) || (childValue && childValue.constructor === Object)) {
+                        data[key] = Object.keys(childValue).length ? childValue : parent[key];
+                    } else {
+                        // 只要子组件有传值，即使是 false 值也算「传值」，覆盖父组件的同名参数
+                        data[key] = childValue || childValue === false ? childValue : parent[key];
+                    }
+                }
+            }
+            return data;
+        }
+    }
+    return {};
+}
+
+// 兼容默认导入习惯：import getParent from '.../getParent'
+export default getParent;

package/libs/function/getRect.ts

@@ -0,0 +1,29 @@
+export type SelectorRect = UniApp.NodeInfo & { width: number; height: number; top: number; left: number };
+
+/**
+ * 查询节点布局信息（boundingClientRect）。
+ * 查不到节点不 reject：单值返回全 0 兜底 rect，all=true 返回空数组，调用方无需判空。
+ * @param selector CSS 选择器
+ * @param instance 组件实例（自动取 .proxy）或上下文对象；不传则页面级查询
+ * @param all 是否查询全部匹配节点（返回数组）
+ */
+export function getRect(selector: string, instance?: unknown, all?: false): Promise<SelectorRect>;
+export function getRect(selector: string, instance: unknown | undefined, all: true): Promise<SelectorRect[]>;
+export function getRect(selector: string, instance?: unknown, all = false): Promise<SelectorRect | SelectorRect[]> {
+    return new Promise(resolve => {
+        let query = uni.createSelectorQuery();
+        // instance 可能是组件实例（取 .proxy）也可能是上下文对象；部分平台无 query.in，降级为页面级查询
+        const target = (instance as { proxy?: unknown } | undefined)?.proxy ?? instance;
+        if (target && typeof query.in === 'function') query = query.in(target);
+        const builder = all ? query.selectAll(selector) : query.select(selector);
+        builder
+            .boundingClientRect(rect =>
+                resolve(
+                    all
+                        ? ((rect || []) as SelectorRect[])
+                        : ((rect || { width: 0, height: 0, top: 0, left: 0 }) as SelectorRect)
+                )
+            )
+            .exec();
+    });
+}

package/libs/function/guid.ts

@@ -0,0 +1,11 @@
+/**
+ * 生成带前缀的轻量唯一 id：`前缀-时间戳36进制-随机串`。
+ * 时间戳保证趋势递增，随机段兜底同毫秒碰撞，适合做组件内部 key、
+ * v-for 列表 id（避免用 index 导致复用错乱）。
+ * 非加密强度，勿用于令牌等安全场景。
+ * @param prefix id 前缀，默认 'snake'
+ */
+export function guid(prefix = 'snake'): string {
+    const random = Math.random().toString(36).slice(2, 10);
+    return `${prefix}-${Date.now().toString(36)}-${random}`;
+}