Sass API

概述

「漢字標準格式」提供Sass選擇器擴展 @extend、代碼混用 @mixin、函數 @function及變數等接口,用以簡化樣式表的複雜度並避免重覆的樣式宣告。

模組

一般情況下,直接在Sass樣式表中匯入han-css/index.scss即可使用「漢字標準格式」的所有功能;然而,亦可依據網站需求,載入需要的Sass模組。

直接匯入「漢字標準格式」所有模組,

@import '[node_modules]/han-css/index';

匯入需要的Sass模組,

// 「漢字標準格式」必要檔案
@import '[node_modules]/han-css/src/sass/var';
@import '[node_modules]/han-css/src/sass/api';

// Normalize.css
@import '[node_modules]/han-css/src/sass/locale/normalize';

// 本地樣式標準化模組
@import '[node_modules]/han-css/src/sass/locale';

// 文字設計模組
@import '[node_modules]/han-css/src/sass/typography';

// 高級排版功能模組(章節的編排、行的組成)
@import '[node_modules]/han-css/src/sass/typeset';

字體基型 @extend

字體基型 @extend以精良的字體回退機制處理字體的套用,「文字設計模組」中,多數元素及情境的字體樣式由字體基型 @extend提供,相關調用的字體亦請見該頁各小節的說明。

據CSS3標準,字體基型(typeface generics)共分為「無襯線」「襯線」「手寫」「等寬」「裝飾」五種。目前「漢字標準格式」提供前述四種字體基型及相應意大利體的選擇器擴展。為選擇器加入所需的字體基型 @extend,選擇器便可套用相應的字體樣式,避免樣式的重覆宣告。

註:文字設計中,「generics」一詞應作「通用字體」;本使用手冊為明顯區分「字體」與「通用字體」,遂將後者統一稱作「基型」或「字體基型」,以為差異。

一般字體基型 @extend的調用形式為,

@extend %han-[基型]-[語言文字變體];

搭配西文意大利體的字體基型 @extend調用形式為,

@extend %han-[基型]-italic-[語言文字變體];

註:西文等寬基型 @extend不提供意大利體。

或參見以下二表,

漢字字體基型

基型 繁體中文 簡體中文 日文
黑體 %han-sans-hant %han-sans-hans %han-sans-ja
黑體、
意大利體
%han-sans-italic-hant %han-sans-italic-hans %han-sans-italic-ja
宋體 %han-serif-hant %han-serif-hans %han-serif-ja
宋體、
意大利體
%han-serif-italic-hant %han-serif-italic-hans %han-serif-italic-ja
楷體 %han-cursive-hant %han-cursive-hans %han-cursive-ja
楷體、
意大利體
%han-cursive-italic-hant %han-cursive-italic-hans %han-cursive-italic-ja
西文等寬/
黑體
%han-mono-hant %han-mono-hans %han-mono-ja

因Firefox 36起更改了 @font-face選用策略,在部分情況下無法處理回退字體。為正確顯示「西文等寬字體」,漢字標準格式自v3.2.1起暫時去除等寬漢字字體基型下的漢字標點字體。

西文字體基型

基型 西文字體
無襯線 %han-sans
無襯線意大利體 %han-sans-italic
襯線 %han-serif
襯線意大利體 %han-serif-italic
手寫 %han-cursive
手寫意大利體 %han-cursive-italic
等寬 %han-mono

代碼示例

.box {
  @extend %han-mono-hans;
}

上方的Sass代碼會將選擇器.box擴展至佔用符%han-mono-hans上。樣式表輸出結果將類似於,

[%han-mono-hans],
code:lang(zh-Hans),
[……],
.box {
  font-family: "Biaodian Pro Sans GB", Menlo, Courier, "Han Heiti GB", monospace, monospace, sans-serif
}

覆蓋順序

在擁有相同繼承權重的同一選擇器上套用二個以上的字體基型 @extend時,字體樣式不為基型 @extend宣告順序所決定,相關覆蓋順序規則見下表,

基型覆蓋優先級
西文等寬/黑體
楷體、意大利體
楷體
宋體、意大利體
宋體
黑體、意大利體
黑體

代碼示例

.some-container {
  @extend %han-cursive-italic-hant;
  @extend %han-sans-hant;
}

.some-container-2 {
  @extend %han-sans-hant;
  @extend %han-cursive-italic-hant;
}

上述代碼中,容器.some-container.some-container-2的最終字體樣式皆應為「楷體(繁體)、西文意大利體」,而非「黑體(繁體)」,意即覆蓋規則與宣告順序無關

相應的 @mixin

使用字體基型 @mixin han-typeface-by-lang可為選擇器加入所有地區變體之字體樣式的擴展,其調用形式為,

@include han-typeface-by-lang( $typeface: [基型] );
// 意大利體
@include han-typeface-by-lang( $typeface: [基型]-italic );

代碼示例

.entry {
  @include han-typeface-by-lang( $typeface: cursive );
}

上方代碼同等於,

.entry {
  &:lang(zh),
  &:lang(zh-Hant) {
    @extend %han-cursive-hant;
  }

  &:lang(zh-Hans),
  &:lang(zh-CN) {
    @extend %han-cursive-hans;
  }

  &:lang(ja) {
    @extend %han-cursive-ja;
  }

  &:lang(zh-Latn),
  &:lang(ja-Latn),
  &:not(:lang(zh)):not(:lang(ja)),
  *:lang(zh-Latn),
  *:lang(ja-Latn),
  *:not(:lang(zh)):not(:lang(ja)) {
    @extend %han-cursive;
  }
}

章節的編排

章節的計數

若欲在非「文章區塊容器」(預設為文章article元素)中使用章節的計數功能,直接混用han-section-counter即可。套用後,容器內二至四級標題將自動納入計數,二級標題使用漢字數字(一二三……)標示,三、四級標題則使用「1.1」「1.2.1」數字形式,適合用於技術文獻或長篇文章。

@include han-section-counter( $toc: false );

參數說明

$toc

使用目錄清單與否,預設關閉。開啓後,容器下類別為.toc的有序清單ol元素即作為該容器的目錄,其後每增加一子清單元素,即為下一級的標題名稱容器,可置於長篇文章頂部,方便跳轉及査閱。

示例請見測試範例頁·章節與目錄的計數

行的組成

着重號

強調em元素預設使用着重號樣式,「漢字標準格式」提供接口方便其他選擇器使用相同的CSS3 text-emphasis屬性的polyfill。包含Sass及JavaScript二部分,後者可依需求選用。

Sass

@include han-text-emphasis( 
  $posi: under,
  $mark: circle,
  $shape: filled,
  $color: inherit,
  $skip: true,
  $extend: true
);

參數說明

$posi

着重號的位置,可為字下under或字上over

$mark

着重號符號,選項有圈circle、點dot、雙圈double-circle、三角形triangle、芝麻點sesame或其他字符<string>

$shape

着重號形狀,填滿filled、空心open、無none`。

$color

着重號顏色。

$skip

規避標點符號與否(需配合JavaScript腳本)。

$extend

使用選擇器 @extend與否,可減縮生成的CSS代碼大小。

JavaScript(選用)

Han( context ).renderEm( selector )

參數說明

context

套用着重號選擇器的範圍,預設為文件內容body元素。

selector

套用着重號的目標選擇器,支援CSS選擇器語法。

示例請見測試範例頁·強調元素(着重號)

啓用web font合字功能

在需要啓用web font合字(ligature)功能的選擇器上引用如下 @extend。

@extend %han-ligature;

行尾點號懸掛

Sass變數彙整下的相應小節

直式注音符號

非行間注元素下、符合han.js渲染的注音符號格式之容器可以引用直式注音符號樣式 @extend。

@extend %han-zhuyin;

Sass變數彙整

以下是「漢字標準格式」Sass樣式表下所有可調控的變數及其預設値。最佳實踐方式係在引用_han.sass前,為需要更動的變數賦値。

檔案路徑

Web fonts所在路徑,

$han-font-path: './font/';

元素容器的選用

根元素,依需求可改用:root等。

$han-root: html;

文章區塊容器,其他的可能値有.article.entry#post……等。

$han-article: article;

「行動裝置模式」的啓用寬度(裝置或瀏覽器視窗),

$han-mobile-device-width: 480px;

文字樣式

行高(全域行高文章行高),

$han-line-height:         1.3;  // 全域行高(設置於根元素)
$han-article-line-height: 1.7;  // 文章行高(設置於文章區塊容器)

文章區塊是否使用齊頭尾文字對齊

$han-article-justify:     true;

文章區塊是否啓用「章節與目錄的計數」功能。

$han-section-counter:     false;  // 章節標題計數
$han-section-counter-toc: false;  // 目錄計數

縮進字數,

$han-indent:    2em;
$han-indent-md: 1em;  // 行動裝置上的縮進

着重號相關設定,

// 遇標點回避與否
$han-text-emphasis-skip: true;

// 着重號形狀
// `none` || `filled` || `open`
$han-text-emphasis-shape: filled;

// 着重號符號
// `dot` || `circle` || `double-circle` || `triangle` || `sesame` || <string>
$han-text-emphasis-mark: circle;

// 着重號位置
// `over` || `under`
$han-text-emphasis-posi: under;

// 着重號顏色
// `inherit` || <color>
$han-text-emphasis-color: inherit;

// 日文着重號樣式設定(同上)
$han-text-emphasis-shape-ja: filled;
$han-text-emphasis-mark-ja:  sesame;
$han-text-emphasis-posi-ja:  over;
$han-text-emphasis-color-ja: inherit;

行間注元素中,注音符號的字體大小(單位:em),

$han-zhuyin-size: .5;

文字設計

字集相關設定(漢字標點),

// 繁體中文字體變體
// `default` || `CNS` || `GB`
$han-glyph-set-hant: default;

// 繁體中文標點字體
// `Pro` || `CNS` || `GB` || `simp`
$han-biaodian-hant: Pro;

// 簡體中文字體變體
// `default` || `GB`
$han-glyph-set-hans: GB;

// 簡體中文標點字體
// `Pro` || `CNS` || `GB` || `simp`
$han-biaodian-hans: GB;

西文預設字體,

// 無襯線
$han-sans:  'Helvetica Neue', Helvetica, Arial;
// 襯線
$han-serif: Georgia, 'Times New Roman';
// 等寬
$han-mono:  Menlo, Courier;

中文預設字體,

$han-sans-zh:    '';
$han-serif-zh:   '';
$han-cursive-zh: '';
$han-mono-zh:    $han-sans-zh;

行的組成

各語言文字的行尾點號懸掛啓用與否,

// 繁體中文
$han-hanging-hant: false;
// 簡體中文
$han-hanging-hans: true;
// 日語
$han-hanging-ja:   true;