generateHandwriting

使用 Canvas 将文字渲染为手写体风格图片。文档站 Playground 默认加载内置「钟齐志莽行书」，调用方也可通过 loadHandwritingFont 传入自己的字体文件。

预览

字体加载中…

生成中...

文字

内容你好，手写体 Hello World

风格毛笔（brush）连笔（cursive）工整（neat）马克笔（marker）

对齐左对齐居中右对齐

字体

字体来源钟齐志莽行书（内置）上传字体文件系统字体

默认使用文档站内置「钟齐志莽行书」。调用方也可通过 loadHandwritingFont + fontFamily 传入自己的字体。

外观

字号 48

墨迹

背景

透明背景

笔迹

倾斜 6°

起伏 0.30

种子

字间距 1

行高 1.45

内边距 32

自定义描边

画布

自动尺寸

前置依赖

依赖参数

参数名	类型	说明
deps.createCanvas	(width: number, height: number) => CanvasLike	创建指定大小的 Canvas 对象

自定义字体

使用非系统字体时，需先生成前调用 loadHandwritingFont 加载字体，再在 generateHandwriting 中传入同名 fontFamily：

参数名	类型	说明
deps.loadFont	(options: LoadHandwritingFontOptions) => Promise<void>	加载字体（浏览器可用 FontFace 实现）

函数签名

function loadHandwritingFont(
  options: LoadHandwritingFontOptions,
  deps: LoadHandwritingFontDeps
): Promise<void>

function generateHandwriting(
  options: GenerateHandwritingOptions,
  deps: GenerateHandwritingDeps
): GenerateHandwritingResult

const ZHIMANG_XING_FONT_FAMILY = 'ZhiMangXing'

interface LoadHandwritingFontOptions {
  family: string
  source: string | ArrayBuffer
}

interface GenerateHandwritingOptions {
  text: string
  fontFamily?: string
  // ...其他选项见下表
}

使用自定义字体

import {
  generateHandwriting,
  loadHandwritingFont
} from '@zengchaowu/shared/functions/image/generateHandwriting'

async function browserLoadFont(family: string, source: string | ArrayBuffer) {
  const fontFace = new FontFace(family, typeof source === 'string' ? `url(${source})` : source)
  await fontFace.load()
  document.fonts.add(fontFace)
  await document.fonts.ready
}

await loadHandwritingFont(
  { family: 'MyHandFont', source: '/fonts/MyHandFont.ttf' },
  {
    loadFont: async ({ family, source }) => {
      const fontFace = new FontFace(family, typeof source === 'string' ? `url(${source})` : source)
      await fontFace.load()
      document.fonts.add(fontFace)
      await document.fonts.ready
    }
  }
)

const result = generateHandwriting(
  {
    text: '你好，世界',
    fontFamily: 'MyHandFont',
    variation: 0.3
  },
  { createCanvas }
)

传入 fontFamily 后会直接使用该字体绘制，并自动减弱叠墨特效，避免破坏字形。

参数

参数名	类型	必填	默认值	说明
options.text	string	是	-	要渲染的文字，支持 \n 换行
options.fontFamily	string	否	-	已加载的自定义字体 family
options.width	number	否	自动	画布宽度（像素）
options.height	number	否	自动	画布高度（像素）
options.fontSize	number	否	48	字号
options.color	string	否	#1a1a2e	墨迹颜色
options.backgroundColor	string	否	transparent	背景色，默认透明
options.style	HandwritingStyle	否	brush	未传 fontFamily 时的风格预设
options.slant	number	否	10	整体倾斜角度（度）
options.variation	number	否	0.55	笔迹起伏强度 0–1
options.seed	number	否	由文字哈希	相同 seed + 参数每次生成一致
deps	GenerateHandwritingDeps	是	-	环境依赖

工作原理

1. 调用方通过 loadHandwritingFont 注入字体加载逻辑（浏览器 FontFace、Node registerFont 等）
2. generateHandwriting 使用 fontFamily 指定的已加载字体；未传时回退到系统字体栈 + 叠墨特效
3. 逐字排版，支持多行与左/中/右对齐；透明背景默认开启

内置字体（文档站）

Playground 内置 docs/public/fonts/ZhiMangXing-Regular.ttf（钟齐志莽行书），仅供文档演示。生产环境请自行准备有合法授权的字体文件。