ht-emr 0.6.2 → 0.6.3

package/dist/src/editor/core/event/CanvasEvent.d.ts

@@ -3,55 +3,198 @@ import { ICurrentPosition, IPositionContext } from '../../interface/Position';
 import { Draw } from '../draw/Draw';
 import { IRange, IRangeElementStyle } from '../../interface/Range';
 import { ICopyOption } from '../../interface/Event';
+/**
+ * 输入法组合信息接口
+ *
+ * 在使用输入法（如中文输入法）时，记录组合输入的状态信息。
+ */
 export interface ICompositionInfo {
+    /** 组合开始时的起始索引 */
     startIndex: number;
+    /** 组合结束时的结束索引 */
     endIndex: number;
+    /** 组合输入的值 */
     value: string;
+    /** 默认样式 */
     defaultStyle: IRangeElementStyle | null;
+    /** 是否取消组合 */
     cancel?: boolean;
+    /** 性能计时开始时间 */
     perfStartTime?: number;
 }
+/**
+ * 鼠标按下起始位置接口
+ *
+ * 记录鼠标按下时的位置信息，用于拖拽和选区操作。
+ */
 export interface MouseDownStartPosition extends ICurrentPosition {
+    /** 鼠标按下时的原始元素索引 */
     originalIndex?: number;
 }
+/**
+ * Canvas事件处理类
+ *
+ * 负责处理Canvas上的所有用户交互事件：
+ * - 鼠标事件（点击、双击、三击、拖拽等）
+ * - 键盘事件
+ * - 输入法组合事件
+ * - 拖放事件
+ *
+ * 该类是用户与编辑器交互的核心桥梁。
+ */
 export declare class CanvasEvent {
+    /** 是否允许选区操作 */
     isAllowSelection: boolean;
+    /** 是否正在进行输入法组合 */
     isComposing: boolean;
+    /** 输入法组合信息 */
     compositionInfo: ICompositionInfo | null;
+    /** 是否允许拖拽 */
     isAllowDrag: boolean;
+    /** 是否允许放置 */
     isAllowDrop: boolean;
+    /** 缓存的选区信息 */
     cacheRange: IRange | null;
+    /** 缓存的元素列表 */
     cacheElementList: IElement[] | null;
+    /** 缓存的位置列表 */
     cachePositionList: IElementPosition[] | null;
+    /** 缓存的位置上下文 */
     cachePositionContext: IPositionContext | null;
+    /** 鼠标按下时的起始位置 */
     mouseDownStartPosition: MouseDownStartPosition | null;
+    /** Draw实例 */
     private draw;
+    /** 页面容器元素 */
     private pageContainer;
+    /** Canvas页面列表 */
     private pageList;
+    /** 选区管理器 */
     private range;
+    /** 位置管理器 */
     private position;
+    /**
+     * 创建Canvas事件处理器
+     * @param draw - Draw实例
+     */
     constructor(draw: Draw);
+    /**
+     * 获取Draw实例
+     * @returns Draw实例
+     */
     getDraw(): Draw;
+    /**
+     * 注册事件监听器
+     *
+     * 为页面容器绑定所有必要的事件监听器。
+     */
     register(): void;
+    /**
+     * 设置是否允许选区操作
+     * @param payload - 是否允许
+     */
     setIsAllowSelection(payload: boolean): void;
+    /**
+     * 设置是否允许拖拽
+     * @param payload - 是否允许
+     */
     setIsAllowDrag(payload: boolean): void;
+    /**
+     * 清除格式刷样式
+     *
+     * 重置光标样式并清除格式刷状态。
+     */
     clearPainterStyle(): void;
+    /**
+     * 应用格式刷样式
+     *
+     * 将格式刷样式应用到当前选区或光标所在的词组。
+     */
     applyPainterStyle(): void;
+    /**
+     * 全选操作
+     *
+     * 选中所有内容。在表格内时选中整个表格。
+     */
     selectAll(): void;
+    /**
+     * 处理鼠标移动事件
+     * @param evt - 鼠标事件对象
+     */
     mousemove(evt: MouseEvent): void;
+    /**
+     * 处理鼠标按下事件
+     * @param evt - 鼠标事件对象
+     */
     mousedown(evt: MouseEvent): void;
+    /**
+     * 处理点击事件
+     *
+     * 在iOS系统上，需要用户主动触发才能弹出键盘。
+     */
     click(): void;
+    /**
+     * 处理鼠标释放事件
+     * @param evt - 鼠标事件对象
+     */
     mouseup(evt: MouseEvent): void;
+    /**
+     * 处理鼠标离开事件
+     * @param evt - 鼠标事件对象
+     */
     mouseleave(evt: MouseEvent): void;
+    /**
+     * 处理键盘按下事件
+     * @param evt - 键盘事件对象
+     */
     keydown(evt: KeyboardEvent): void;
+    /**
+     * 处理双击事件
+     * @param evt - 鼠标事件对象
+     */
     dblclick(evt: MouseEvent): void;
+    /**
+     * 处理三击事件
+     *
+     * 三击选中整个段落。
+     */
     threeClick(): void;
+    /**
+     * 处理文本输入事件
+     * @param data - 输入的文本数据
+     * @param source - 输入来源
+     */
     input(data: string, source?: string): void;
+    /**
+     * 处理剪切操作
+     */
     cut(): Promise<void>;
+    /**
+     * 处理复制操作
+     * @param options - 复制选项
+     */
     copy(options?: ICopyOption): Promise<void>;
+    /**
+     * 处理输入法组合开始事件
+     */
     compositionstart(): void;
+    /**
+     * 处理输入法组合结束事件
+     * @param evt - 组合事件对象
+     */
     compositionend(evt: CompositionEvent): void;
+    /**
+     * 取消输入法组合
+     */
     compositionCancel(): void;
+    /**
+     * 处理拖放事件
+     * @param evt - 拖放事件对象
+     */
     drop(evt: DragEvent): void;
+    /**
+     * 处理拖拽悬停事件
+     * @param evt - 拖拽事件对象
+     */
     dragover(evt: DragEvent | MouseEvent): void;
 }

package/dist/src/editor/core/position/Position.d.ts

@@ -2,34 +2,166 @@ import { IComputePageRowPositionPayload, IComputePageRowPositionResult, ICompute
 import { IElement, IElementPosition } from '../../interface/Element';
 import { ICurrentPosition, IGetPositionByXYPayload, IPositionContext } from '../../interface/Position';
 import { Draw } from '../draw/Draw';
+/**
+ * 位置管理类
+ *
+ * 负责管理编辑器中所有元素的位置信息，包括：
+ * - 计算和存储元素位置列表
+ * - 管理光标位置
+ * - 处理浮动元素位置
+ * - 根据鼠标坐标定位元素
+ * - 管理位置上下文（是否在表格、控件内等）
+ */
 export declare class Position {
+    /** 当前光标位置信息 */
     private cursorPosition;
+    /** 位置上下文（是否在表格、控件内等） */
     private positionContext;
+    /** 元素位置列表 */
     private positionList;
+    /** 浮动元素位置列表 */
     private floatPositionList;
+    /** Draw实例 */
     private draw;
+    /** 事件总线 */
     private eventBus;
+    /** 编辑器配置选项 */
     private options;
+    /**
+     * 创建位置管理器实例
+     * @param draw - Draw实例
+     */
     constructor(draw: Draw);
+    /**
+     * 获取浮动元素位置列表
+     * @returns 浮动元素位置数组
+     */
     getFloatPositionList(): IFloatPosition[];
+    /**
+     * 获取表格内元素位置列表
+     * @param sourceElementList - 源元素列表
+     * @returns 表格内元素位置数组
+     */
     getTablePositionList(sourceElementList: IElement[]): IElementPosition[];
+    /**
+     * 获取元素位置列表
+     * 根据当前位置上下文返回对应的位置列表
+     * @returns 元素位置数组
+     */
     getPositionList(): IElementPosition[];
+    /**
+     * 获取主区域元素位置列表
+     * @returns 主区域元素位置数组
+     */
     getMainPositionList(): IElementPosition[];
+    /**
+     * 获取原始位置列表
+     * 根据当前激活的区域返回对应的位置列表
+     * @returns 原始元素位置数组
+     */
     getOriginalPositionList(): IElementPosition[];
+    /**
+     * 获取原始主区域位置列表
+     * @returns 主区域位置数组
+     */
     getOriginalMainPositionList(): IElementPosition[];
+    /**
+     * 获取选区内的位置列表
+     * @returns 选区位置数组，如果没有选区则返回null
+     */
     getSelectionPositionList(): IElementPosition[] | null;
+    /**
+     * 设置元素位置列表
+     * @param payload - 元素位置数组
+     */
     setPositionList(payload: IElementPosition[]): void;
+    /**
+     * 设置浮动元素位置列表
+     * @param payload - 浮动元素位置数组
+     */
     setFloatPositionList(payload: IFloatPosition[]): void;
+    /**
+     * 计算页面行位置
+     *
+     * 遍历行列表，计算每个元素的坐标位置，处理行对齐、浮动元素等
+     *
+     * @param payload - 计算参数
+     * @returns 计算结果，包含最终的x、y坐标和元素索引
+     */
     computePageRowPosition(payload: IComputePageRowPositionPayload): IComputePageRowPositionResult;
+    /**
+     * 计算位置列表
+     *
+     * 清空原有位置信息，遍历每页行计算所有元素的位置坐标
+     */
     computePositionList(): void;
+    /**
+     * 计算单行位置
+     * @param payload - 计算参数，包含行信息和内部宽度
+     * @returns 元素位置数组
+     */
     computeRowPosition(payload: IComputeRowPositionPayload): IElementPosition[];
+    /**
+     * 设置光标位置
+     * @param position - 光标位置信息
+     */
     setCursorPosition(position: IElementPosition | null): void;
+    /**
+     * 获取光标位置
+     * @returns 当前光标位置信息
+     */
     getCursorPosition(): IElementPosition | null;
+    /**
+     * 获取位置上下文
+     * @returns 当前位置上下文信息
+     */
     getPositionContext(): IPositionContext;
+    /**
+     * 设置位置上下文
+     *
+     * 同时会触发positionContextChange事件
+     *
+     * @param payload - 新的位置上下文
+     */
     setPositionContext(payload: IPositionContext): void;
+    /**
+     * 根据XY坐标获取位置
+     *
+     * 遍历位置列表，找到鼠标坐标所在的元素位置
+     * 支持表格内元素、浮动元素、控件等特殊处理
+     *
+     * @param payload - 坐标参数
+     * @returns 当前位置信息
+     */
     getPositionByXY(payload: IGetPositionByXYPayload): ICurrentPosition;
+    /**
+     * 根据XY坐标获取浮动元素位置
+     *
+     * 检查给定坐标是否在浮动元素范围内
+     *
+     * @param payload - 坐标参数，包含要检查的图片显示类型
+     * @returns 如果命中浮动元素则返回位置信息
+     */
     getFloatPositionByXY(payload: IGetFloatPositionByXYPayload): ICurrentPosition | void;
+    /**
+     * 调整位置上下文
+     *
+     * 根据鼠标位置调整光标位置和位置上下文
+     * 处理控件内光标移动等特殊情况
+     *
+     * @param payload - 坐标参数
+     * @returns 调整后的位置信息
+     */
     adjustPositionContext(payload: IGetPositionByXYPayload): ICurrentPosition | null;
+    /**
+     * 设置环绕元素位置
+     *
+     * 计算环绕文字的浮动元素对当前行元素的影响
+     * 调整元素位置以避免与浮动元素重叠
+     *
+     * @param payload - 设置参数
+     * @returns 调整后的X坐标和增加的行宽
+     */
     setSurroundPosition(payload: ISetSurroundPositionPayload): {
         x: number;
         rowIncreaseWidth: number;

package/dist/src/editor/core/range/RangeManager.d.ts

@@ -2,49 +2,327 @@ import { IControlContext } from '../../interface/Control';
 import { IElement } from '../../interface/Element';
 import { IRange, IRangeElementStyle, IRangeParagraphInfo, RangeRowArray, RangeRowMap, SplitTdRange } from '../../interface/Range';
 import { Draw } from '../draw/Draw';
+/**
+ * 选区管理类
+ *
+ * 负责编辑器中文本选区的创建、管理和渲染。
+ * 选区用于表示用户选择的文本范围，支持普通文本选区、
+ * 表格单元格选区、跨行跨列选区等多种形式。
+ */
 export declare class RangeManager {
+    /** Draw实例，用于获取渲染上下文和状态 */
     private draw;
+    /** 编辑器配置选项 */
     private options;
+    /** 当前选区信息 */
     private range;
+    /** 事件监听器，用于触发回调 */
     private listener;
+    /** 事件总线，用于发布/订阅事件 */
     private eventBus;
+    /** 位置管理器，用于获取元素位置 */
     private position;
+    /** 历史管理器，用于撤销/重做功能 */
     private historyManager;
+    /** 默认样式，用于新输入的文本 */
     private defaultStyle;
+    /** 上次发射的选区样式，用于优化事件触发 */
     private lastRangeStyle;
+    /**
+     * 创建选区管理器实例
+     * @param draw - Draw实例，用于获取渲染上下文
+     */
     constructor(draw: Draw);
+    /**
+     * 比较两个选区样式是否相同
+     *
+     * 用于优化选区样式变化事件的触发，避免重复发射相同样式。
+     *
+     * @param source - 源样式对象
+     * @param target - 目标样式对象
+     * @returns 如果两个样式完全相同则返回true
+     * @private
+     */
     private _isSameRangeStyle;
+    /**
+     * 发射选区样式变化事件
+     *
+     * 当选区样式发生变化时，通知监听器和事件总线。
+     * 使用缓存机制避免重复发射相同的样式。
+     *
+     * @param rangeStyle - 当前的选区样式
+     * @private
+     */
     private _emitRangeStyle;
+    /**
+     * 获取当前选区信息
+     * @returns 当前选区对象，包含起始和结束索引
+     */
     getRange(): IRange;
+    /**
+     * 清除当前选区
+     *
+     * 将选区重置为无效状态（startIndex和endIndex都设为-1）
+     */
     clearRange(): void;
+    /**
+     * 设置默认样式
+     *
+     * 用于设置新输入文本的默认样式，如字体、大小等。
+     *
+     * @param style - 要设置的样式对象，传入null则清除默认样式
+     */
     setDefaultStyle(style: IRangeElementStyle | null): void;
+    /**
+     * 获取默认样式
+     * @returns 当前的默认样式对象，如果没有设置则返回null
+     */
     getDefaultStyle(): IRangeElementStyle | null;
+    /**
+     * 获取选区锚点元素的样式
+     *
+     * 锚点元素是选区起始位置的元素，用于确定当前样式状态。
+     *
+     * @param elementList - 元素列表
+     * @param anchorIndex - 锚点索引
+     * @returns 合并了默认样式的锚点元素，如果不存在则返回null
+     */
     getRangeAnchorStyle(elementList: IElement[], anchorIndex: number): IElement | null;
+    /**
+     * 判断选区是否发生变化
+     *
+     * 比较新选区与当前选区的所有属性，包括表格相关属性。
+     *
+     * @param startIndex - 起始索引
+     * @param endIndex - 结束索引
+     * @param tableId - 表格ID（可选）
+     * @param startTdIndex - 起始单元格索引（可选）
+     * @param endTdIndex - 结束单元格索引（可选）
+     * @param startTrIndex - 起始行索引（可选）
+     * @param endTrIndex - 结束行索引（可选）
+     * @returns 如果选区发生变化则返回true
+     */
     getIsRangeChange(startIndex: number, endIndex: number, tableId?: string, startTdIndex?: number, endTdIndex?: number, startTrIndex?: number, endTrIndex?: number): boolean;
+    /**
+     * 判断选区是否折叠
+     *
+     * 折叠选区表示光标位置（起始和结束位置相同），
+     * 未折叠选区表示用户选择了文本范围。
+     *
+     * @returns 如果选区是折叠的（起始等于结束）则返回true
+     */
     getIsCollapsed(): boolean;
+    /**
+     * 判断是否存在有效选区
+     *
+     * 检查当前是否有文本被选中（选区非空且起始不等于结束）。
+     *
+     * @returns 如果存在有效选区则返回true
+     */
     getIsSelection(): boolean;
+    /**
+     * 获取选区内的元素列表
+     *
+     * 返回当前选区范围内的所有元素，支持跨页单元格选区。
+     *
+     * @returns 选区内的元素数组，如果没有选区则返回null
+     */
     getSelection(): IElement[] | null;
+    /**
+     * 获取选区元素列表（支持跨行跨列选区）
+     *
+     * 当选区跨越表格的多行多列时，返回所有涉及的单元格内容。
+     *
+     * @returns 选区内的所有元素数组，如果跨行跨列选区则包含多个单元格的内容
+     */
     getSelectionElementList(): IElement[] | null;
+    /**
+     * 获取选区内的文本类元素
+     *
+     * 过滤选区内非文本类型的元素，只返回文本、超链接等文本类元素。
+     *
+     * @returns 文本类元素数组，如果没有则返回null
+     */
     getTextLikeSelection(): IElement[] | null;
+    /**
+     * 获取选区元素列表中的文本类元素
+     *
+     * 过滤选区元素列表中的非文本类型元素，支持跨行跨列选区。
+     *
+     * @returns 文本类元素数组，如果没有则返回null
+     */
     getTextLikeSelectionElementList(): IElement[] | null;
+    /**
+     * 获取光标所选位置的行信息
+     *
+     * 返回一个Map，键为页码，值为该页中选区涉及的行号集合。
+     *
+     * @returns 行信息的Map结构，如果没有选区则返回null
+     */
     getRangeRow(): RangeRowMap | null;
+    /**
+     * 获取光标所选位置的元素列表
+     *
+     * 返回选区所在行的所有元素，支持跨行跨列选区。
+     *
+     * @returns 选区所在行的元素数组，如果没有选区则返回null
+     */
     getRangeRowElementList(): IElement[] | null;
+    /**
+     * 获取选区段落信息
+     *
+     * 返回当前光标或选区所在段落的行信息。
+     * 会向上和向下查找，直到找到段落边界（换行符或不同列表/标题）。
+     *
+     * @returns 段落行信息的Map结构，键为页码，值为行号数组
+     */
     getRangeParagraph(): RangeRowArray | null;
+    /**
+     * 获取选区段落信息
+     *
+     * 返回段落内的所有元素及其起始位置索引，
+     * 用于段落级别的格式操作。
+     *
+     * @returns 段落信息对象，包含元素列表和起始索引
+     */
     getRangeParagraphInfo(): IRangeParagraphInfo | null;
+    /**
+     * 获取选区段落元素列表
+     *
+     * 便捷方法，直接返回段落内的所有元素。
+     *
+     * @returns 段落元素数组，如果没有则返回null
+     */
     getRangeParagraphElementList(): IElement[] | null;
+    /**
+     * 获取选区所在的表格元素
+     *
+     * 当光标在表格内时，返回对应的表格元素。
+     *
+     * @returns 表格元素，如果不在表格内则返回null
+     */
     getRangeTableElement(): IElement | null;
+    /**
+     * 判断是否全选
+     *
+     * 检查当前选区是否覆盖了整个文档内容（非表格内）。
+     *
+     * @returns 如果是全选状态则返回true
+     */
     getIsSelectAll(): boolean;
+    /**
+     * 判断指定点是否在选区范围内
+     *
+     * 用于检测鼠标位置是否在当前选区内。
+     *
+     * @param x - X坐标
+     * @param y - Y坐标
+     * @param curPageNo - 当前页码
+     * @returns 如果点在选区范围内则返回true
+     */
     getIsPointInRange(x: number, y: number, curPageNo: number): boolean;
+    /**
+     * 获取关键词的选区列表
+     *
+     * 在文档中搜索指定关键词，返回所有匹配位置的选区信息。
+     *
+     * @param payload - 要搜索的关键词
+     * @returns 匹配的选区数组
+     */
     getKeywordRangeList(payload: string): IRange[];
+    /**
+     * 判断当前位置是否可以输入
+     *
+     * 检查当前选区位置是否允许用户输入文本，
+     * 会考虑控件（如日期选择器）的限制。
+     *
+     * @returns 如果可以输入则返回true
+     */
     getIsCanInput(): boolean;
+    /**
+     * 设置选区
+     *
+     * 设置新的选区范围，支持普通文本选区和表格单元格选区。
+     * 当选区发生变化时，会重置默认样式并处理控件激活状态。
+     *
+     * @param startIndex - 起始索引
+     * @param endIndex - 结束索引
+     * @param tableId - 表格ID（可选）
+     * @param startTdIndex - 起始单元格索引（可选）
+     * @param endTdIndex - 结束单元格索引（可选）
+     * @param startTrIndex - 起始行索引（可选）
+     * @param endTrIndex - 结束行索引（可选）
+     * @param splitTdRange - 跨页单元格选区信息（可选）
+     */
     setRange(startIndex: number, endIndex: number, tableId?: string, startTdIndex?: number, endTdIndex?: number, startTrIndex?: number, endTrIndex?: number, splitTdRange?: SplitTdRange): void;
+    /**
+     * 替换选区
+     *
+     * 使用新的选区对象完全替换当前选区。
+     *
+     * @param range - 新的选区对象
+     */
     replaceRange(range: IRange): void;
+    /**
+     * 收缩选区
+     *
+     * 将选区收缩到结束位置（变成折叠状态）。
+     * 用于在删除操作后将光标移动到正确位置。
+     */
     shrinkRange(): void;
+    /**
+     * 设置并发射选区样式
+     *
+     * 根据当前选区计算样式信息，并通过监听器和事件总线通知外部。
+     * 用于更新工具栏按钮状态等场景。
+     */
     setRangeStyle(): void;
+    /**
+     * 恢复选区样式到默认值
+     *
+     * 将选区样式重置为编辑器默认值，
+     * 用于清除选区或文档为空时的样式状态。
+     */
     recoveryRangeStyle(): void;
+    /**
+     * 收缩选区边界
+     *
+     * 调整选区边界以处理控件元素的特殊情况。
+     * 当选区落在控件的占位符、前缀等位置时，
+     * 自动调整到合适的输入位置。
+     *
+     * @param context - 控件上下文，包含元素列表和选区信息
+     */
     shrinkBoundary(context?: IControlContext): void;
+    /**
+     * 渲染选区
+     *
+     * 在Canvas上绘制选区高亮矩形。
+     *
+     * @param ctx - Canvas 2D渲染上下文
+     * @param x - 矩形左上角X坐标
+     * @param y - 矩形左上角Y坐标
+     * @param width - 矩形宽度
+     * @param height - 矩形高度
+     */
     render(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number): void;
+    /**
+     * 将选区内容转换为字符串
+     *
+     * 提取选区内的文本内容，移除零宽字符。
+     *
+     * @returns 选区内的纯文本内容
+     */
     toString(): string;
+    /**
+     * 获取选区元素信息
+     *
+     * 根据上下文返回正确的元素列表和选区信息，
+     * 支持跨页单元格选区的特殊处理。
+     *
+     * @param context - 控件上下文，可指定元素列表和选区
+     * @returns 包含元素列表和选区信息的对象
+     */
     getRangeElement(context?: IControlContext): {
         elementList: IElement[];
         range: {