@cregis/ui 1.0.23 → 1.0.24

package/dist/types/index.d.ts

@@ -351,8 +351,27 @@ export declare interface InputProps {
     clearText?: string;
 }
 
+export declare const isElementMeasurable: (el: {
+    isConnected: boolean;
+    offsetWidth: number;
+    offsetHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+}) => boolean;
+
 export declare type LanguageKey = 'zh-CN' | 'zh-TW' | 'en-US';
 
+/** 溢出监测目标：元素本身、ref、或 getter */
+export declare type MaybeElementRef = MaybeReadonlyRef<HTMLElement | null | undefined>;
+
+/**
+ * 不依赖 Vue 品牌类型（RefSymbol）的可读 ref。
+ * 跨包 link 时，应用与组件库可能解析到两份 vue 类型，直接使用 MaybeRefOrGetter 会无法传入 ref()。
+ */
+export declare type MaybeReadonlyRef<T> = T | {
+    readonly value: T;
+} | (() => T);
+
 declare type MaybeRef<T> = T | Ref<T>;
 
 /** 函数式轻提示，默认停留 1s，可通过对象配置时长；已有提示展示时忽略新调用 */
@@ -486,6 +505,8 @@ export declare interface RadioProps {
 
 export declare type RadioValue = boolean | string | number;
 
+export declare const resolveTextOverflow: (metrics: TextOverflowMetrics, axis?: TextOverflowAxis, threshold?: number) => TextOverflowState;
+
 export declare const Select: DefineComponent<SelectProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
     "update:modelValue": (value: StringOrNumber_3 | StringOrNumber_3[]) => any;
     change: (value: StringOrNumber_3 | StringOrNumber_3[]) => any;
@@ -707,6 +728,21 @@ export declare type TagSize = 'small' | 'medium' | 'large';
 
 declare type TagType = 'subtle' | 'solid' | 'gray' | 'strokeSubtle' | 'strokeSolid' | 'danger' | 'warning' | 'success' | 'ready' | 'invalid' | 'apricot' | 'khaki' | 'grass' | 'sage' | 'cyan' | 'iceBlue' | 'periwinkle' | 'lilac' | 'orchid' | 'mallow' | 'rose' | 'coral' | 'mauve' | 'moss' | 'steel' | 'grape' | 'sameWhite' | 'lime' | 'amlDanger';
 
+export declare type TextOverflowAxis = 'horizontal' | 'vertical' | 'both';
+
+export declare interface TextOverflowMetrics {
+    scrollWidth: number;
+    clientWidth: number;
+    clientHeight: number;
+    scrollHeight: number;
+}
+
+export declare interface TextOverflowState {
+    overflowX: boolean;
+    overflowY: boolean;
+    overflow: boolean;
+}
+
 export declare const Timeline: DefineComponent<TimelineProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<TimelineProps> & Readonly<{}>, {
     dotSize: number | string;
     lineWidth: number | string;
@@ -810,4 +846,59 @@ export declare interface UploadProps {
  */
 export declare function useClickOutside(target: ClickOutsideTarget | ClickOutsideTarget[], callback: (event: PointerEvent) => void, options?: ClickOutsideOptions): void;
 
+/**
+ * 检测元素是否因内容溢出而产生省略/截断。
+ * 不负责写入省略样式，调用方需自行设置 overflow + text-overflow / line-clamp。
+ */
+export declare function useTextOverflow(target: MaybeElementRef, options?: UseTextOverflowOptions): UseTextOverflowReturn;
+
+export declare interface UseTextOverflowOptions {
+    /**
+     * 检测轴向。
+     * - `horizontal`：单行省略
+     * - `vertical`：多行截断 / line-clamp
+     * - `both`：任一方向溢出即为溢出
+     * @default 'horizontal'
+     */
+    axis?: MaybeReadonlyRef<TextOverflowAxis>;
+    /**
+     * 溢出判定阈值（px），用于吸收亚像素与缩放误差。
+     * @default 1
+     */
+    threshold?: MaybeReadonlyRef<number>;
+    /**
+     * 额外依赖。文本、字号、line-clamp 等不改变元素盒尺寸时需要传入，否则不会重测。
+     */
+    deps?: MaybeReadonlyRef<unknown> | MaybeReadonlyRef<unknown>[];
+    /**
+     * 是否监听元素尺寸变化。
+     * @default true
+     */
+    observeResize?: MaybeReadonlyRef<boolean>;
+    /**
+     * 是否在字体加载完成后补测。web font 替换可能改变文本宽度但不改变盒尺寸。
+     * @default true
+     */
+    observeFonts?: MaybeReadonlyRef<boolean>;
+    /**
+     * 是否用 rAF 合并同一帧内的多次测量（拖拽列宽、连续 deps 更新）。
+     * @default true
+     */
+    raf?: MaybeReadonlyRef<boolean>;
+    /**
+     * 为 `false` 时停止观测，并将溢出状态重置为未溢出。
+     * @default true
+     */
+    enabled?: MaybeReadonlyRef<boolean>;
+}
+
+export declare interface UseTextOverflowReturn {
+    isOverflow: Readonly<Ref<boolean>>;
+    isOverflowX: Readonly<Ref<boolean>>;
+    isOverflowY: Readonly<Ref<boolean>>;
+    /** 同步测量并返回综合溢出结果。布局未完成时请在 DOM 更新后调用。 */
+    checkOverflow: () => boolean;
+    stop: () => void;
+}
+
 export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cregis/ui",
   "private": false,
-  "version": "1.0.23",
+  "version": "1.0.24",
   "type": "module",
   "files": [
     "dist"