admin
92c37cf63e
docs 分支僅含文檔，與程式碼歷史脫鉤（orphan，無 src／dist 等舊實現之提交）。 以 HTML manifest 模板（report 模式）構建為自含單檔，無外部依賴。 - docs/index.html 使用文檔：安裝／用法／功能／選項／halt 與 margin 後備／ 字型偏側與配字工作流／CSS 基礎設定／分頁器相容／v1 相容。 - docs/changelog.html 變更紀錄。 - *.src.html 為可編輯之文檔源。 程式碼正本與其歷史在 main；本分支不記錄任何實現。
224 lines
18 KiB
HTML
224 lines
18 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-Hant">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>聚珍（Juzhen）</title>
|
||
<meta name="generated-at" content="2026-06-02">
|
||
<meta name="source" content="cjk-autospace · 使用文檔">
|
||
<!-- RUNTIME_CSS -->
|
||
</head>
|
||
<body data-toc="1">
|
||
|
||
<header class="page">
|
||
<div class="meta">
|
||
<h1>聚珍（Juzhen）</h1>
|
||
<p class="subtitle">現代簡／繁中文網頁排版套件——Han.css 之現代化重寫，複製乾淨、依 lang 全角／開明切換、justify 句末標點單份間距、跨瀏覽器一致。</p>
|
||
<p class="timestamp"><time>2026-06-02</time> · <span>cjk-autospace · 使用文檔</span></p>
|
||
</div>
|
||
<div class="actions">
|
||
<!-- ACTIONS -->
|
||
</div>
|
||
</header>
|
||
|
||
<main>
|
||
<!-- BODY -->
|
||
<p class="lede">聚珍（Juzhen）是現代簡／繁中文網頁排版套件，Han.css 之現代化重寫，沿其功能版圖，並針對四點作調整：複製乾淨（中西間隙不入剪貼板）、依 <code>lang</code> 全角／開明自動切換、<code>justify</code> 下句末標點只佔一份間距、跨瀏覽器一致。倉庫名仍為 <code>cjk-autospace</code>；公開 API 為 <code>createJuzhen</code> ／全域 <code>Juzhen</code>；注入之自訂元素前綴 <code>jz-</code>。</p>
|
||
|
||
<p>本版（2.x）為從零重寫。v1 之 <code>createCjkAutospace</code> API 由相容層保留，既有消費端不需改碼即可運行；v1 原始碼保存於 <code>v1-autospace</code> 分支。設計契約見 <code>ARCHITECTURE.md</code>。</p>
|
||
|
||
<h2>安裝與構建</h2>
|
||
<pre><code>npm install
|
||
npm run build # esbuild → dist/juzhen.{mjs,iife.js,css}；tsc → dist/index.d.ts
|
||
npm test # jsdom DOM 正確性測試</code></pre>
|
||
<p>產物（<code>dist/</code>，已入庫）：<code>juzhen.mjs</code>（ESM，供打包器／TypeScript）、<code>juzhen.iife.js</code>（IIFE，全域 <code>Juzhen</code>，原生 <code><script></code> 直跑）、<code>juzhen.css</code>（合併樣式，<strong>必須引入</strong>）、<code>index.d.ts</code>（型別宣告）。</p>
|
||
|
||
<h2>用法</h2>
|
||
<h3>原生 <code><script></code></h3>
|
||
<pre><code><link rel="stylesheet" href="dist/juzhen.css">
|
||
<script src="dist/juzhen.iife.js"></script>
|
||
<script>
|
||
const jz = Juzhen.createJuzhen({ scope: { include: ".prose" } });
|
||
jz.render(); // 對 document.body 套用（僅命中 .prose 子樹）
|
||
// jz.revert(); // 還原
|
||
</script></code></pre>
|
||
<h3>ESM／TypeScript</h3>
|
||
<pre><code>import { createJuzhen } from "cjk-autospace";
|
||
import "cjk-autospace/css";
|
||
|
||
createJuzhen({ lang: { default: "zh-Hant" } }).render(document.querySelector("main"));</code></pre>
|
||
<div class="callout info"><span class="label">JS 與 CSS 缺一不可</span> JS 只注入 <code>jz-*</code> 結構，所有視覺尺寸（間隙寬度、擠壓量、<code>justify</code> 原子化、字體堆疊）都在 <code>juzhen.css</code>。缺 CSS 則全部失效。</div>
|
||
|
||
<h2>已實作功能</h2>
|
||
<table>
|
||
<thead><tr><th>功能</th><th>說明</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>中西間隙 <code>spacing</code></td><td>CJK↔西文邊界，<strong>margin 模型</strong>：包裹左側字、以 <code>margin-right</code> 留隙，不注入空白字元 → <code>textContent</code> 完全不變、複製緊湊、<code>justify</code> 不暴增、行首乾淨；行末由 <code>gapTrim</code> layout pass 去隙以齊右。含跨樣式邊界與 <code>code</code>／<code>kbd</code> pill（pill 緊鄰標點時穿越 <code>jz-jinze</code> 仍補間隙）。贅餘作者空格一律正規化：CJK↔西文吸收為受管間隙、CJK↔CJK（含跨 inline 標籤）剝除不留隙。</td></tr>
|
||
<tr><td>長英文詞 <code>longWord</code></td><td><code>[A-Za-z]{6,}</code> 包入 <code><span lang="en"></code>，配合消費端 CSS <code>hyphens:auto</code> 原生斷詞（DOM 無連字符 → 複製不污染）。</td></tr>
|
||
<tr><td>標點擠壓 <code>jiya</code></td><td>標點 charify 為 <code>jz-char</code> ＋ <code>bd-*</code> class。三機制：baseline 政策（全角式不擠／開明式擠句內點號＋括號引號／半角式全擠）＋行內連續擠壓＋行端擠壓。半形預設以字型 OpenType <code>halt</code> 渲染；缺 <code>halt</code> 字型可切 <code>margin</code> 後備模式（見下）。</td></tr>
|
||
<tr><td>禁則 <code>jinze</code></td><td>行首行末避頭尾：閉類／點號綁前一字（不置行首）、開類綁後一字（不置行末）；只隔離邊界詞元，長引文中段仍可斷。亦為 <code>justify</code> 綁定載體。</td></tr>
|
||
<tr><td>justify 單份間距</td><td>每個 <code>jz-char</code> 為 <code>inline-block</code> 原子，句末標點只貢獻一份對齊伸縮量。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<p>後續（架構已預留，不返工）：標點懸掛、標點修正（簡↔繁）、著重號、注音／Ruby。</p>
|
||
|
||
<h2>選項</h2>
|
||
<pre><code>createJuzhen({
|
||
lang: {
|
||
default: "zh-Hant", // 無 lang 祖先時之預設語言標籤
|
||
style: "kaiming", // 全域擠壓預設：quanjiao｜kaiming｜banjiao
|
||
policy: { "zh-Hant": "quanjiao" }, // 逐 lang 覆寫（最高優先）
|
||
},
|
||
scope: { root: document.body, include: ".prose", avoid: "blockquote.raw" },
|
||
spacing: true,
|
||
longWord: { minLength: 6, lang: "en" },
|
||
jiya: true, // 或物件：{ halfWidth: "halt"|"margin", bias }
|
||
jinze: true,
|
||
justifyAtoms: true, // 分頁器下設 false 改 inline（見下）
|
||
blocks: [ { selector: ".code-comment", features: [ "spacing" ] } ],
|
||
});</code></pre>
|
||
<p>擠壓政策優先序：<strong>逐 lang <code>policy</code> ＞ 全域 <code>style</code> ＞ 內建預設</strong>（繁→全角、簡→開明）。</p>
|
||
<h3>分塊功能選擇（HTML 屬性，就近繼承）</h3>
|
||
<pre><code><p data-juzhen="spacing jiya">…</p> <!-- 白名單：僅此二功能 -->
|
||
<p data-juzhen-off="jiya">…</p> <!-- 黑名單：停用 jiya，其餘繼承 -->
|
||
<div lang="zh-Hans">…</div> <!-- lang 驅動全角／開明 --></code></pre>
|
||
|
||
<h2>標點半形：<code>halt</code> 預設與 <code>margin</code> 後備</h2>
|
||
<p>開明／半角式把標點收成「半形」，有兩種渲染機制：</p>
|
||
<table>
|
||
<thead><tr><th>機制</th><th>設定</th><th>原理</th><th>適用</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>halt</code>（預設）</td><td><code>jiya: true</code></td><td>字型 OpenType <code>halt</code>，由字型按字形正確定位、不重疊</td><td>字型含 <code>halt</code>（Noto CJK／思源系列）</td></tr>
|
||
<tr><td><code>margin</code>（後備）</td><td><code>jiya: { halfWidth: "margin" }</code></td><td><code>width:0.5em</code> ＋字身依墨色偏側溢出定位（以 CSS 重現 halt）</td><td>字型<strong>缺</strong> <code>halt</code>（多數系統字型、GBK 老字型如方正書宋 GBK、PingFang）</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="callout warn"><span class="label">為何需要後備</span> <code>halt</code> 缺席時開明式擠壓「完全無效」（標點仍佔全形）。實測<strong>方正書宋 GBK 僅含 <code>vert</code>、無 <code>halt</code></strong> → halt 模式不擠；切 <code>margin</code> 後備後，同句行寬 <code>24.0em → 19.5em</code>、單一標點 <code>1.0em → 0.5em</code>，半形生效。</div>
|
||
|
||
<h3>激活與粒度</h3>
|
||
<p>模式由 <strong><code>data-jz-halfwidth</code> 屬性所在子樹</strong>決定（CSS 後代選擇器），故粒度極靈活：</p>
|
||
<ul>
|
||
<li><strong>全域</strong>：<code>jiya: { halfWidth: "margin" }</code> → <code>render()</code> 於處理 root 自動掛屬性。</li>
|
||
<li><strong>逐區塊／逐語言</strong>：在 HTML 任一祖先手寫 <code>data-jz-halfwidth="margin"</code>（或 <code>"halt"</code>），即令該子樹用對應機制，無需另建實例。常見如「全頁 <code>halt</code>，某用無 <code>halt</code> 字型之區塊掛 <code>margin</code>」，或反之（<code>margin</code> 頁中嵌一塊 <code>halt</code> 島）。</li>
|
||
</ul>
|
||
<pre><code><!-- 全頁 halt（預設），此塊改用無 halt 字型 → 局部 margin 後備 -->
|
||
<section data-jz-halfwidth="margin" style="font-family: '方正书宋_GBK'">…</section></code></pre>
|
||
|
||
<h3>機制與字形偏側表（<code>margin</code> 模式專用，可覆寫）</h3>
|
||
<p><code>margin</code> 模式把標點 <code>jz-char</code> 之 inline-block 寬收為 <strong>0.5em（真半形 advance）</strong>，字身（<code>jz-inner</code>）以 <code>overflow</code> 溢出該盒，再依<strong>墨色偏側</strong>左移、使墨色落於 0.5em 盒內、空白溢向外側——即以 CSS 盒模型重現 <code>halt</code> 之「收字身寬＋按字形定位」。相鄰兩標點各 0.5em、合佔 1em，無鄰接疊加或單側重疊問題。</p>
|
||
<p>偏側依每字墨色中心。聚珍內建<strong>參考表</strong>（依方正書宋 GBK 實測之 glyph ink 位）：簡體點號 <code>，、。；：！？</code> 偏左；繁體點號居中；彎引號 <code>“”‘’</code>、角括號 <code>「」</code>、尖括號 <code>〈〉</code> 墨色強偏一側（開→<code>right</code>、閉→<code>left</code>）；圓／方／書名等括號 <code>（）【】《》…</code> 墨色近中→<code>center</code>。可逐 <code>lang</code> 逐字覆寫：</p>
|
||
<pre><code>createJuzhen({
|
||
jiya: {
|
||
halfWidth: "margin",
|
||
bias: {
|
||
"zh-Hans": { "，": "center", "（": "right" }, // 覆寫參考預設
|
||
"zh-Hant": { "。": "center" },
|
||
},
|
||
},
|
||
});
|
||
// 偏側值（決定字身於 0.5em 盒內之左移）：
|
||
// left 墨偏左 → 不移（字身左對齊）
|
||
// center 墨居中 → 左移 0.25em
|
||
// right 墨偏右 → 左移 0.5em（右半入盒）
|
||
// full 無可壓縮空白 → 不收、維持全形</code></pre>
|
||
|
||
<h3>字型適配工作流（margin 模式配字）</h3>
|
||
<p>換用新字型時，依下列步驟確認半形渲染：</p>
|
||
<ol>
|
||
<li><strong>驗 <code>halt</code></strong>：<code>python3 tools/measure-bias.py <font.ttf></code>（需 <code>pip install fonttools</code>）。首行報該字型是否含 OpenType <code>halt</code>。有則直接用預設（halt 模式），到此為止；無則用 <code>margin</code> 後備，續下。</li>
|
||
<li><strong>取偏側建議</strong>：同一工具量各標點 glyph 之墨色中心、印出建議偏側表與可貼入 <code>jiya.bias</code> 之 JSON。</li>
|
||
<li><strong>套用</strong>：<code>createJuzhen({ jiya: { halfWidth: "margin", bias: <貼入 JSON> } })</code>；多數宋體系 GBK 字型與內建參考表相符，未必需覆寫。</li>
|
||
<li><strong>目視微調</strong>：與原文對照逐字檢查——標點與鄰字<strong>重疊</strong>則偏側往「不移」方向調（<code>right→center→left</code>）；標點與內容<strong>仍有空隙</strong>則往「多移」方向調（<code>left→center→right</code>）；某標點無可壓空白則設 <code>full</code>。</li>
|
||
<li><strong>記錄</strong>：把該字型之 <code>bias</code> 覆寫存入專案設定，作為該字型之適配結果。</li>
|
||
</ol>
|
||
<p>偏側是「字身於 0.5em 盒內左移多少」的三檔量化（0／0.25／0.5em）；量測值近門檻時以目視為準。<code>halt</code> 字型由字型精確定位，無此配字需求——<code>margin</code> 配字僅為缺 <code>halt</code> 字型之務實近似。</p>
|
||
|
||
<h2>CSS 基礎設定（消費端須知）</h2>
|
||
<p>JS 只注入 <code>jz-*</code> 結構，<strong>所有視覺尺寸在 <code>juzhen.css</code></strong>。消費端須備妥：</p>
|
||
<ol>
|
||
<li><strong>引入樣式（必須）</strong>：<code><link rel="stylesheet" href="dist/juzhen.css"></code>（或 ESM <code>import "cjk-autospace/css"</code>）。</li>
|
||
<li><strong>設定 <code>lang</code>（強烈建議）</strong>：內容容器標 <code>lang="zh-Hans"</code>／<code>"zh-Hant"</code>／<code>"ja"</code>，驅動全角／開明政策與字形 <code>locl</code>。</li>
|
||
<li><strong>作用域類</strong>：若設 <code>scope.include: ".juzhen"</code>，須給內容容器加對應 class；<code>juzhen.css</code> 之 normalize／字型堆疊亦收斂於此域。</li>
|
||
<li><strong>長英文詞斷字</strong>：須由消費端 CSS 提供 <code>hyphens: auto</code>（含 <code>-webkit-hyphens</code>）。</li>
|
||
<li><strong><code>justify</code>（選用）</strong>：欲兩端對齊則自設 <code>text-align: justify</code>；句末標點單份間距與行末去隙由聚珍處理。</li>
|
||
<li><strong>字型（影響擠壓）</strong>：半形預設依字型 <code>halt</code>；含 <code>halt</code> 字型（Noto CJK／思源）即可，缺則用 <code>margin</code> 後備。<code>juzhen.css</code> 內建依 <code>:lang</code> 之 Noto CJK 字型堆疊，但<strong>僅作後備</strong>（全包 <code>:where()</code> 零特異度、只命中帶 <code>lang</code> 屬性之元素、不直接覆寫標點字面容器）——<strong>消費端 <code>font-family</code> 恆優先</strong>，標點亦隨之以消費端字型渲染。</li>
|
||
<li><strong>自動處理</strong>：<code>juzhen.css</code> 已於 <code>.juzhen</code> 範圍內以 <code>@supports</code> 關閉 Blink 原生 <code>text-spacing-trim</code>／<code>text-autospace</code>，並令注入間隙 <code>user-select: none</code>（複製乾淨）。</li>
|
||
</ol>
|
||
|
||
<h2>分頁器（Paged.js 等）相容：<code>justifyAtoms</code></h2>
|
||
<p>預設 <code>jz-char</code>／<code>jz-jinze</code> 為 <code>inline-block</code>，作 <code>justify</code> 之單一對齊原子。但<strong>分頁器</strong>（如 Paged.js）之對齊引擎會把每個 inline-block 邊界當伸縮點、與 CJK inter-ideograph 疊加，於窄欄混排時字距失控、整段散架。此時設 <code>justifyAtoms: false</code>——<code>jz-char</code>／<code>jz-jinze</code> 改 <code>display:inline</code>（半形 <code>halt</code> 與禁則 <code>nowrap</code> 綁定均保留）。常規流式版面無需設定。</p>
|
||
<div class="callout warn"><span class="label">注意</span> <code>margin</code> 後備半形依賴 <code>inline-block</code>（<code>width:0.5em</code>），故 <code>justifyAtoms:false</code> 與 <code>margin</code> 模式不可兼得——分頁器場景請用含 <code>halt</code> 之字型。</div>
|
||
|
||
<h2>v1 向下相容</h2>
|
||
<pre><code>const cjk = createCjkAutospace({ pillSelector: "code, kbd" });
|
||
cjk.apply(document.body); // → render</code></pre>
|
||
<p>IIFE 另掛 <code>globalThis.createCjkAutospace</code> 別名。與 v1 之差異（行為等價、不要求逐位一致）：間隙由 <code><span></code> ＋真實空格改為 <code>jz-hws</code> margin（複製更乾淨）；擠壓改由 <code>juzhen.css</code> 託管，預設仍以字型 <code>halt</code> 渲染半形（同 v1 機制），缺 <code>halt</code> 字型可切 <code>margin</code> 後備。</p>
|
||
|
||
<h2>目視驗證</h2>
|
||
<p><code>demo/index.html</code> 載入 <code>dist/</code> 產物，簡繁並列、可切 <code>justify</code>、附 copy-clean 測試區。<code>demo/fallback.html</code> 以方正書宋 GBK（無 <code>halt</code>）對照 <code>halt</code> 失效 vs <code>margin</code> 後備生效。版面相關結論（justify 單份間距、擠壓視覺量、行端、<code>inline-block</code> 基線）須於 Chrome／Safari／Firefox 三引擎目視核對——jsdom 僅驗證 DOM 結構正確性。</p>
|
||
|
||
</main>
|
||
|
||
<footer class="page">
|
||
<p>本頁為聚珍（Juzhen）使用文檔。所有文檔操作均於 docs 分支進行；main 僅存一份未追蹤之本地鏡像。MIT 授權；借鑑 Han.css／Heti 之思路與分類表，成品自含。</p>
|
||
</footer>
|
||
|
||
<!-- RUNTIME_SPRITE -->
|
||
|
||
<script type="text/markdown" id="md-source">
|
||
# 聚珍（Juzhen）
|
||
|
||
現代簡／繁中文網頁排版套件。Han.css 之現代化重寫：複製乾淨、依 `lang` 全角／開明切換、`justify` 句末標點單份間距、跨瀏覽器一致。公開 API `createJuzhen` ／全域 `Juzhen`，自訂元素前綴 `jz-`。
|
||
|
||
## 用法
|
||
|
||
```html
|
||
<link rel="stylesheet" href="dist/juzhen.css">
|
||
<script src="dist/juzhen.iife.js"></script>
|
||
<script>
|
||
Juzhen.createJuzhen({ scope: { include: ".prose" } }).render();
|
||
</script>
|
||
```
|
||
|
||
JS 只注入 `jz-*` 結構，所有視覺尺寸在 juzhen.css，缺一不可。
|
||
|
||
## 已實作功能
|
||
|
||
- spacing 中西間隙（margin 模型，copy-clean；含 pill 與作者空格正規化）
|
||
- longWord 長英文詞包裝（`<span lang>` + hyphens:auto）
|
||
- jiya 標點擠壓（全角／開明／半角；半形 halt 預設、margin 後備）
|
||
- jinze 禁則（避頭尾、justify 綁定）
|
||
- justify 句末標點單份間距（jz-char inline-block 原子）
|
||
|
||
## 標點半形：halt 預設與 margin 後備
|
||
|
||
- halt（預設，`jiya: true`）：字型 OpenType halt 定位，需字型支援。
|
||
- margin（`jiya: { halfWidth: "margin" }`）：width:0.5em＋字身依墨色偏側溢出定位，以 CSS 重現 halt；供缺 halt 字型（如方正書宋 GBK，僅含 vert）。
|
||
- 模式由 `data-jz-halfwidth` 子樹屬性決定，可逐區塊／lang。
|
||
- 偏側 inkBias 給 left/center/right/full，可 `jiya.bias` 逐 lang 逐字覆寫。
|
||
|
||
### 字型適配工作流
|
||
|
||
1. `python3 tools/measure-bias.py <font.ttf>` 驗 halt、量偏側。
|
||
2. 有 halt → 用預設；無 halt → margin 後備＋偏側表。
|
||
3. 套用 jiya.bias，瀏覽器目視微調（重疊→往不移；有隙→往多移）。
|
||
|
||
## CSS 基礎設定
|
||
|
||
引入 juzhen.css（必須）；設 lang；scope class；hyphens:auto；text-align:justify（選用）；含 halt 字型或 margin 後備。juzhen.css 之 Noto 字型堆疊僅作後備，消費端 font-family 恆優先。
|
||
|
||
## 分頁器相容
|
||
|
||
`justifyAtoms: false` → jz-char/jz-jinze 改 display:inline，相容 Paged.js。margin 後備與 justifyAtoms:false 不可兼得。
|
||
|
||
## v1 相容
|
||
|
||
`createCjkAutospace(opts).apply(root)` 經相容層映射至 createJuzhen，零改動可跑。
|
||
|
||
MIT。借鑑 Han.css／Heti 思路與分類表，成品自含。
|
||
</script>
|
||
|
||
<!-- RUNTIME_JS -->
|
||
|
||
</body>
|
||
</html>
|