@gct-paas/word 0.1.22 → 0.1.24

package/dist/core/view/utils/TextUtil.d.ts

@@ -2,14 +2,30 @@ import { default as Konva } from 'konva';
 export declare class TextUtil {
     /** 字体度量缓存限制 */
     private static readonly FONT_METRICS_CACHE_LIMIT;
-    /** 布局大小缓存限制 */
+    /** 布局大小缓存限制（按「样式 + 单段文本」键，长文档可提高命中率） */
     private static readonly LAYOUT_SIZE_CACHE_LIMIT;
     /** 东亚常见全宽字符块 */
     private static readonly EAST_ASIAN_FULL_WIDTH_REGEX;
     /** 表单/文档中常见的几何符号 */
     private static readonly FULL_WIDTH_SYMBOL_REGEX;
+    /**
+     * 视觉间距系数
+     * 值 = fontSize * ratio
+     *
+     * 解决：
+     * - N·m
+     * - N/A
+     * - kg·m²
+     * 等符号贴太近的问题
+     */
+    private static readonly VISUAL_SPACING_MAP;
     private static fontMetricsCache;
     private static layoutSizeCache;
+    /**
+     * 等待文档字体就绪后再做 Canvas 度量，可减轻 Mac/Windows 因 Web 字体未加载导致的度量差异。
+     * 无 Font Loading API 时立即 resolve。
+     */
+    static awaitDocumentFonts(): Promise<void>;
     /**
      * 验证中文字符
      * @param char
@@ -23,16 +39,53 @@ export declare class TextUtil {
      */
     static isFullWidthChar(char: string): boolean;
     /**
-     * 生成文本度量缓存键
-     * @param payload
-     * @param includeText
+     * 获取字符视觉间距
+     *
+     * 注意：
+     * 这里不是 glyph width
+     * 而是用于排版推进的额外 advance width
+     *
+     * 例如：
+     * - N·m
+     * - N/A
+     *
+     * 中间符号真实宽度很小，
+     * 但视觉上需要 breathing space
+     *
+     * @param char
+     * @param fontSize
      * @returns
      */
-    private static getMeasureCacheKey;
+    static getVisualSpacing(char: string, fontSize: number): number;
+    /** 与度量路径一致：lineHeight 固定为 1 的样式副本 */
+    private static measureBase;
+    /**
+     * 字体级缓存键（不含 text），与 getFontMetrics 语义一致
+     */
+    private static measureStyleKey;
+    /**
+     * 布局缓存键：样式签名 + 编码后的文本
+     */
+    private static layoutCacheKey;
+    private static touchLru;
+    private static evictOldestIfFull;
+    /**
+     * 单次 Konva.Text 计算 width / height（advance width 含视觉间距）
+     */
+    private static computeLayoutSizeUncached;
     /**
-     * 计算度量 - 基于 JSON 序列化的缓存（LRU）
-     * 将最终的 config 序列化为缓存键，相同配置直接返回缓存结果
-     * 最近使用的项会被移到末尾，超限时删除最古老的项
+     * 一次度量：布局宽高 + 字体 ascent/descent（双缓存均未命中时只创建一个 Konva.Text）
+     */
+    static measureTextComplete(payload: Konva.TextConfig): {
+        width: number;
+        height: number;
+        ascent: number;
+        descent: number;
+    };
+    /**
+     * 计算字体度量
+     * ascent / descent
+     *
      * @param payload
      * @returns
      */
@@ -41,7 +94,31 @@ export declare class TextUtil {
         descent: number;
     };
     /**
-     * 计算单个字符布局大小 - 基于 JSON 序列化的缓存（LRU）
+     * 获取字符排版推进宽度
+     *
+     * 注意：
+     * 这里返回的是：
+     * advance width
+     *
+     * 而不是：
+     * glyph width
+     *
+     * 用于：
+     * - 自动换行
+     * - 光标推进
+     * - 文本布局
+     * - selection
+     *
+     * @param payload
+     * @returns
+     */
+    static getAdvanceWidth(payload: Konva.TextConfig): number;
+    /**
+     * 计算单字符布局大小
+     *
+     * 注意：
+     * width 使用 advance width
+     *
      * @param payload
      * @returns
      */
@@ -50,12 +127,12 @@ export declare class TextUtil {
         height: number;
     };
     /**
-     * 清除度量结果缓存
+     * 清除度量缓存
      */
     static clearMeasureCache(): void;
     /**
-     * 获取缓存大小信息
-     * @returns 返回测量缓存的大小 {fontMetrics, layoutSize}
+     * 获取缓存大小
+     * @returns
      */
     static getMeasureCacheSize(): {
         fontMetrics: number;