admin
a0c66ecadc
把 [A-Za-z]{N,} 之長英文段包進 <span lang="en">，配合消費端 CSS
[lang|="en"] { hyphens: auto; ... } 用瀏覽器原生 en 字典斷詞 + 渲
染連字符。連字符純由 CSS 渲染，DOM 內不存在 → 選取 / 複製返回原文
無污染。冪等：parent 為 <span lang> 直接跳過。
skip 鏈共用 Pass A / B 之 isSkipped（CODE / KBD / PRE / SAMP / TT
/ VAR / SCRIPT / STYLE / TEXTAREA / INPUT / SVG / contentEditable
/ data-md-key）。
預設啟用以解 CJK 兩端對齊正文中行末長英文詞之斷行問題；消費端可傳
longWordWrap: false 顯式關閉，或 { minLength, lang } 自訂粒度與標
語。
README + .d.ts 同步說明，含字型陷阱（CJK serif 把 U+2010 設為全形）
與消費端 CSS 範本（含 hyphenate-character: "-"）。
74 lines
2.4 KiB
TypeScript
74 lines
2.4 KiB
TypeScript
/**
|
||
* cjk-autospace — CJK ↔ Latin 邊界自動間距 shim（Pangu.js v7.2.1 風格）。
|
||
*
|
||
* 用法：
|
||
* ```ts
|
||
* import { createCjkAutospace } from "./cjk-autospace.js";
|
||
*
|
||
* const autospace = createCjkAutospace({
|
||
* pillSelector: "code, kbd, .cjk-pill",
|
||
* });
|
||
* autospace.apply(document.body);
|
||
* ```
|
||
*/
|
||
|
||
export interface CjkAutospaceOptions {
|
||
/** 行內塊（PILL）選擇器。預設 `"code, kbd"`。 */
|
||
pillSelector?: string;
|
||
|
||
/** 樣式標籤集合（shim 透明走過）。tagName 用大寫。 */
|
||
styleInlines?: readonly string[];
|
||
|
||
/** 段落級標籤集合（Pass A run 邊界）。tagName 用大寫。 */
|
||
blockTags?: readonly string[];
|
||
|
||
/** Skip-ancestor 標籤集合（subtree 整個跳過）。tagName 用大寫。 */
|
||
skipTags?: readonly string[];
|
||
|
||
/** Marker span 之 class 名。預設 `"cjk-autospace"`。 */
|
||
autospaceClass?: string;
|
||
|
||
/** Skip-ancestor 額外屬性檢查（任一祖先帶此屬性則 skip）。預設 `"data-md-key"`。 */
|
||
skipAttribute?: string;
|
||
|
||
/** 自訂 skip 判定（在內建判定前先檢查）。回傳 true 表示應跳過。 */
|
||
isSkipped?: (node: Node) => boolean;
|
||
|
||
/**
|
||
* Pass C（**預設啟用**）：把 `[A-Za-z]{minLength,}` 之長英文段包進
|
||
* `<span lang="…">`，讓瀏覽器原生 `hyphens: auto` 可斷詞並渲染連字
|
||
* 符（連字符純由 CSS 渲染，DOM 內不存在 → 複製不污染原文）。需消費
|
||
* 端 CSS 配：
|
||
*
|
||
* ```css
|
||
* [lang|="en"] {
|
||
* hyphens: auto;
|
||
* -webkit-hyphens: auto;
|
||
* hyphenate-limit-chars: 6 3 3; // 詞長 / 斷點前 / 斷點後最少字符
|
||
* }
|
||
* ```
|
||
*
|
||
* 傳 `false` 顯式關閉；`true` 或省略等同 `{ minLength: 6, lang: "en" }`。
|
||
*/
|
||
longWordWrap?: boolean | {
|
||
/** 觸發包裝之最短字母串長度。預設 6。 */
|
||
minLength?: number;
|
||
/** 包裝 span 之 `lang` 屬性值。預設 `"en"`。 */
|
||
lang?: string;
|
||
};
|
||
}
|
||
|
||
export interface CjkAutospaceInstance {
|
||
/**
|
||
* 對指定 root（預設 `document.body`）套用 Pass A + Pass B。
|
||
* 在已注入 marker 之 DOM 上重跑為冪等（會跳過既有 `.cjk-autospace`）。
|
||
*/
|
||
apply(root?: ParentNode | Document): void;
|
||
}
|
||
|
||
export function createCjkAutospace(options?: CjkAutospaceOptions): CjkAutospaceInstance;
|
||
|
||
declare global {
|
||
var createCjkAutospace: typeof createCjkAutospace;
|
||
}
|