SDK 集成文档

为你的网站接入中文字体按需加载

原理：服务端根据 text 参数裁剪字体，只返回所需字符的子集。相同 URL 的请求会被浏览器自动缓存。

基础用法：将 CSS 复制到你的页面，修改 text 参数中的文字即可：

<style>
@font-face {
  font-family: "MyFont";
  src: url("/api?font=字体名&text=你的文字") format("woff2");
}
.title { font-family: "MyFont"; }
</style>
<h1 class="title">你的文字</h1>

JS SDK（推荐）：增量加载字体片段，按需请求，不会出现全量字体闪烁。下载 SDK

<script src="/webfont-sdk.js"></script>

<h1 class="title">你的文字</h1>
<p class="content">输入任意文字，SDK 自动裁剪加载</p>

<script>
  WebFont.observeFont({
    fontName: "字体文件名.ttf",
    selector: ".title, .content",
    family: "MyFont",
  });
</script>

还支持WebFont.observeFont()（MutationObserver 事件驱动）和WebFont.loadText()（手动传文本）两种方式，多种方式可同时使用，SDK 内部自动按字体去重增量加载。

npm 包（推荐，工程化项目）：安装 webfont-sdk 后可在任意前端工程 / Node 项目中使用，支持 DOM（CSS 模式）与 Canvas（FontFace 模式）：

npm install webfont-sdk

import { WebFont, WebFontCanvas } from 'webfont-sdk'

// DOM 场景：自动观察元素内文字，增量加载
const obs = WebFont.observeFont({
  fontName: '字体文件名.ttf',
  selector: '.title',
  family: 'MyFont',
  baseUrl: '',
})

// Canvas 场景（leafer / fabric / 原生 canvas）
const face = WebFontCanvas.loadFontFace(
  { fontName: '字体文件名.ttf' },
  () => redraw(), /* 片段就绪，重绘 */
)
face.update('画布上的文字')
await WebFontCanvas.ready()

服务端 API 客户端：字体列表 / 元数据 / 上传 / 统计等 REST 接口封装在独立子路径，供字体选择器等场景使用：

import { createWebFontApi } from 'webfont-sdk/api'

const api = createWebFontApi({ baseUrl: '' })

const fonts = await api.fonts()          // 字体列表
const meta = await api.fontMeta('字体名') // 覆盖率 / codepoint 区间
const r = await api.upload({ data: file, filename: '我的字体.ttf' })
if (!r.success) console.error(r.error)