TwinType Webfont

依頁面實際用到的字元動態產生字型子集。瀏覽器只下載該頁需要的字，而不是整套字型檔。

Generates font subsets from the characters a page actually uses. The browser downloads only the glyphs on that page instead of a complete font file.

需要準備

Prerequisites

• 一個專案 Token（在主控台建立專案後取得）
• 該專案的允許網域清單中，包含你要嵌入的網站網域

• A project token, issued when you create a project in the console
• The site's domain listed in that project's allowed domains

最小可用範例

Minimal setup

<script src="https://api.twintype.co/webfont-api.js?token=YOUR_TOKEN"></script>

貼在 <head>。腳本會在載入時掃描頁面文字、向 API 請求對應的子集，並注入 @font-face。

Place it in <head>. On load the script scans the page text, requests the matching subset, and injects @font-face.

字型的套用仍由你的 CSS 決定：

Applying the font is still up to your CSS:

body {
  font-family: 'pingting', sans-serif;
}

font-family 的值必須與字型的 family 名稱一致。方案內的字型可在主控台的字型預覽頁查到； 自訂字型的 family 顯示在「我的字體」。

The font-family value must match the font's family name exactly. Plan fonts are listed on the console's font preview page; family names for your own uploads appear under My Fonts.

兩種整合方式

Two integration paths

計費單位

Billing

每一次子集請求消耗 1 PV，快取命中也計算。額度依方案，用完後 API 回傳 402。

Each subset request consumes 1 PV, including cache hits. Quota depends on the plan; the API returns 402 once it is exhausted.

嵌入腳本

Embed Script

<script>
  window.TWINTYPE_CONFIG = {
    mode: "auto",
    hideBody: true
  };
</script>
<script src="https://api.twintype.co/webfont-api.js?token=YOUR_TOKEN"></script>

TWINTYPE_CONFIG 必須在腳本標籤之前宣告，否則不會被讀到。

TWINTYPE_CONFIG must be declared before the script tag or it will not be read.

Token 從腳本的 src query string 取得。若同一頁有多個腳本標籤，第一個帶 token= 的會被採用。

The token is taken from the script's src query string. With multiple script tags, the first one carrying token= wins.

模式

Modes

三種模式在載入時都會掃描頁面並請求一次。差別在載入之後還會不會自動再請求。

All three modes scan the page and issue one request on load. They differ in whether anything happens afterwards.

設定項

Configuration

window.TWINTYPE_API 也可覆寫 API 位址，優先於 CONFIG.api。

window.TWINTYPE_API also overrides the API URL and takes precedence over CONFIG.api.

狀態 class

State classes

腳本會在 <html> 上維護目前狀態，可用於自訂載入樣式。

The script maintains the current state on <html> for styling load transitions.

html.tw-loading .content { visibility: hidden; }

JS API

腳本載入後掛在 window.TWINTYPE。

Available on window.TWINTYPE once the script has loaded.

setText

setText

用於預覽器一類的介面：文字來自輸入框，而不是頁面內容。

For preview interfaces where the text comes from an input rather than the page.

input.addEventListener('input', () => {
  TWINTYPE.setText(input.value);
});

setText 設定後會一直生效，頁面掃描不再影響請求內容。要恢復掃描，傳 null。

Once set, setText stays in effect and page scanning no longer affects requests. Pass null to resume scanning.

unobserve

unobserve

在 auto 模式下呼叫，等同於「只吃第一次掃描的結果」：

Called under auto, this makes the first scan the only one:

window.addEventListener('load', () => {
  TWINTYPE.unobserve();
});

回呼

Callbacks

指派為 window.TWINTYPE 上的函式。回呼中拋出的例外會被忽略，不會中斷字型載入。

Assign functions on window.TWINTYPE. Exceptions thrown from a callback are swallowed and will not interrupt font loading.

TWINTYPE.onActived = () => {
  document.body.classList.add('fonts-ready');
};

回呼必須在腳本載入之後指派。若要在載入前就準備好，先建立物件：

Callbacks must be assigned after the script loads. To have them ready earlier, create the object first:

window.TWINTYPE = window.TWINTYPE || {};
window.TWINTYPE.onActived = () => { /* ... */ };

Subset API

POST https://api.twintype.co/api/fonts/subset
Content-Type: application/json

請求

Request

{
  "token": "YOUR_TOKEN",
  "site": "https://example.com",
  "family": "pingting",
  "weight": 600,
  "text": "天地玄黃 宇宙洪荒"
}

回應

Response

{
  "success": true,
  "subset_url": "https://api.twintype.co/fonts/subset/subset_<hash>.woff2",
  "cached": false
}

注入字型

Injecting the font

function injectFontFace(family, weight, url) {
  const id = `tt-${family}-${weight}`;
  let el = document.getElementById(id);
  if (!el) {
    el = document.createElement('style');
    el.id = id;
    document.head.appendChild(el);
  }
  el.textContent = `
    @font-face {
      font-family: '${family}';
      font-weight: ${weight};
      font-display: block;
      src: url('${url}') format('woff2');
    }
  `;
}

用固定的 id 覆寫同一個 <style>，避免重複請求累積出大量 @font-face 規則。

Overwriting a <style> with a fixed id keeps repeated requests from accumulating @font-face rules.

網域比對

Domain matching

site 會正規化後與專案的允許網域逐一比對，必須完全相等。正規化會去除協定、路徑與通訊埠。 因此 https://example.com:8443/page 與 example.com 相符。 子網域不會自動涵蓋：www.example.com 與 example.com 是兩個不同的值，都要分別加入。

site is normalised and compared against each allowed domain for an exact match. Normalisation strips the scheme, path and port, so https://example.com:8443/page matches example.com. Subdomains are not covered automatically: www.example.com and example.com are distinct values and both must be listed.

字型解析順序

Font resolution order

1. 該 Token 已套用的自訂字型中，family 相符者
2. 該 Token 所屬方案的字型庫中，family 相符者

1. Custom fonts applied to this token whose family matches
2. Fonts in the token's plan library whose family matches

兩者皆以 family 相符為前提，再從候選中挑字重最接近 weight 的一支。 自訂字型優先，因此以相同 family 上傳的自訂字型會覆蓋方案字型。

Both require a family match; the nearest weight to weight is then chosen from the candidates. Custom fonts take priority, so uploading a custom font under an existing family name overrides the plan font.

節流建議

Throttling

使用者輸入時不要每個按鍵都發請求。以 300–450 毫秒 debounce 合併，再一次送出。

Do not issue a request per keystroke. Coalesce with a 300–450 ms debounce and send once.

let timer;
input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(() => loadPreviewFont(input.value), 450);
});

錯誤參考

Error Reference

失敗一律回傳 success: false 與 error 字串。

Failures return success: false and an error string.

{ "success": false, "error": "domain not allowed" }

400

401

402

500

字型沒有變化

Fonts do not change

API 回 success: true 但畫面沒變，依序檢查：

When the API returns success: true but nothing renders differently, check in order:

1. CSS 的 font-family 是否與字型的 family 名稱完全相同，包含空白與全角字元
2. 是否有更後面的 CSS 規則覆蓋了 font-family
3. 是否同時載入了嵌入腳本又自己注入 @font-face，兩者互相覆蓋
4. 自訂字型是否已在主控台套用到這個專案

1. Whether the CSS font-family matches the family name exactly, including spaces and full-width characters
2. Whether a later CSS rule overrides font-family
3. Whether the embed script and your own @font-face injection are both present, overwriting each other
4. Whether the custom font has been applied to this project in the console