sarasa-gothic-webfont

v0.4.0

Published

18 days ago

Build-time integrations for Unicode-range Sarasa Gothic webfonts.

0High
0Medium
0Low

haytham831

sarasa-gothic-webfont

更纱黑体 UI（Sarasa UI）的构建期 Web 字体下载器，提供 Next.js、Vite 自动集成和通用 CLI。

npm 包只包含 API、CLI 和带 SHA-256 的字体制品清单。应用构建前根据配置下载所选字重；生成的 CSS 使用 Unicode Range，浏览器仍只请求页面实际使用字符对应的 WOFF2 分片。

字体来自 Sarasa Gothic。

安装

pnpm add sarasa-gothic-webfont

Next.js

Next.js 16 可以在构建配置中选择字重。适配器会在 next dev 和 next build 启动时准备字体，并为 Turbopack 和 Webpack 自动加载生成的样式。

// next.config.mjs
import { withSarasa } from "sarasa-gothic-webfont/next/config";

export default withSarasa({
  uiSc: {
    weights: [400, 600],
  },
});

已有 Next.js 配置时，通过第二个参数传入：

import { withSarasa } from "sarasa-gothic-webfont/next/config";

const nextConfig = {
  reactStrictMode: true,
};

export default withSarasa(
  {
    uiSc: {
      weights: [400, 600],
    },
  },
  nextConfig,
);

在根布局中使用字体：

import { Sarasa_UI_SC } from "sarasa-gothic-webfont/next";

const sarasaUiSc = Sarasa_UI_SC();

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="zh-CN" className={sarasaUiSc.className}>
      <body>{children}</body>
    </html>
  );
}

Next.js 集成不需要运行 prepare、创建字体配置文件或导入生成的 CSS。下载内容和生成文件都位于 node_modules/.cache/sarasa-gothic-webfont。

Vite

在 Vite 配置中选择字重。插件会在 vite dev 和 vite build 启动时准备字体，并自动加载生成的样式：

// vite.config.ts
import { defineConfig } from "vite";
import { sarasa } from "sarasa-gothic-webfont/vite/config";

export default defineConfig({
  plugins: [
    sarasa({
      uiSc: {
        weights: [400, 600],
      },
    }),
  ],
});

在应用入口使用字体：

import { Sarasa_UI_SC } from "sarasa-gothic-webfont/vite";

const sarasaUiSc = Sarasa_UI_SC();

document.documentElement.classList.add(sarasaUiSc.className);

Storybook 使用 Vite builder 时，将同一个插件加入 .storybook/main.ts：

import type { StorybookConfig } from "@storybook/nextjs-vite";
import { mergeConfig } from "vite";
import { sarasa } from "sarasa-gothic-webfont/vite/config";

const config: StorybookConfig = {
  framework: "@storybook/nextjs-vite",
  async viteFinal(config) {
    return mergeConfig(config, {
      plugins: [
        sarasa({
          uiSc: {
            weights: [400, 600],
          },
        }),
      ],
    });
  },
};

export default config;

然后在 .storybook/preview.tsx 从 Vite 入口导入 Sarasa_UI_SC，把返回的 className 或 variable 应用到全局 decorator。

Vite 集成不需要运行 prepare、创建字体配置文件或导入生成的 CSS。下载内容和生成文件都位于 node_modules/.cache/sarasa-gothic-webfont。

通用构建工具

其他构建工具可以使用 CLI。在项目根目录创建 sarasa-font.config.mjs：

import { defineConfig } from "sarasa-gothic-webfont/config";

export default defineConfig({
  outDir: "src/generated/sarasa-fonts",
  families: {
    "ui-sc": {
      weights: [400, 600],
    },
  },
});

Sarasa UI SC 提供以下正体字重：200、300、400、600、700。

将生成目录加入项目的 .gitignore：

src/generated/sarasa-fonts/

在应用构建前准备字体：

{
  "scripts": {
    "fonts": "sarasa-gothic-webfont prepare",
    "predev": "pnpm fonts",
    "prebuild": "pnpm fonts"
  }
}

下载缓存默认位于 node_modules/.cache/sarasa-gothic-webfont。可通过配置中的 cacheDir 改为另一个项目内相对路径。

使用生成的字体

在应用的全局入口导入生成的样式表，然后使用组件式 API：

import "@/generated/sarasa-fonts/index.css";
import { Sarasa_UI_SC } from "sarasa-gothic-webfont";

const sarasaUiSc = Sarasa_UI_SC();

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="zh-CN" className={sarasaUiSc.className}>
      <body>{children}</body>
    </html>
  );
}

Sarasa_UI_SC() 返回 className、variable 和 style。使用 CSS 变量时，将 variable 添加到父元素，并通过 var(--font-sarasa-ui-sc) 引用字体栈。

如果配置文件使用其他名称或位置，可以显式指定：

sarasa-gothic-webfont prepare --config config/fonts.mjs

构建行为

只下载配置中明确选择的 family 和 weight。
Next.js 适配器同时支持 Turbopack 和 Webpack。
Vite 适配器支持开发服务器和生产构建，包括使用 Vite builder 的 Storybook。
每个归档在解包前核对字节数和 SHA-256。
缓存校验失败时重新下载，不使用损坏文件。
生成目录通过临时目录替换，失败时保留上一次可用输出。
不在 postinstall 阶段联网，也不修改安装后的包目录。

维护

pnpm install
pnpm run build
pnpm run build:assets
pnpm test
pnpm pack --dry-run

build 从 font-source.json 指定的官方发行文件重建 WOFF2 分片；build:assets 为每个字重生成独立归档并更新 font-assets.json。发布 npm 版本前，对应的字体归档必须已上传到清单中的 GitHub Release。

许可证

字体归档和仓库 fonts/ 下的生成文件使用 SIL Open Font License 1.1。
其余原创代码和文档使用 MIT License。

完整授权范围和许可证文本见 LICENSE。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

sarasa-gothic-webfont

安装

Next.js

Vite

通用构建工具

使用生成的字体

构建行为

维护

许可证