# ldesign-webfont

**Repository Path**: ldesign-v1/ldesign-webfont

## Basic Information

- **Project Name**: ldesign-webfont
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# unplugin-webfont

`unplugin-webfont` 是一个面向前端工程的字体与 SVG 资产工具包，覆盖三类核心场景：

- 把 `ttf`、`otf`、`woff`、`woff2` 转成适合网页分发的 Webfont。
- 基于文本做字体子集化，显著缩小中文或多语言字体体积。
- 把一批 SVG 图标批量生成 Icon Font 或多框架组件库。

它同时提供 `unplugin`
插件、CLI 命令和可复用的服务层 API，适合在 Vite、Webpack、Rollup、脚本工具链和 CI 流程里复用。

## 功能概览

- 支持输入格式：`ttf`、`otf`、`woff`、`woff2`
- 支持输出格式：`woff2`、`woff`、`ttf`
- 支持生成 `@font-face` CSS，并自动把 `ttf` 映射为 `format('truetype')`
- 支持基于文本和文本文件做去重子集化
- 支持把 SVG 目录生成 Icon Font、CSS、预览页和映射 JSON
- 支持把 SVG 目录生成 Vue 2、Vue 3、React、Svelte、Solid、Preact、Lit 组件
- 支持重名检测，避免不同目录下同名字体或图标互相覆盖
- 支持 `--dry-run` 预览产物、内容未变化自动跳过、`--force` 强制重写和可调并发
- 支持 `onArtifact` 钩子接入自定义日志、缓存、遥测或二次发布流程
- 支持 `unplugin` 方式接入构建流程，也支持纯脚本 API

## 安装

```bash
pnpm add -D unplugin-webfont
```

或：

```bash
npm install -D unplugin-webfont
```

## 快速开始

### 1. 在 Vite 中处理字体

```ts
import { defineConfig } from 'vite'
import Webfont from 'unplugin-webfont/vite'

export default defineConfig({
  plugins: [
    Webfont({
      include: './fonts/*.{ttf,otf}',
      text: '你好世界Hello World',
      formats: ['woff2', 'woff'],
      outputDir: 'public/fonts',
      cssOutput: true,
      fontDisplay: 'swap',
      concurrency: 4,
      onArtifact(artifact) {
        console.log(`${artifact.status}: ${artifact.relativePath}`)
      },
    }),
  ],
})
```

### 2. 在命令行里做字体转换

```bash
webfont convert "./fonts/*.ttf" --output ./dist/fonts --formats woff2,woff --css
```

### 3. 在命令行里做字体子集化

```bash
webfont subset "./fonts/*.ttf" --text "你好世界Hello" --output ./dist/fonts --formats woff2,woff --css
```

### 4. 把 SVG 图标生成 Icon Font

```bash
webfont svg2font "./icons/**/*.svg" --output ./dist/iconfont --name app-icons --formats woff2,woff,ttf
```

### 5. 把 SVG 图标生成组件库

```bash
webfont svg2component "./icons/**/*.svg" --framework vue3 --output ./dist/icons --prefix Icon
```

## CLI 命令

| 命令                            | 说明                     | 常用参数                                              |
| ------------------------------- | ------------------------ | ----------------------------------------------------- |
| `webfont convert <input>`       | 批量转换字体格式         | `--output` `--formats` `--font-family` `--css`        |
| `webfont subset <input>`        | 批量做字体子集化         | `--text` `--text-file` `--output` `--formats` `--css` |
| `webfont info <input>`          | 输出字体详细分析报告     | 无                                                    |
| `webfont svg2font <input>`      | 批量生成 Icon Font       | `--output` `--name` `--formats` `--prefix`            |
| `webfont svg2component <input>` | 批量生成组件源码或组件包 | `--framework` `--output` `--prefix` `--package`       |

生成类命令都支持 `--dry-run`、`--force` 和 `--concurrency <count>`：

- `--dry-run` 只返回将要生成的产物清单，不创建输出目录。
- 默认会跳过内容未变化的产物，状态显示为 `skipped`。
- `--force` 会强制重写所有产物。
- `--concurrency` 会被收敛到 `1-32`，用于稳定控制批量任务吞吐。

## `unplugin` 模式

### Vite

```ts
import { defineConfig } from 'vite'
import Webfont from 'unplugin-webfont/vite'

export default defineConfig({
  plugins: [
    Webfont({
      mode: 'svg-to-component',
      svg: {
        src: './icons/**/*.svg',
        framework: 'react',
        outputDir: './src/generated/icons',
        componentPrefix: 'Icon',
        typescript: true,
      },
    }),
  ],
})
```

### Webpack

```js
const Webfont = require('unplugin-webfont/webpack').default

module.exports = {
  plugins: [
    Webfont({
      include: './fonts/*.ttf',
      formats: ['woff2', 'woff'],
      outputDir: './public/fonts',
    }),
  ],
}
```

### Rollup

```ts
import Webfont from 'unplugin-webfont/rollup'

export default {
  plugins: [
    Webfont({
      mode: 'iconfont',
      svg: {
        src: './icons/**/*.svg',
      },
      iconfont: {
        fontName: 'app-icons',
        outputDir: './dist/iconfont',
      },
    }),
  ],
}
```

## 服务层 API

如果你不想走 CLI，也可以直接在脚本里调用服务函数。

### 构建 Webfont

```ts
import { buildWebfonts } from 'unplugin-webfont/services'

const result = await buildWebfonts({
  cwd: process.cwd(),
  fontFiles: ['./fonts/SourceHanSans-Regular.otf'],
  text: '你好世界Hello',
  formats: ['woff2', 'woff'],
  outputDir: './dist/fonts',
  cssOutput: './dist/fonts/fonts.css',
  dryRun: false,
  force: false,
  concurrency: 4,
  onArtifact(artifact) {
    console.log(`${artifact.status}: ${artifact.relativePath}`)
  },
})

console.log(result.artifacts)
```

### 构建 Icon Font

```ts
import { buildIconfont } from 'unplugin-webfont/services'

await buildIconfont({
  cwd: process.cwd(),
  src: './icons/**/*.svg',
  fontName: 'app-icons',
  outputDir: './dist/iconfont',
  formats: ['woff2', 'woff', 'ttf'],
  generateCSS: true,
  generatePreview: true,
  dryRun: false,
})
```

### 构建 SVG 组件库

```ts
import { buildComponentLibrary } from 'unplugin-webfont/services'

await buildComponentLibrary({
  cwd: process.cwd(),
  src: './icons/**/*.svg',
  framework: 'vue3',
  outputDir: './dist/icons',
  componentPrefix: 'Icon',
  typescript: true,
  concurrency: 8,
})
```

## 导出结构

| 入口                        | 说明                               |
| --------------------------- | ---------------------------------- |
| `unplugin-webfont`          | 主入口，包含默认插件和常用能力导出 |
| `unplugin-webfont/vite`     | Vite 插件入口                      |
| `unplugin-webfont/webpack`  | Webpack 插件入口                   |
| `unplugin-webfont/rollup`   | Rollup 插件入口                    |
| `unplugin-webfont/services` | 服务层 API                         |
| `unplugin-webfont/font`     | 字体相关能力                       |
| `unplugin-webfont/svg`      | SVG 相关能力                       |
| `unplugin-webfont/utils`    | 通用工具函数                       |
| `unplugin-webfont/types`    | TypeScript 类型定义                |

## 生成策略与约束

- 字体转换统一先归一为 TTF，再输出到目标格式，逻辑更稳定。
- `cssOutput` 为字符串时会生成一份聚合 CSS，不会因为循环覆盖导致只保留最后一个字体。
- SVG 组件生成默认把内部 SVG 标记作为静态字符串注入，降低 JSX / 模板属性兼容问题。
- 构建阶段会拦截重名文件，避免两个 `home.svg` 或两个 `regular.ttf` 静默覆盖。
- 组件库索引文件使用无扩展名导出，避免 TypeScript 工程额外打开 `allowImportingTsExtensions`。

## 开发脚本

```bash
pnpm run type-check
pnpm run lint:check
pnpm run build
pnpm run test:run
pnpm run verify
```

说明：

- 构建流程直接使用 `@composy/pack` 的零配置入口：`pack build && pack verify`
- `pack build` 会按 `package.json` 和 `src/` 约定自动推断入口，并同时生成 ESM、CJS 和 DTS
- `pack verify` 会校验 `package.json` 中声明的公开导出目标是否真实存在
- `bin/cli.mjs` 是轻量包装入口，运行时会加载 `dist/cli/index.cjs`

## 目录结构

```text
src/
  cli/          命令行入口与子命令
  constants/    常量和默认配置
  errors/       错误类型
  font/         字体检测、转换、子集化、分析、CSS 生成
  services/     可复用的高层构建服务
  svg/          SVG 解析、组件生成、Icon Font 生成
  unplugin/     Vite / Webpack / Rollup 入口
  utils/        通用工具函数
  types/        类型定义
```

## 适用场景

- 设计系统图标库构建
- 中文或多语言 Webfont 子集化
- SVG 资产转多框架组件源码
- 字体和图标资源的 CI 自动化处理

## License

MIT

## 通过 `@composy/cli` 统一接入

<!-- ldesign-cli-integration:start -->

- 接入类型：`bin`
- 统一命令：`ldesign webfont`
- 命令别名：无
- 包内原生 bin：`webfont`

当前包通过独立 bin 接入，统一命令会转发到包自身 CLI。

```bash
pnpm add -D @composy/cli
ldesign webfont --help
ldesign tools run webfont --help
```

<!-- ldesign-cli-integration:end -->