HumanBreak/docs/api/motajs-render-style/Font.md

Font API 文档

本文档由 DeepSeek R1 模型生成并微调。

---

graph LR
    Font --> IFontConfig

实现 IFontConfig 接口，表示字体配置。

---

接口说明

IFontConfig

interface IFontConfig {
    family: string; // 字体名称（如 "Arial"）
    size: number; // 字号数值
    sizeUnit: string; // 字号单位（推荐 "px"）
    weight: number; // 字重（0-1000）
    italic: boolean; // 是否斜体
}

FontWeight 枚举

enum FontWeight {
    Light = 300, // 细体
    Normal = 400, // 常规
    Bold = 700 // 粗体
}

---

属性说明

属性名	类型	描述
family	string	字体家族名称（只读）
size	number	字号数值（只读）
sizeUnit	string	字号单位（如 "px"，只读）
weight	number	字重数值（只读）
italic	boolean	是否斜体（只读）

---

构造方法

constructor

function constructor(
    family?: string,
    size?: number,
    sizeUnit?: string,
    weight?: number,
    italic?: boolean
): Font;

创建字体实例，参数默认使用静态默认值。
示例：

const font = new Font('Arial', 14, 'px', FontWeight.Bold, true);

---

方法说明

addFallback

function addFallback(...fallback: Font[]): void;

添加后备字体（当主字体不可用时使用）。
注意： 检测到递归添加时会触发 logger.warn(62) 警告。
示例：

const mainFont = new Font('CustomFont');
const fallback1 = new Font('Arial');
const fallback2 = new Font('Helvetica');
mainFont.addFallback(fallback1, fallback2); // 添加两个后备

string

function string(): string;

生成 CSS 字体字符串，包含后备字体。
示例：

console.log(font.string()); // 示例输出："italic 700 14px CustomFont, 400 16px Arial"

---

静态方法说明

Font.parse

function parse(str: string): Font;

解析 CSS 字体字符串（支持多字体声明）。
示例：

const parsed = Font.parse('italic 16px "Fira Sans", Arial');
// 主字体：Fira Sans，后备：Arial

Font.setDefaults

function setDefaults(font: Font): void;

全局设置默认字体参数。
示例：

Font.setDefaults(new Font('Segoe UI', 14, 'px', 400, false));

Font.clone

function clone(font: Font, options: Partial<IFontConfig>): Font;

克隆字体并修改指定属性。
示例：

const cloned = Font.clone(baseFont, {
    size: 18,
    weight: FontWeight.Bold
});

---

总使用示例

// 创建主字体
const mainFont = new Font('CustomFont', 16, 'px', FontWeight.Normal);

// 添加后备字体（注意避免循环引用）
const fallbackA = new Font('Arial');
const fallbackB = new Font('Helvetica');
fallbackA.addFallback(fallbackB);
// 错误示例（触发警告62）:
// fallbackB.addFallback(fallbackA);

mainFont.addFallback(fallbackA);

// 生成 CSS 字符串
console.log(mainFont.string());
// 输出: "400 16px CustomFont, 400 16px Arial, 400 16px Helvetica"

// 解析 CSS 字符串
const parsed = Font.parse('italic 700 24px Fantasy, "Comic Sans"');
parsed.addFallback(new Font('Verdana'));

// 克隆并修改
const boldFont = Font.clone(parsed, {
    weight: FontWeight.Bold,
    italic: false
});