@tdh-keyboard/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,269 @@
+//#region src/canvas.d.ts
+interface CanvasDrawerOptions {
+  onDrawEnd?: () => void;
+  clearDelay?: number;
+}
+declare class CanvasDrawer {
+  private canvas;
+  private ctx;
+  private lastX;
+  private lastY;
+  private strokeData;
+  private clearTimerId;
+  private isDrawing;
+  private options;
+  constructor(canvas: HTMLCanvasElement, options?: CanvasDrawerOptions);
+  private setupCanvas;
+  drawGrid(): void;
+  clearCanvas(): void;
+  startDrawing(offsetX: number, offsetY: number): void;
+  draw(offsetX: number, offsetY: number): void;
+  endStroke(): void;
+  getStrokeData(): ReadonlyArray<number>;
+  resetClearTimer(): void;
+  startClearTimer(): void;
+  private getEventCoordinates;
+  private handleStart;
+  private handleMove;
+  private handleEnd;
+  private attachEvents;
+  private detachEvents;
+  destroy(): void;
+  getCanvas(): HTMLCanvasElement;
+  getContext(): CanvasRenderingContext2D;
+}
+//#endregion
+//#region src/handwriting.d.ts
+interface RecognizerInitOptions {
+  /**
+   * 初始化进度回调函数
+   * @param progress 进度范围为0到1，表示初始化的完成度
+   * @returns void
+   */
+  onProgress?: (progress: number) => void;
+}
+/**
+ * 手写识别器接口
+ * 用于实现手写汉字识别功能
+ */
+interface HandwritingRecognizer {
+  /**
+   * 初始化手写识别服务
+   * @returns 返回是否初始化成功
+   */
+  initialize(options?: RecognizerInitOptions): Promise<boolean>;
+  /**
+   * 识别手写笔迹
+   * @param strokeData 笔迹数据，格式为 x y c x y c ...，其中x和y是坐标，c表示是否为笔画的最后一点(1表示是，0表示否)
+   * @returns 识别结果列表
+   */
+  recognize(strokeData: number[]): Promise<string[]>;
+  /**
+   * 关闭手写识别服务
+   */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/pinyin-engine.d.ts
+interface Candidate {
+  text: string;
+  comment: string;
+}
+interface PinyinState {
+  /** 已提交（最终）文本；若无提交则为 null。 */
+  committed: string | null;
+  /** 选区前的预编辑文本。 */
+  preeditHead: string;
+  /** 当前被选中的预编辑部分。 */
+  preeditBody: string;
+  /** 选区后的预编辑文本。 */
+  preeditTail: string;
+  /** 预编辑中的光标位置。 */
+  cursorPos: number;
+  /** 当前页的候选项列表。 */
+  candidates: Candidate[];
+  /** 当前页码（从 0 开始）。 */
+  pageNo: number;
+  /** 是否为候选的最后一页。 */
+  isLastPage: boolean;
+  /** 高亮候选的索引。 */
+  highlightedIndex: number;
+  /** 候选选择键的标签数组。 */
+  selectLabels: string[];
+}
+/**
+ * 拼音引擎通用接口
+ * 所有拼音引擎实现必须遵循此接口
+ */
+interface PinyinEngine {
+  /**
+   * 初始化引擎，加载必要资源
+   */
+  initialize(): Promise<void>;
+  /**
+   * 处理完整的拼音输入串，返回所有候选词列表（跨所有页）。
+   * 引擎内部负责增量 vs 重置的优化，调用方只传完整拼音。
+   * @param pinyin 完整的拼音字符串
+   * @returns 候选词状态，包括所有页的候选词集合和分页信息
+   */
+  processInput(pinyin: string): Promise<PinyinState | null>;
+  /**
+   * 按全局索引选择候选词，返回已提交的文本。
+   * @param index 候选词在全量列表中的全局索引（从0开始）
+   * @returns 候选词状态，包括所有页的候选词集合和分页信息
+   */
+  pickCandidate(index: number): Promise<PinyinState>;
+  /**
+   * 清除引擎当前的预编辑输入状态
+   */
+  clearInput(): Promise<void>;
+  /**
+   * 切换简体/繁体输出（可选，引擎不支持时忽略）
+   * @param simplified true 为简体，false 为繁体
+   */
+  setSimplified?(simplified: boolean): Promise<void>;
+  /**
+   * 销毁引擎，释放所有持有的资源
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * 键盘配置类型
+ */
+interface KeyboardConfig {
+  /**
+   * 默认的键盘模式
+   */
+  defaultMode?: 'en' | 'zh' | 'hand' | 'num' | 'symbol';
+  /**
+   * 是否启用手写输入
+   */
+  enableHandwriting?: boolean;
+  /**
+   * 键盘定位模式
+   */
+  position?: 'static' | 'float' | 'bottom';
+  /**
+   * 浮动模式下键盘与输入框的距离
+   * @default 10
+   */
+  floatMarginTop?: number;
+  /**
+   * 当没有input获得焦点时是否禁用键盘
+   */
+  disableWhenNoFocus?: boolean;
+  /**
+   * 是否启用手动打开模式
+   * 启用后不再根据焦点自动显示，需要通过实例方法手动调用 open / close / destroy。
+   */
+  manual?: boolean;
+  /**
+   * 数字键盘的行配置
+   */
+  numKeys?: string[][];
+  /**
+   * RIME WASM 文件及数据文件的 URL 或路径前缀。
+   * 用于默认 RIME 引擎加载（当未通过 registerPinyinEngine 注册自定义引擎时）。
+   * @default '/rime'
+   */
+  wasmDir?: string;
+}
+/**
+ * 获取全局键盘配置
+ */
+declare function getKeyboardConfig(): KeyboardConfig;
+/**
+ * 设置全局键盘配置
+ */
+declare function setKeyboardConfig(config: KeyboardConfig): void;
+/**
+ * 注册手写识别服务
+ * @param recognizer 手写识别服务实现
+ */
+declare function registerHandwritingRecognizer(recognizer: HandwritingRecognizer): void;
+/**
+ * 获取手写识别服务实例
+ * @returns 手写识别服务实例
+ */
+declare function getHandwritingRecognizer(): HandwritingRecognizer | null;
+/**
+ * 注册拼音引擎。
+ * 注册后，CandidateBar 将使用此引擎而非默认的 RIME 引擎。
+ * 适用于自定义引擎或 Worker 中运行的引擎。
+ * @param engine 拼音引擎实现
+ */
+declare function registerPinyinEngine(engine: PinyinEngine): void;
+/**
+ * 获取已注册的拼音引擎实例
+ * @returns 拼音引擎实例，未注册时返回 null
+ */
+declare function getPinyinEngine(): PinyinEngine | null;
+//#endregion
+//#region src/dom.d.ts
+interface KeyboardPosition {
+  top: string;
+  left: string;
+}
+/**
+ * 计算键盘的显示位置
+ * @param inputElement 输入框元素
+ * @param keyboardElement 键盘元素
+ * @param positionMode 位置模式：'static'（静态，不计算位置）、'float'（浮动，根据输入框位置计算）、'bottom'（固定在底部）
+ * @returns 返回键盘的 top 和 left 位置，如果不需要计算则返回 null
+ */
+declare function calculateKeyboardPosition(inputElement: HTMLElement | null, keyboardElement: HTMLElement | null, positionMode: 'static' | 'float' | 'bottom', floatMarginTop?: number): KeyboardPosition | null;
+//#endregion
+//#region src/input.d.ts
+type TextInputElement = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * 判断元素是否为可输入元素（支持文本输入的 input 或 textarea）
+ * @param el 要检测的元素
+ * @returns 如果是可输入元素则返回 true
+ */
+declare function isInputElement(el?: Element | null): el is TextInputElement;
+/**
+ * 获取当前激活的输入元素
+ * @throws {Error} 如果当前没有激活的输入框
+ */
+declare function getInputElement(): TextInputElement;
+/**
+ * 向输入框插入文本
+ * @param inputElement 输入框元素
+ * @param text 要插入的文本
+ */
+declare function writeToInputElement(inputElement: TextInputElement, text: string): void;
+/**
+ * 向输入框删除文本
+ * @param inputElement 输入框元素
+ */
+declare function delToInputElement(inputElement: TextInputElement): void;
+/**
+ * 设置输入框光标位置
+ * @param inputElement 输入框元素
+ * @param index 光标位置索引
+ */
+declare function moveCursor(inputElement: TextInputElement, index: number): void;
+//#endregion
+//#region src/repeat.d.ts
+interface KeyRepeatOptions {
+  /** Long-press delay before repeating starts (ms). */
+  delay?: number;
+  /** Repeat interval after the initial delay (ms). */
+  interval?: number;
+}
+interface KeyRepeater {
+  start: (action: () => void) => void;
+  stop: () => void;
+}
+/**
+ * Create a small, framework-agnostic key repeater for long-press.
+ *
+ * - Calls `action()` immediately on start.
+ * - After `delay`, repeats with `interval` until `stop()` is called.
+ */
+declare function createKeyRepeater(options?: KeyRepeatOptions): KeyRepeater;
+//#endregion
+export { Candidate, CanvasDrawer, CanvasDrawerOptions, HandwritingRecognizer, KeyRepeatOptions, KeyRepeater, KeyboardConfig, KeyboardPosition, PinyinEngine, PinyinState, RecognizerInitOptions, TextInputElement, calculateKeyboardPosition, createKeyRepeater, delToInputElement, getHandwritingRecognizer, getInputElement, getKeyboardConfig, getPinyinEngine, isInputElement, moveCursor, registerHandwritingRecognizer, registerPinyinEngine, setKeyboardConfig, writeToInputElement };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,269 @@
+//#region src/canvas.d.ts
+interface CanvasDrawerOptions {
+  onDrawEnd?: () => void;
+  clearDelay?: number;
+}
+declare class CanvasDrawer {
+  private canvas;
+  private ctx;
+  private lastX;
+  private lastY;
+  private strokeData;
+  private clearTimerId;
+  private isDrawing;
+  private options;
+  constructor(canvas: HTMLCanvasElement, options?: CanvasDrawerOptions);
+  private setupCanvas;
+  drawGrid(): void;
+  clearCanvas(): void;
+  startDrawing(offsetX: number, offsetY: number): void;
+  draw(offsetX: number, offsetY: number): void;
+  endStroke(): void;
+  getStrokeData(): ReadonlyArray<number>;
+  resetClearTimer(): void;
+  startClearTimer(): void;
+  private getEventCoordinates;
+  private handleStart;
+  private handleMove;
+  private handleEnd;
+  private attachEvents;
+  private detachEvents;
+  destroy(): void;
+  getCanvas(): HTMLCanvasElement;
+  getContext(): CanvasRenderingContext2D;
+}
+//#endregion
+//#region src/handwriting.d.ts
+interface RecognizerInitOptions {
+  /**
+   * 初始化进度回调函数
+   * @param progress 进度范围为0到1，表示初始化的完成度
+   * @returns void
+   */
+  onProgress?: (progress: number) => void;
+}
+/**
+ * 手写识别器接口
+ * 用于实现手写汉字识别功能
+ */
+interface HandwritingRecognizer {
+  /**
+   * 初始化手写识别服务
+   * @returns 返回是否初始化成功
+   */
+  initialize(options?: RecognizerInitOptions): Promise<boolean>;
+  /**
+   * 识别手写笔迹
+   * @param strokeData 笔迹数据，格式为 x y c x y c ...，其中x和y是坐标，c表示是否为笔画的最后一点(1表示是，0表示否)
+   * @returns 识别结果列表
+   */
+  recognize(strokeData: number[]): Promise<string[]>;
+  /**
+   * 关闭手写识别服务
+   */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/pinyin-engine.d.ts
+interface Candidate {
+  text: string;
+  comment: string;
+}
+interface PinyinState {
+  /** 已提交（最终）文本；若无提交则为 null。 */
+  committed: string | null;
+  /** 选区前的预编辑文本。 */
+  preeditHead: string;
+  /** 当前被选中的预编辑部分。 */
+  preeditBody: string;
+  /** 选区后的预编辑文本。 */
+  preeditTail: string;
+  /** 预编辑中的光标位置。 */
+  cursorPos: number;
+  /** 当前页的候选项列表。 */
+  candidates: Candidate[];
+  /** 当前页码（从 0 开始）。 */
+  pageNo: number;
+  /** 是否为候选的最后一页。 */
+  isLastPage: boolean;
+  /** 高亮候选的索引。 */
+  highlightedIndex: number;
+  /** 候选选择键的标签数组。 */
+  selectLabels: string[];
+}
+/**
+ * 拼音引擎通用接口
+ * 所有拼音引擎实现必须遵循此接口
+ */
+interface PinyinEngine {
+  /**
+   * 初始化引擎，加载必要资源
+   */
+  initialize(): Promise<void>;
+  /**
+   * 处理完整的拼音输入串，返回所有候选词列表（跨所有页）。
+   * 引擎内部负责增量 vs 重置的优化，调用方只传完整拼音。
+   * @param pinyin 完整的拼音字符串
+   * @returns 候选词状态，包括所有页的候选词集合和分页信息
+   */
+  processInput(pinyin: string): Promise<PinyinState | null>;
+  /**
+   * 按全局索引选择候选词，返回已提交的文本。
+   * @param index 候选词在全量列表中的全局索引（从0开始）
+   * @returns 候选词状态，包括所有页的候选词集合和分页信息
+   */
+  pickCandidate(index: number): Promise<PinyinState>;
+  /**
+   * 清除引擎当前的预编辑输入状态
+   */
+  clearInput(): Promise<void>;
+  /**
+   * 切换简体/繁体输出（可选，引擎不支持时忽略）
+   * @param simplified true 为简体，false 为繁体
+   */
+  setSimplified?(simplified: boolean): Promise<void>;
+  /**
+   * 销毁引擎，释放所有持有的资源
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * 键盘配置类型
+ */
+interface KeyboardConfig {
+  /**
+   * 默认的键盘模式
+   */
+  defaultMode?: 'en' | 'zh' | 'hand' | 'num' | 'symbol';
+  /**
+   * 是否启用手写输入
+   */
+  enableHandwriting?: boolean;
+  /**
+   * 键盘定位模式
+   */
+  position?: 'static' | 'float' | 'bottom';
+  /**
+   * 浮动模式下键盘与输入框的距离
+   * @default 10
+   */
+  floatMarginTop?: number;
+  /**
+   * 当没有input获得焦点时是否禁用键盘
+   */
+  disableWhenNoFocus?: boolean;
+  /**
+   * 是否启用手动打开模式
+   * 启用后不再根据焦点自动显示，需要通过实例方法手动调用 open / close / destroy。
+   */
+  manual?: boolean;
+  /**
+   * 数字键盘的行配置
+   */
+  numKeys?: string[][];
+  /**
+   * RIME WASM 文件及数据文件的 URL 或路径前缀。
+   * 用于默认 RIME 引擎加载（当未通过 registerPinyinEngine 注册自定义引擎时）。
+   * @default '/rime'
+   */
+  wasmDir?: string;
+}
+/**
+ * 获取全局键盘配置
+ */
+declare function getKeyboardConfig(): KeyboardConfig;
+/**
+ * 设置全局键盘配置
+ */
+declare function setKeyboardConfig(config: KeyboardConfig): void;
+/**
+ * 注册手写识别服务
+ * @param recognizer 手写识别服务实现
+ */
+declare function registerHandwritingRecognizer(recognizer: HandwritingRecognizer): void;
+/**
+ * 获取手写识别服务实例
+ * @returns 手写识别服务实例
+ */
+declare function getHandwritingRecognizer(): HandwritingRecognizer | null;
+/**
+ * 注册拼音引擎。
+ * 注册后，CandidateBar 将使用此引擎而非默认的 RIME 引擎。
+ * 适用于自定义引擎或 Worker 中运行的引擎。
+ * @param engine 拼音引擎实现
+ */
+declare function registerPinyinEngine(engine: PinyinEngine): void;
+/**
+ * 获取已注册的拼音引擎实例
+ * @returns 拼音引擎实例，未注册时返回 null
+ */
+declare function getPinyinEngine(): PinyinEngine | null;
+//#endregion
+//#region src/dom.d.ts
+interface KeyboardPosition {
+  top: string;
+  left: string;
+}
+/**
+ * 计算键盘的显示位置
+ * @param inputElement 输入框元素
+ * @param keyboardElement 键盘元素
+ * @param positionMode 位置模式：'static'（静态，不计算位置）、'float'（浮动，根据输入框位置计算）、'bottom'（固定在底部）
+ * @returns 返回键盘的 top 和 left 位置，如果不需要计算则返回 null
+ */
+declare function calculateKeyboardPosition(inputElement: HTMLElement | null, keyboardElement: HTMLElement | null, positionMode: 'static' | 'float' | 'bottom', floatMarginTop?: number): KeyboardPosition | null;
+//#endregion
+//#region src/input.d.ts
+type TextInputElement = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * 判断元素是否为可输入元素（支持文本输入的 input 或 textarea）
+ * @param el 要检测的元素
+ * @returns 如果是可输入元素则返回 true
+ */
+declare function isInputElement(el?: Element | null): el is TextInputElement;
+/**
+ * 获取当前激活的输入元素
+ * @throws {Error} 如果当前没有激活的输入框
+ */
+declare function getInputElement(): TextInputElement;
+/**
+ * 向输入框插入文本
+ * @param inputElement 输入框元素
+ * @param text 要插入的文本
+ */
+declare function writeToInputElement(inputElement: TextInputElement, text: string): void;
+/**
+ * 向输入框删除文本
+ * @param inputElement 输入框元素
+ */
+declare function delToInputElement(inputElement: TextInputElement): void;
+/**
+ * 设置输入框光标位置
+ * @param inputElement 输入框元素
+ * @param index 光标位置索引
+ */
+declare function moveCursor(inputElement: TextInputElement, index: number): void;
+//#endregion
+//#region src/repeat.d.ts
+interface KeyRepeatOptions {
+  /** Long-press delay before repeating starts (ms). */
+  delay?: number;
+  /** Repeat interval after the initial delay (ms). */
+  interval?: number;
+}
+interface KeyRepeater {
+  start: (action: () => void) => void;
+  stop: () => void;
+}
+/**
+ * Create a small, framework-agnostic key repeater for long-press.
+ *
+ * - Calls `action()` immediately on start.
+ * - After `delay`, repeats with `interval` until `stop()` is called.
+ */
+declare function createKeyRepeater(options?: KeyRepeatOptions): KeyRepeater;
+//#endregion
+export { Candidate, CanvasDrawer, CanvasDrawerOptions, HandwritingRecognizer, KeyRepeatOptions, KeyRepeater, KeyboardConfig, KeyboardPosition, PinyinEngine, PinyinState, RecognizerInitOptions, TextInputElement, calculateKeyboardPosition, createKeyRepeater, delToInputElement, getHandwritingRecognizer, getInputElement, getKeyboardConfig, getPinyinEngine, isInputElement, moveCursor, registerHandwritingRecognizer, registerPinyinEngine, setKeyboardConfig, writeToInputElement };
+//# sourceMappingURL=index.d.mts.map