JavaScript API

概述

「漢字標準格式」的腳本文件han.js提供多種接口以方便功能的調用，其所有開放的變量、常量、函數及方法皆收錄於Han構造函數中，亦支援異步模塊載入器（AMD或CommonJS）。

AMD

require( [ './han.min' ], function( Han ) {
  Han.init()
})

CommonJS（NPM）

var Han = require( 'han-css' )
Han.init()

Han構造函數

構造函數Han的使用方式類似jQuery，支援快捷的鏈式書寫，實例的生成亦毋須使用new運算符。

Han( context, condition )
.method()
.method2()
…

參數說明

context: 選用。單一的指定渲染範圍DOM元件，預設為document.body。
condition: 選用。附加信息——如功能、字體支援偵測類別等——的加載環境，預設為根元素document.documentElement。

渲染機制

Han提供下列多種渲染方法，可依需求選用。

Han.fn.render()

在未更動「常規渲染途徑」（Han.fn.routine）的情況下，渲染途徑的簡寫方法render()將依下列清單之順序，依序執行各渲染方法。

初始化initCond()
字級語意元素樣式標準化renderElem()
- 渲染行間注元素renderRuby()
- 渲染文字裝飾線元素renderDecoLine()
- 渲染強調元素renderEm()
渲染行尾點號懸掛renderHanging()
渲染標點擠壓renderJiya()
渲染漢字西文混排間隙renderHWS()
修正基本標點符號correctBasicBD()（瀏覽器不支援時啓用）
以PUA字元取代合字符substCombLigaWithPUA()（瀏覽器不支援時啓用）

Han( document.querySelector( '.entry' )).render()

上述簡寫同等於，

Han( document.querySelector( '.entry' ))
.initCond()
.renderElem()
.renderHanging()
.renderJiya()
.renderHWS()
.correctBasicBD()
.substCombLigaWithPUA()

全頁渲染簡寫Han.init()

全頁渲染簡寫方法Han.init()，網頁完成DOM載入後可使用乙次，為網頁載入Han渲染機制，並回傳該實例。

var hinst = Han.init()

等同於，

var hinst = Han( document.body ).render()

使用類別啓用全頁渲染

在根元素套用類別.han-init，或在指定單一元素上套用類別.han-init-context即可在DOM完成載入後渲染頁面。

<html lang="zh-Hant" class="han-init">

或

<article class="han-init-context">
  …
</article>

Han.init作為實例

原作為方法的命名空間Han.init在完成上述二種DOM ready渲染後，即替換為該Han實例，以利後續處理及調用。

Han.init()

// …

// After the DOM-ready rendering
var hinst = Han.init

hinst.replace( /IE\s?[6-8]/gi, 'IE11' )

上述代碼大致同等於，

Han.init().replace( /IE\s?[6-8]/gi, 'IE11' )

環境初始化

Han.fn.initCond()

為condition（預設為根元素）加入各項功能及字體支援偵測類別。

分類	類別名稱	說明
渲染	`han-js-rendered`	已完成「漢字標準格式」的腳本渲染。
功能	`[no-]ruby`	瀏覽器是否支援HTML的基本行間注功能。
	`[no-]ruby-display`	瀏覽器是否支援CSS行間注`ruby-display`屬性。
	`[no-]ruby-interchar`	瀏覽器是否支援CSS行間注`ruby-position`屬性的`inter-character`値。
	`[no-]fontface`	瀏覽器是否支援CSS3的`@font-face`功能。
	`[no-]unicoderange`	瀏覽器是否支援CSS3 `@font-face`的`unicode-range`功能。
	`[no-]columnwidth`	瀏覽器是否支援CSS3的容器分欄功能。
	`[no-]textemphasis`	瀏覽器是否支援CSS3的文字着重號功能。
	`[no-]writingmode`	瀏覽器是否支援CSS的書寫模式（文字直排等）功能。
字體	`[no-]songti`	作業系統是否支援宋體（Han Songti等）。
	`[no-]songti-gb`	作業系統是否支援簡體中文宋體（Han Songti GB）。
	`[no-]kaiti`	作業系統是否支援楷體（Han Kaiti等）。
	`[no-]fangsong`	作業系統是否支援仿宋體（Han Fangsong等）。
	`heiti`	假定所有作業系統皆支援黑體（Han Heiti等）。
	`[no-]han-space`	瀏覽器是否正確加載空格字體（用於行尾點號懸掛）。

樣式標準化

樣式標準化方法對下列四類、共六個字級語意元素進行DOM重構，以便在樣式表中修正樣式。

行間注ruby元素
註記u及增訂ins元素（文字裝飾線）
訛訊s及刪訂del元素（文字裝飾線）
強調em元素（着重號）

Han.fn.renderElem()

修正Han實例範圍內上述清單所列之元素樣式，詳情請見以下各小節。

Han.fn.renderRuby()

依Han實例範圍內各個行間注ruby元素之類別，套用相應的DOM重構，以利樣式表正確顯示其樣式。

相關說明，請見〈樣式標準化·行間注元素〉。

Han.fn.renderDecoLine( [target] )

修正Han實例範圍內包含文字裝飾線的相鄰元素，預設為註記u與增訂ins元素。

相關說明，請見〈樣式標準化·文字裝飾線〉。

參數說明

target: 字串，選用。作用的目標元素選擇器，預設値為'u, ins'。

Han.fn.renderEm( [target] )

修正Han實例範圍內套用着重號樣式的元素，預設為強調em元素。需要配合相應的Sass @mixin。

相關說明，請見〈樣式標準化·強調與重點〉。

參數說明

target: 字串，選用。作用的目標元素選擇器，預設値為'em'。

行的組成

Han.fn.renderHanging()

處理Han實例範圍內的「行尾點號懸掛」。

Han.fn.revertHanging()

回退Han實例範圍內，行尾點號懸掛修正前的DOM結構。

Han.fn.renderJiya()

處理Han實例範圍內的「標點擠壓」。

Han.fn.revertJiya()

回退Han實例範圍內，標點擠壓修正前的DOM結構。

Han.fn.renderHWS( [strict] )

處理Han實例範圍內的「漢字－西文混排間隙」。

參數說明

strict: 布林値，選用。是否啓用嚴格模式。預設為否。

Han.fn.revertHWS()

回退Han實例範圍內，漢字－西文混排間隙修正前的DOM結構。

注意：此方法並非嚴格的finder回退，可能導致非預期的結果，請謹慎使用。

Han.fn.correctBasicBD( [all] )

處理Han實例範圍內的「標點樣式修正」（瀏覽器不支援CSS3 @font-face的unicode-range屬性時啓用，如Mozilla Firefox）。

參數說明

all: 布林値，選用。是否在支援CSS3 unicode-range屬性的瀏覽器下亦進行修正。預設為否。

Han.fn.revertBasicBD()

回退Han實例範圍內，標點樣式修正前的DOM結構。

Han.fn.substCombLigaWithPUA()

處理Han實例範圍內的「變音組字符」（瀏覽器無法正常顯示變音組字符時啓用，如IE）。

Han.fn.revertCombLigaWithPUA()

回退Han實例範圍內，修正變音組字符前的DOM結構。

功能與字體支援偵測

Han.support

對象（object），其下所包含各項目之値（布林値）表示該項目是否為使用者瀏覽器所支援。

Han.support.ruby（基本行間注，HTML）
Han.support.ruby-display（行間注，CSS3）
Han.support.ruby-interchar（行間注，CSS3）
Han.support.fontface（CSS3）
Han.support.unicoderange（CSS3 @font-face）
Han.support.columnwidth（CSS3）
Han.support.textemphasis（CSS3）
Han.support.writingmode（CSS3）

Han.isVowelCombLigaNormal()

函數方法。偵測瀏覽器是否正常支援拉丁字母元音的OpenType組合合字（combining ligature）功能，需在字體檔案han.woff正常載入的情況下，方回傳正確的偵測結果。回傳布林値。

Han.isVowelICombLigaNormal()

函數方法。偵測瀏覽器是否正常支援拉丁字母元音「i」的OpenType組合合字（combining ligature）功能，需在字體檔案han.woff正常載入的情況下，方回傳正確的偵測結果。回傳布林値。

Han.isZhuyinCombLigaNormal()

函數方法。偵測瀏覽器是否正常支援注音符號入聲調號的OpenType組合合字（combining ligature）功能，需在字體檔案han.woff正常載入的情況下，方回傳正確的偵測結果。回傳布林値。

Han.isCombLigaNormal

【已棄用】布林値，瀏覽器是否正常支援OpenType組合合字（combining ligature）功能，需在字體檔案han.woff正常載入的情況下，方回傳正確的偵測結果。

Han.isNodeNormalizeNormal

布林値，IE11的Node.prototype.normalize()方法可能導致錯誤，調用此變量可瞭解該方法在使用者瀏覽器上是否正常運行。

Han.detectFont( treat[, control, text] )

函數方法。用於偵測字體是否為使用者作業系統所支援，回傳布林値。

參數說明

treat: 字串。實驗組字體名稱（列表）。
control: 字串，選用。對照組字體名稱（列表），預設値為無襯線'sans-serif'基型。
text: 字串，選用。比對二組字體的實驗文字，預設値為包含漢字及拉丁字母的'辭Q'。

字元査替器

字元査替器是基於findAndReplaceDOMText庫的字元査替方法集合，用以替換或使用元素來包裹DOM結構中的文字。

與原生String.prototype.replace()等方法不同，字元査替器支援跨元素邊界的字元査找。

Han.fn.replace()

將Han指定範圍中符合pattern表達式的文字替換為newSubStr。

Han( context ).replace( pattern, newSubStr )

參數說明

pattern: 正則表達式或字串。査找指定範圍內相應的文字。
newSubStr: 字串，目標文字的替換內容。

Han.fn.wrap()

以newSubElem返回的元素包裹Han指定範圍內、符合pattern表達式的文字。

Han( context ).wrap( pattern, newSubElem )

參數說明

pattern: 正則表達式或字串。
newSubElem: 一個DOM對象或元素名稱字串。

Han.fn.revert()

回退至finder査替前的DOM狀態，回退層級以參數level決定，預設回退一級。

Han( context )
// .replace()
// .wrap()
// …
.revert( [level] )

參數說明

level: 數字、可轉換為數字的字串或'all'，使用'all'將回退該Han對象上的所有finder。

範例

var hinst = Han( document.body )

hinst
.replace( /詞[匯會惠]/g, '辭彙' )
.wrap( /辭彙/g, 'em' )
// …

window.addEventListener( 'DOMContentLoaded', function() {
  setTimeout(function() {
    hinst.revert( 'all' )
  }, 5000 )
})

網頁中的「詞匯」「詞會」「詞惠」等字樣將替換成「辭彙」，並為強調em元素所包裹。網頁在DOM載入完成事件觸發後5秒，受替換的文字將自動回退至先前的「詞匯」「詞會」或「詞惠」等，包裹的強調元素亦會移除。

詞組、字級選擇器

Han.fn.groupify( [option] )

依選項為Han對象上的指定範圍進行詞或組的包裹，實現「詞組選擇器」。

若需同時調用，方法groupify()應調用於方法charify()之前，方能取得預期結果。

option及其預設値

{
  // 漢字標點（以`h-char-group`元素包裹）
  biaodian: false,

  // 漢字（包含假名，以`h-char-group`元素包裹）
  // 或使用鍵名`cjk`
  hanzi: false,

  // 假名（以`h-char-group`元素包裹）
  kana: false,

  // 諺文（詞組，以`h-word`元素包裹）
  // 或使用鍵名`hangul`
  eonmun: false,

  // 西文詞（詞組，以`h-word`元素包裹）
  // 包含拉丁字母、希臘字母、西里爾字母及西文標點組成的詞組
  western: false
}

代碼示例

詞組選擇器處理前，

<div id="example">
  <p>「你好」！
  <p>「こんにちは」、"안녕하세요."
  <p>‘Hello World’, «Γειά Σου Κόσμε», 'привет мир'.
</div>

JavaScript代碼示例，

Han( document.getElementById( 'example' ))
.groupify({
  biaodian: true,
  hanzi: true,
  kana: true,
  eonmun: true,
  western: true
})

詞組選擇器處理後，

<div id="example">
  <p>「<h-char-group class="hanzi cjk">你好</h-char-group><h-char-group class="biaodian cjk">」！</h-char-group></p>
  <p>「<h-char-group class="hanzi cjk">こんにちは</h-char-group><h-char-group class="biaodian cjk">」、</h-char-group><h-word class="western">"</h-word><h-word class="eonmun hangul">안녕하세요</h-word><h-word class="western">."</h-word></p>
  <p><h-word class="western">‘Hello</h-word> <h-word class="western">World’,</h-word> <h-word class="western">«Γειά</h-word> <h-word class="western">Σου</h-word> <h-word class="western">Κόσμε»,</h-word> <h-word class="western">'привет</h-word> <h-word class="western">мир'.</h-word></p>
</div>

Han.fn.charify( [option] )

依選項或預設設定為Han對象上的指定範圍進行字元包裹，實現「字級選擇器」。

若需同時調用，方法groupify()應調用於方法charify()之前，有較佳效果。

option及其預設値

{
  // 漢字標點
  biaodian: false,

  // 西文標點
  punct: false,

  // 漢字（包含假名）
  // 或使用鍵名`cjk`
  hanzi: false,

  // 拉丁字母
  latin: false,

  // 希臘字母 
  // 或使用鍵名`greek`
  ellinika: false,

  // 西里爾字母
  // 或使用鍵名`cyrillic`
  kirillica: false,

  // 假名
  kana: false,

  // 諺文
  // 或使用鍵名`hangul`
  eonmun: false
}

代碼示例

字級選擇器處理前

<div id="example">
  <p>「你好」！
  <p>「こんにちは」、"안녕하세요."
  <p>‘Hello World’, «Γειά Σου Κόσμε», 'привет мир'.
</div>

JavaScript腳本，

Han( document.getElementById( 'example' ))
.charify({
  biaodian: true,
  punct: true,
  hanzi: true,
  latin: true,
  ellinika: true,
  kirillica: true,
  kana: true,
  eonmun: true
})

字級選擇器處理後

<div id="example">
  <p><h-char unicode="300c" class="biaodian cjk bd-open">「</h-char><h-char class="hanzi cjk">你</h-char><h-char class="hanzi cjk">好</h-char><h-char unicode="300d" class="biaodian cjk bd-close bd-end">」</h-char><h-char unicode="ff01" class="biaodian cjk bd-end">！</h-char></p>
  <p><h-char unicode="300c" class="biaodian cjk bd-open">「</h-char><h-char class="hanzi cjk">こ</h-char><h-char class="hanzi cjk">ん</h-char><h-char class="hanzi cjk">に</h-char><h-char class="hanzi cjk">ち</h-char><h-char class="hanzi cjk">は</h-char><h-char unicode="300d" class="biaodian cjk bd-close bd-end">」</h-char><h-char unicode="3001" class="biaodian cjk bd-end">、</h-char><h-char class="punct">"</h-char><h-char class="eonmun hangul">안</h-char><h-char class="eonmun hangul">녕</h-char><h-char class="eonmun hangul">하</h-char><h-char class="eonmun hangul">세</h-char><h-char class="eonmun hangul">요</h-char><h-char class="punct">.</h-char><h-char class="punct">"</h-char></p>
  <p><h-char class="punct">‘</h-char><h-char class="alphabet latin">H</h-char><h-char class="alphabet latin">e</h-char><h-char class="alphabet latin">l</h-char><h-char class="alphabet latin">l</h-char><h-char class="alphabet latin">o</h-char> <h-char class="alphabet latin">W</h-char><h-char class="alphabet latin">o</h-char><h-char class="alphabet latin">r</h-char><h-char class="alphabet latin">l</h-char><h-char class="alphabet latin">d</h-char><h-char class="punct">’</h-char><h-char class="punct">,</h-char> <h-char class="punct">«</h-char><h-char class="alphabet ellinika greek">Γ</h-char><h-char class="alphabet ellinika greek">ει</h-char><h-char class="alphabet ellinika greek">ά</h-char> <h-char class="alphabet ellinika greek">Σ</h-char><h-char class="alphabet ellinika greek">ο</h-char><h-char class="alphabet ellinika greek">υ</h-char> <h-char class="alphabet ellinika greek">Κ</h-char><h-char class="alphabet ellinika greek">ό</h-char><h-char class="alphabet ellinika greek">σ</h-char><h-char class="alphabet ellinika greek">μ</h-char><h-char class="alphabet ellinika greek">ε</h-char><h-char class="punct">»</h-char><h-char class="punct">,</h-char> <h-char class="punct">'</h-char><h-char class="alphabet kirillica cyrillic">п</h-char><h-char class="alphabet kirillica cyrillic">р</h-char><h-char class="alphabet kirillica cyrillic">и</h-char><h-char class="alphabet kirillica cyrillic">в</h-char><h-char class="alphabet kirillica cyrillic">е</h-char><h-char class="alphabet kirillica cyrillic">т</h-char> <h-char class="alphabet kirillica cyrillic">м</h-char><h-char class="alphabet kirillica cyrillic">и</h-char><h-char class="alphabet kirillica cyrillic">р</h-char><h-char class="punct">'</h-char><h-char class="punct">.</h-char></p>
</div>

Han.fn.jinzify()

為Han對象上的指定範圍加入標點禁則處理。

一般情況下，瀏覽器可以正常套用標點禁則，毋須使用此方法。若需同時調用，方法jinzify()應調用於方法groupify()及charify()之前，有較佳效果。

代碼示例

禁則處理前

<div id="example">
  <p>林·菲利認為，身為一個「航海家」，這是不可寬恕的過錯。
</div>

JavaScript腳本，

Han( document.getElementById( 'example' )).jinzify()

禁則處理後

<div id="example">
  <p><h-jinze class="middle">林·菲</h-jinze>利認<h-jinze class="wei">為，</h-jinze>身為一個<h-jinze class="tou">「航</h-jinze>海<h-jinze class="wei">家」，</h-jinze>這是不可寬恕的過<h-jinze class="wei">錯。</h-jinze></p>
</div>

相應的CSS樣式，

h-jinze {
  display: inline-block;
  text-indent: 0
}

萬國碼區段及正則表達式

Han包含二類萬國碼區段表達式常量——以字串集合而成的Han.UNICODE及以正則表達式集合而成的Han.TYPESET。

漢字標點

點號

Han.UNICODE.biaodian.base

開始括注號

Han.UNICODE.biaodian.open
Han.TYPESET.char.biaodian.open

結束括注號

Han.UNICODE.biaodian.close
Han.TYPESET.char.biaodian.close

結束標點符號（包含點號與結束括注號）

Han.UNICODE.biaodian.end
Han.TYPESET.char.biaodian.end

佔二個漢字空間的標點

Han.UNICODE.biaodian.liga
Han.TYPESET.char.biaodian.liga

漢字標點表達式

字符：Han.TYPESET.char.biaodian.all
字符組：Han.TYPESET.group.biaodian[0]
字符組：Han.TYPESET.group.biaodian[1]

西文標點

點號

Han.UNICODE.punct.base

開始括注號

Han.UNICODE.punct.open
Han.TYPESET.char.punct.open

結束括注號

Han.UNICODE.punct.close
Han.TYPESET.char.punct.close

結束標點符號（包含點號與結束括注號）

Han.UNICODE.punct.end
Han.TYPESET.punct.biaodian.end

西文標點表達式

字符：Han.TYPESET.char.punct.all

漢字區段

基本漢字（包含擴展區）

Han.UNICODE.cjk.base
意音文字描述字元：Han.UNICODE.cjk.desc
繁簡漢字部首：Han.UNICODE.cjk.radical

漢字、假名及其相關區段表達式

字符：Han.TYPESET.char.cjk
字符組：Han.TYPESET.group.cjk

亦可使用hanzi替代cjk鍵名。

西文

包含拉丁字母、希臘字母、西里爾字母及西文標點符號的正則表達式，多用於詞組。

詞組：Han.TYPESET.group.western

拉丁字母區段

基本拉丁字母、組合字符

Han.UNICODE.latin.base
Han.UNICODE.latin.combine

拉丁字母表達式（包含組合字符）

字符：Han.TYPESET.char.latin
詞組：Han.TYPESET.group.western

希臘字母區段

基本希臘字母、組合字符

Han.UNICODE.greek.base
Han.UNICODE.greek.combine

希臘字母表達式（包含組合字符）

字符：Han.TYPESET.char.greek
詞組：Han.TYPESET.group.western

亦可使用ellinika替代greek鍵名。

西里爾字母區段

基本西里爾字母、組合字符

Han.UNICODE.cyrillic.base
Han.UNICODE.cyrillic.combine

西里爾字母表達式（包含組合字符）

字符：Han.TYPESET.char.cyrillic
詞組：Han.TYPESET.group.western

亦可使用kirillica替代cyrillic鍵名。

假名區段

基本假名

Han.UNICODE.kana.base
組合字符：Han.UNICODE.kana.combine
半形：Han.UNICODE.kana.half
小寫：Han.UNICODE.kana.base
符號：Han.UNICODE.kana.mark

假名表達式

字符：Han.TYPESET.char.kana
字符組：Han.TYPESET.group.kana

諺文區段

基本諺文

Han.UNICODE.hangul.base
半形：Han.UNICODE.hangul.half
字母：Han.UNICODE.hangul.letter

諺文表達式

字符：Han.TYPESET.char.hangul
詞組：Han.TYPESET.group.hangul

亦可使用eonmun替代hangul鍵名。

注音符號區段

基本注音符號（國語及方言音）

全部：Han.UNICODE.zhuyin.base
聲母：Han.UNICODE.zhuyin.initial
介音：Han.UNICODE.zhuyin.medial
韻母：Han.UNICODE.zhuyin.final

聲調

平上去聲：Han.UNICODE.zhuyin.tone（包含國語四聲及輕聲）
入聲：Han.UNICODE.zhuyin.checked

注音拼式表達式

整體：Han.TYPESET.zhuyin.form
聲調：Han.TYPESET.zhuyin.diao