mirror of https://github.com/2234839/web-font.git synced 2026-09-04 23:02:27 +08:00

崮生（子虚） 140f84d3c7 feat: uni-app 插件 gs-webfont —— 字体按需加载（子集化）上线准备

- webfont-sdk 引擎修复两处并发池 bug（原版排队分支丢任务；闭包复用会让
  队列真身丢失导致 pending 卡死），新增 per-state provider 与 submitText 分批
- 新增 packages/uni-webfont：字符累积 + uni.loadFontFace 同 family 重载策略，
  串行保序（maxConcurrent=1），二次 loadFont 从引擎播种累积集
- 产物同步 uni_modules/gs-webfont/js_sdk（自包含 ESM+iife+d.ts）
- 端到端验证：mock 全绿；线上真实服务 4 字 → 10.1KB 合法 TTF

2026-08-16 10:34:40 +08:00

4.4 KiB

Raw Blame History

gs-webfont —— uni-app 字体按需加载（中文字体子集化）

任意中文字体，按页面实际用到的字符动态裁剪加载：10 个字 ≈ 10KB。突破小程序 2MB 主包限制，无需构建期裁字、无需整包下载 10MB+ 字体、文字改了零成本生效。

为什么需要它

中文字体动辄 5-20MB，而微信小程序主包限 2MB、整包下载超时白屏。官方文档的建议是 "抽离出部分中文，减少体积"——每改一次文案就得重新裁一次字体，文案一多就漏字。

gs-webfont 把裁字搬到运行时：把页面文字提交给子集化服务，服务端秒级裁出只含这些字的字体片段，uni.loadFontFace 注册生效。文案随便改，用多少加载多少。

方案	体积	文案可变	跨端
整包 ttf	5-20MB	✅	❌ 超主包限制
构建期裁字（fontmin 等）	小	❌ 改文案需重裁	✅
gs-webfont 运行时子集	按字符数	✅ 随便改	✅

快速开始

// 页面或 App.vue
import { UniWebFont } from '@/uni_modules/gs-webfont/js_sdk/index.js'

const loader = UniWebFont.loadFont({ fontName: '令东齐伋复刻体.ttf' })
loader.update('静心茶舍 今日特饮')

// 样式里直接用（family = 字体名去扩展名）
// <view style="font-family: 令东齐伋复刻体">静心茶舍</view>

首次 update 后字体异步生效，旧字形（系统字体）保持显示直到新字体就绪，无闪烁。

等待就绪（截图/导出场景）

loader.update('要渲染的文字')
await loader.ready()
// 此时字体必然已生效，再截图/生成 canvas

追加文本（打字机/动态内容）

loader.update('第一段文字')
loader.update('第二段文字')  // 引擎自动去重，只请求新出现的字

API

`UniWebFont.loadFont(options): IUniFontLoader`

参数	类型	默认	说明
`fontName`	`string`	—	字体文件名（服务端字体列表里可选，支持模糊匹配）
`baseUrl`	`string`	官方服务	私有部署地址
`family`	`string`	去扩展名字体名	CSS font-family 用的名字
`outType`	`'ttf' \| 'woff2'`	`'ttf'`	小程序建议 ttf（iOS 低版本 woff2 兼容差）
`global`	`boolean`	`true`	是否全局生效（微信 2.10.0+，在 App.vue 调用则全 app 生效）
`maxCharsPerChunk`	`number`	`300`	单次请求最大字符数，超出自动分批
`desc`	`object`	—	字体描述符（style/weight/variant）
`debug`	`boolean`	`false`	控制台输出加载日志

返回 loader：update(text) / isPending() / ready() / retryFailed() / dispose()。

`UniWebFont.ready()` / `hasPending()`

全部字体的就绪等待（多字体页面导出前用）。

平台兼容

平台	支持	说明
微信/支付宝/百度/抖音/QQ 小程序	✅	需把 `webfont.shenzilong.cn` 加入小程序后台 downloadFile 合法域名（https）
H5	✅	无需任何配置
App (vue/uvue)	✅
app-nvue	❌	平台不支持 loadFontFace，用 Weex DOM.addRule 自行处理

私有部署

插件默认使用官方免费服务 webfont.shenzilong.cn（Docker 一键部署见 web-font），商用或内网场景传 baseUrl 指向自建服务即可，插件零改动。

常见问题

Q: 字体加载失败？ 微信小程序需在 mp.weixin.qq.com 后台「开发管理 → 开发设置 → 服务器域名」把 https://webfont.shenzilong.cn 加入 downloadFile 合法域名（loadFontFace 内部走下载通道，不是 request 域名）。

Q: 为什么默认 ttf 不是 woff2？ 低版本 iOS 的 WebView 对 woff2 支持不全（官方文档），ttf 全端稳妥。纯 H5 场景可传 outType: 'woff2' 省约 30% 流量。

Q: 请求会带什么数据？ 仅「字体名 + 待渲染字符」，无用户信息。服务端按文本缓存，同文案只裁一次。

来源

源码：packages/uni-webfont（MIT）
服务端：web-font · 在线体验：webfont.shenzilong.cn

4.4 KiB Raw Blame History Unescape Escape