docs: README／ARCHITECTURE 同步階段一／二——設置速查表＋三分類分層＋avoid 七源＋修正過時
goal 2 文檔重整（main 部分）。反映階段一／二之行為與契約變更，並修審計發現之過時內容。 README： ・新增「全部選項速查」表——突出被埋沒之強力設置（lang.style／styleInlines／blockTags／ skipTags 之標籤名陣列、skipAttribute／isSkipped 函數鉤子）＋ HTML 屬性一覽；標明「標籤名 陣列」與「CSS 選擇器」兩機制之別。 ・選項示例補 lang.style；三分類「共用同一判定」改分層表述（邏輯流共用 isTransparent、未知 行內＝嚴格白名單邊界、canSplit／lineedge 為獨立層）；avoid 要點改七源＋isAvoided 組合入口＋ skipTags 不含 CODE/KBD 之三分類互斥說明。 ARCHITECTURE： ・§3.1 scope.avoid 過時示例修正（無默認、與內建 skipTags 並存，非「追加於內建 avoid」）。 ・§4.1 avoid 內建名單去 code/kbd、改七源表述；「共用同一判定」改分層（isTransparent 為邏輯流 單一真相源＋嚴格白名單；canSplit／lineedge 兩層正當不同、不硬併，含 lineedge 須跨 isolate 之 物理測量理由）；transparentInline→isTransparent、avoidsSelf／isAvoided 組合入口。 ・§4.2 標點六子類修正（bd-stop／pause／open／close／middle／liga——舊列 bd-cop／bd-sep／quote 與實作不符）。
This commit is contained in:
@@ -84,7 +84,8 @@ jz.render(document.querySelector("main"));
|
||||
createJuzhen({
|
||||
lang: {
|
||||
default: "zh-Hant", // 無 lang 祖先時之預設
|
||||
policy: { "zh-Hant": "quanjiao", "zh-Hans": "kaiming" }, // 全角／開明／半角
|
||||
style: "kaiming", // 全域政策一鍵覆寫（quanjiao｜kaiming｜banjiao）
|
||||
policy: { "zh-Hant": "quanjiao", "zh-Hans": "kaiming" }, // 逐 lang（最高優先）
|
||||
},
|
||||
scope: {
|
||||
root: document.body, // 處理根；render(root) 可逐次覆寫
|
||||
@@ -108,14 +109,78 @@ createJuzhen({
|
||||
});
|
||||
```
|
||||
|
||||
### 全部選項速查（含少見但強力者）
|
||||
|
||||
完整選項一覽。**「標籤名」型別只吃大寫標籤名陣列**（精確比對 `nodeName`），與
|
||||
`pillSelector`／`isolateSelector`／`scope.*`（**CSS 選擇器**，可用 class／屬性）**不同機制**，
|
||||
勿混。斜體「詳見」指向本文檔展開該項之小節。
|
||||
|
||||
**語言與擠壓政策**（優先序：`policy` ＞ `style` ＞ 逐語言內建）
|
||||
|
||||
| 選項 | 型別 | 預設 | 作用 |
|
||||
|---|---|---|---|
|
||||
| `lang.default` | string | `"zh-Hant"` | 無 `lang` 祖先時之預設語言標籤 |
|
||||
| `lang.style` | `quanjiao｜kaiming｜banjiao` | 逐語言內建（繁→全角、簡→開明） | **全域政策一鍵覆寫** |
|
||||
| `lang.policy` | `Record<lang, style>` | `{}` | 逐 lang 政策（最高優先） |
|
||||
|
||||
**作用域**
|
||||
|
||||
| 選項 | 型別 | 預設 | 作用 |
|
||||
|---|---|---|---|
|
||||
| `scope.root` | Element｜選擇器 | `document.body` | 處理根（`render(root)` 可逐次覆寫） |
|
||||
| `scope.include` | 選擇器 | `null` | opt-in：僅處理命中此選擇器之子樹 |
|
||||
| `scope.avoid` | 選擇器 | `null` | 追加排除子樹 |
|
||||
|
||||
**功能開關 / 對齊 / 分級 / 分塊**（詳見「已實作功能」表及各節）
|
||||
|
||||
| 選項 | 型別 | 預設 | 作用 |
|
||||
|---|---|---|---|
|
||||
| `spacing` | bool | `true` | 中西間隙 |
|
||||
| `longWord` | bool｜`{minLength,lang}` | `true`（`{6,"en"}`） | 長英文詞斷字 |
|
||||
| `jiya` | bool｜`{halfWidth,bias}` | `true` | 標點擠壓（*詳見「標點半形」*） |
|
||||
| `jinze` | bool | `true` | 禁則避頭尾 |
|
||||
| `orphan` | bool｜`{chars}` | `true`（`{chars:2}`） | 垂懸字避免 |
|
||||
| `justifyAtoms` | bool | `true` | inline-block 對齊原子（分頁器設 `false`） |
|
||||
| `level.text` | 選擇器 | `null` | 命中子樹僅跑文本級（*詳見「功能分級」*） |
|
||||
| `blocks` | `{selector,features}[]` | `[]` | 分塊功能選擇 |
|
||||
| `charClass` | `{cjk,western,biaodian}` | — | 追加字符分類（*詳見「自定義字符分類」*） |
|
||||
|
||||
**行內三分類與排除**（*詳見「行內元素三分類」*）
|
||||
|
||||
| 選項 | 型別 | 預設 | 作用 |
|
||||
|---|---|---|---|
|
||||
| `pillSelector` | CSS 選擇器 | `"code, kbd"` | 整體元素（內部不可見、兩端補隙） |
|
||||
| `isolateSelector` | CSS 選擇器 | `"mark"`（`""` 停用） | 隔離元素（內部照常、兩端補隙） |
|
||||
| `styleInlines` | 標籤名[] | 27 個標準行內標籤 | **透明穿越白名單**（未列之行內標籤＝邊界） |
|
||||
| `blockTags` | 標籤名[] | 36 個塊標籤 | 塊級邊界集 |
|
||||
| `skipTags` | 標籤名[] | `PRE,SAMP,TT,VAR,SCRIPT,STYLE,TEXTAREA,INPUT` | avoid 標籤集（**不含 CODE/KBD**，由 pill 涵蓋） |
|
||||
| `skipAttribute` | string | `null` | 自訂「跳過」屬性名（命中即 avoid） |
|
||||
| `isSkipped` | `(node)=>bool` | `null` | 自訂跳過謂詞（函數級排除鉤子） |
|
||||
|
||||
**HTML 屬性**（就近繼承，最近祖先勝）
|
||||
|
||||
| 屬性 | 值 | 作用 |
|
||||
|---|---|---|
|
||||
| `data-jz-level` | `text｜paragraph` | 逐子樹功能分級 |
|
||||
| `data-juzhen` | 功能名（空格分隔） | 白名單：僅列出之功能生效 |
|
||||
| `data-juzhen-off` | 功能名 | 黑名單：停用列出之功能 |
|
||||
| `data-jz-skip` | （存在即可） | 標記元素為 avoid（內外皆不處理） |
|
||||
| `data-jz-halfwidth` | `halt｜margin` | 逐子樹半形渲染模式 |
|
||||
|
||||
**預留、當前無效果**：`hanging`（已移除，見下）；`biaodian`／`emphasis`／`ruby`（架構預留切片
|
||||
#7／#8）。注意頂層 `biaodian`（功能開關）與 `charClass.biaodian`（標點子類擴充表）**同名異義**。
|
||||
|
||||
### 行內元素三分類：透明／隔離／整體
|
||||
|
||||
行內元素對排版有且僅有三種口徑，**所有遍歷原語共用同一判定**（中西間隙、擠壓相鄰、
|
||||
禁則綁定、垂懸字、克隆切分皆一致）：
|
||||
行內元素對排版有且僅有三種口徑。**邏輯文本流之遍歷原語**（中西間隙、擠壓相鄰、禁則綁定、
|
||||
垂懸字）**共用同一判定** `isTransparent`；未在 `styleInlines` 之**未知行內標籤**（自訂元素／
|
||||
web component 等）採**嚴格白名單**、一律當**邊界**（語義同隔離、內部自成脈絡），透明須顯式
|
||||
登記 `styleInlines`。（另兩層各有其正當之邊界、刻意不併入：結構克隆切分之安全白名單
|
||||
`canSplit`、行端物理版面測量 `lineedge`，詳見 `ARCHITECTURE.md`。）
|
||||
|
||||
| 分類 | 選擇器 | 邊界 | 內部 | 典型 |
|
||||
|---|---|---|---|---|
|
||||
| **透明** | `styleInlines`（預設常見樣式標籤） | 穿越——間隙／相鄰／run 皆延續 | 照常處理；禁則可**克隆切分**（最小綁定） | `strong`／`em`／`b`／`i`／`a`／`span` |
|
||||
| **透明** | `styleInlines`（預設 27 個常見樣式標籤；**未列之行內標籤＝邊界**） | 穿越——間隙／相鄰／run 皆延續 | 照常處理；禁則可**克隆切分**（最小綁定） | `strong`／`em`／`b`／`i`／`a`／`span`（自訂元素須自行登記） |
|
||||
| **隔離** | `isolateSelector`（預設 `"mark"`） | 斷 run／斷相鄰／不可切分；**兩端**與 CJK／西文相鄰時補 `jz-hws` 間隙 | **照常處理**（自成脈絡：內部標點照擠、內部中西照補隙） | 帶背景色之 `<mark>`、badge 類盒樣式行內 |
|
||||
| **整體** | `pillSelector`（預設 `"code, kbd"`） | 同隔離（邊界斷、兩端補隙） | **完全不可見**——不 charify、不插間隙、不切分、不下潛 | `code`／`kbd`、行內公式 `.katex`、引用標 `.cite-ref` |
|
||||
|
||||
@@ -127,8 +192,12 @@ createJuzhen({
|
||||
同一段邊界處理代碼），差異僅在內部；同一元素同時命中兩選擇器時 **pill 勝出**（內部不可見）。
|
||||
- **禁則之整體綁定**：pill 緊鄰禁則標點時（`…$公式$，`），整個 pill 作為原子鄰字單位
|
||||
綁入 `jz-jinze`（公式本不可斷，無額外代價）；隔離元素同樣整綁（切分背景盒有可見接縫）。
|
||||
- **`scope.avoid`／`skipAttribute`／`data-jz-skip` 以自身判定**：命中元素自身即邊界、
|
||||
內外皆不處理（舊版僅查祖先，元素自身命中時仍被穿越）。
|
||||
- **avoid（排除）之七種來源**，任一命中即邊界、內外皆不處理：`isSkipped` 謂詞／`skipTags`
|
||||
標籤集／SVG／`contentEditable`／`data-jz-skip` 屬性／`skipAttribute`（自訂屬性名）／
|
||||
`scope.avoid` 選擇器。**以自身判定**（元素自身命中即是，非僅查祖先）；一次性檢查用
|
||||
`isAvoided`（自身或祖先之組合判定）。**`skipTags` 預設不含 `CODE`／`KBD`**——二者已由
|
||||
`pillSelector` 以 pill 涵蓋（三分類互斥；若把 `code` 移出 `pillSelector`，須自行加入
|
||||
`skipTags`／`scope.avoid`，否則其內部將被當普通文本處理）。
|
||||
- **行內公式／夾注引用宜列為 pill**：`pillSelector: "code, kbd, .katex, .cite-ref"`——
|
||||
獨立行內單位以 pill 邊界邏輯統一處理（兩側補隙、吸收作者空格、整體綁定）。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user