docs: 效能/增量 API 文檔+I1/I6 收緊(作者空格規範化不還原)
README:新增「動態頁面:增量恢復」(rerender/invalidate/observe/disconnect 用法+元素變化正確性 告示);新增「revert 之範圍」注(revert 淨移除 jz-* 結構、回邏輯等價態,但不還原 spacing 依契約 規範化之贅餘作者空格;需保留原始源者勿以 revert 當「還原到未處理源碼」)。 ARCHITECTURE:§3.1 增量 API;§4.1 記憶化(category+祖先游走)與快取生命週期/失效;§6.1a S1 對齊門。**I1/I6 收緊**(消除與固有 strip 行為之措辭張力,方案 A): - I1 明示 spacing 規範化贅餘作者空格為刻意之常態例外(語義不變、但確刪空格且不經 revert 還原), 除此之外預設「只包裝、不改寫文字」。 - I6 明示 revert 淨移除全部 jz-* 結構、回「邏輯等價」態;「邏輯等價≠逐字節」之唯一差異即被規範化 之作者空格(穩定、不隨反覆 render/revert 累積;revert 後無 [data-jz] 殘留)。 依據:4 份真人撰寫真實文檔驗收——非空白字元多重集守恆、無字元改/增/漏/亂序,唯贅餘作者空格依 契約規範化(doc-A 55、B 31、C 0、D 85 個);真瀏覽器整條管線(含 lineEdge/gapTrim)零報錯。
This commit is contained in:
@@ -59,6 +59,44 @@ jz.render(document.querySelector("main"));
|
||||
**JS 與 CSS 缺一不可**:JS 只注入 `jz-*` 結構,所有視覺尺寸(間隙寬度、擠壓量、
|
||||
`justify` 原子化、字體堆疊)都在 `juzhen.css`。
|
||||
|
||||
### 動態頁面:增量恢復(局部變化免全樹重掃)
|
||||
|
||||
`render(root)`/`revert(root)` **皆可傳入局部 Element**——頁面局部變化時,只重處理受影響
|
||||
之子樹即可,成本 O(該塊) 而非 O(全文)(實測編輯 400 段中之一段,局部恢復較全樹快數百倍)。
|
||||
|
||||
```ts
|
||||
const jz = createJuzhen();
|
||||
jz.render(document.body); // 初次全樹
|
||||
|
||||
// 局部變化後(手動):
|
||||
jz.rerender(changedBlock); // = revert(changedBlock) + render(changedBlock)
|
||||
jz.render(newlyAppendedBlock); // 新增之塊:直接 render(無須 revert)
|
||||
|
||||
// 自動(opt-in):觀察 DOM,內容/分類屬性變化時自動只重處理受影響之最近塊。
|
||||
jz.observe(document.body); // 之後 DOM 變動即自動增量恢復
|
||||
// jz.disconnect(); // 停止觀察
|
||||
```
|
||||
|
||||
- **`rerender(root?)`**:`revert` 後 `render` 同一(子)樹(便利方法)。
|
||||
- **`observe(root?)`/`disconnect()`**:以 `MutationObserver` 自動增量。juzhen 自身之注入
|
||||
於處理期間暫停觀察、**絕不自觸發**;新增之塊直接 render(免全容器重掃)。需 `MutationObserver`
|
||||
(瀏覽器/jsdom 有;無則 no-op)。
|
||||
- **`invalidate(root?)`**:清該子樹之內部快取。**`revert` 已自動失效其子樹**,故僅在「改了既有
|
||||
元素之分類相關屬性(`class`/`data-jz-*`/`lang` 等)**但不走 `revert`**」時才需顯式調用,以
|
||||
免下次 render 沿用陳舊分類。內容(子節點/文本)變化不改分類、無需 `invalidate`(但須
|
||||
`revert`+`render` 該塊方能重處理)。
|
||||
|
||||
> **元素變化之正確性**:實例內部對「元素分類(透明/pill/隔離/avoid)/功能級別/功能開關」
|
||||
> 快取以加速跨 render 復用(快取隨實例持久、非每次 render 重建)。**改變既有元素之上列屬性後,
|
||||
> 須經 `revert`/`rerender`/`invalidate`/`observe` 任一使該子樹快取失效**,否則沿用舊分類。
|
||||
> 新增/移除元素與純內容編輯無此顧慮(新元素重新計算、移除者自動回收)。
|
||||
|
||||
> **`revert` 之範圍**:`revert` 乾淨移除聚珍注入之全部結構(`jz-*`/`data-jz-*`),DOM 回到**邏輯
|
||||
> 等價**態;但**不還原** `spacing` 依契約規範化之贅餘作者空格(CJK↔西文吸收為 margin 間隙、
|
||||
> CJK↔CJK 剝除;見上表「中西間隙」)。即 `render→revert` 對含 CJK↔西文作者空格之源,還原後語義
|
||||
> 一致、無 `jz-*` 殘留,唯該空格已正規化(此差異穩定、不隨反覆 render/revert 累積)。若消費端需
|
||||
> 保留原始作者空格以供編輯,應自存原文、勿以 `revert` 當「還原到未處理源碼」。
|
||||
|
||||
---
|
||||
|
||||
## 切片 1 已實作功能
|
||||
|
||||
Reference in New Issue
Block a user