公式与符号

#数学公式

Math API 允许使用 OOXML 的 Office 数学标记语言（OMML）构建数学公式。

#基本公式

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "math": {
                  "equations": [
                    ["x", " = ", { "fraction": { "numerator": ["a + b"], "denominator": ["c"] } }]
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                math: {
                  equations: [
                    ["x", " = ", { fraction: { numerator: ["a + b"], denominator: ["c"] } }],
                  ],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

#复杂公式

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              {
                "math": {
                  "equations": [
                    [
                      "x",
                      " = ",
                      {
                        "sum": {
                          "children": [
                            { "superScript": { "children": ["x"], "superScript": ["2"] } }
                          ],
                          "subScript": ["i=0"],
                          "superScript": ["n"]
                        }
                      }
                    ]
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              {
                math: {
                  equations: [
                    [
                      "x",
                      " = ",
                      {
                        sum: {
                          children: [{ superScript: { children: ["x"], superScript: ["2"] } }],
                          subScript: ["i=0"],
                          superScript: ["n"],
                        },
                      },
                    ],
                  ],
                },
              },
            ],
          },
        },
      ],
    },
  ],
});

#数学组件

组件	说明
`math`	根公式容器
`fraction`	分数（分子/分母）
`subScript`	下标表示法
`superScript`	上标表示法
`subSuperScript`	上下标组合
`radical`	平方根和 n 次根
`sum`	求和符号（∑）
`integral`	积分符号（∫）
`limitLower`	下极限表示法
`limitUpper`	上极限表示法
`function`	命名函数（如 sin、cos）
`matrix`	矩阵（行和列）
`roundBrackets`	圆括号分组
`curlyBrackets`	花括号分组
`accent`	重音符号（帽子、波浪号等）
`bar`	上划线/下划线
`eqArr`	公式数组（对齐的公式）
`borderBox`	表达式边框框
`box`	带运算符模拟的框
`groupChr`	组字符（大括号、方括号）
`phant`	占位符（不可见占位）

#公式中的文本

在 JSON API 中，公式文本可以直接使用字符串，或使用 { "text": "x" } 表示带样式的公式文本：

json

{ "math": { "children": ["x", " = ", { "text": "y" }] } }

#MathFraction

分子和分母接受 MathComponent[] 数组：

json

{ "fraction": { "numerator": ["a + b"], "denominator": ["b"], "fractionType": "bar" } }

fractionType 可选值："bar"（默认）、"skw"、"lin"、"noBar"。

#MathRadical

json

{ "radical": { "children": ["x + y"], "degree": ["3"] } }

degree 为可选字段，指定 n 次根的次数。

#MathSubScript / MathSuperScript / MathSubSuperScript

json

{ "subScript": { "children": ["x"], "subScript": ["i"] } }
{ "superScript": { "children": ["x"], "superScript": ["2"] } }
{ "subSuperScript": { "children": ["x"], "subScript": ["i"], "superScript": ["2"] } }

#MathSum / MathIntegral

json

{ "sum": { "children": ["x"], "subScript": ["i=0"], "superScript": ["n"] } }
{ "integral": { "children": ["f(x)"], "subScript": ["a"], "superScript": ["b"] } }

#MathLimitLower / MathLimitUpper

json

{ "limitLower": { "children": ["lim"], "limit": ["x→0"] } }

#MathFunction

json

{ "function": { "name": ["sin"], "children": ["x"] } }

#MathMatrix

json

{
  "matrix": {
    "rows": [
      ["a", "b"],
      ["c", "d"]
    ]
  }
}

#括号

所有括号类型都生成 m:d 分隔符元素，使用不同的字符：

json

{ "roundBrackets": ["x + y"] }
{ "squareBrackets": ["x"] }
{ "curlyBrackets": ["a", "b"] }
{ "angledBrackets": ["x"] }

#Math Accent

用于重音符号（帽子、波浪号等）：

json

{ "accent": { "children": ["x"], "accentCharacter": "^" } }

accentCharacter 可选值："^" 表示帽子，"~" 表示波浪号等。

#Math Bar

用于上划线/下划线：

json

{ "bar": { "children": ["x"], "type": "top" } }

type 可选值："top" 或 "bot"。

#MathEqArr

用于对齐公式的公式数组：

json

{
  "eqArr": {
    "rows": [
      ["a", "=", "b + c"],
      ["d", "=", "e + f"]
    ]
  }
}

#MathBorderBox

在表达式周围绘制边框，可配置边框和删除线：

json

{ "borderBox": { "children": ["a"] } }

隐藏上边框和下边框：

json

{ "borderBox": { "children": ["b"], "properties": { "hideTop": true, "hideBottom": true } } }

BorderBox 属性

属性	类型	说明
`hideTop`	`boolean`	隐藏上边框
`hideBottom`	`boolean`	隐藏下边框
`hideLeft`	`boolean`	隐藏左边框
`hideRight`	`boolean`	隐藏右边框
`strikeHorizontal`	`boolean`	水平删除线
`strikeVertical`	`boolean`	垂直删除线
`strikeDiagonalUp`	`boolean`	从左下到右上的对角线
`strikeDiagonalDown`	`boolean`	从左上到右下的对角线

#MathBox

将内容包裹在框中，可选择模拟运算符行为：

json

{ "box": { "children": ["x + y"] } }

#MathGroupChr

在内容上方或下方添加分组字符（大括号、方括号等）：

json

{ "groupChr": { "children": ["a", "b"] } }

可选 properties 字段：

属性	类型	说明
`chr`	`string`	分组字符（默认 `"{"`）
`pos`	`string`	位置：`"top"` 或 `"bot"`
`vertJc`	`string`	垂直对齐：`"top"` 或 `"bot"`

#MathPhantom

创建用于间距控制的不可见占位符：

json

{ "phant": { "children": ["dy"] } }

#高级数学属性

除上述基础组件外，若干数学元素支持 properties 块用于精细控制。

#分隔符属性

括号类型（roundBrackets、squareBrackets、curlyBrackets、angledBrackets）接受对象形式，含 children 和 properties，可自定义字符、分隔符和拉伸：

{
  roundBrackets: {
    children: [{ text: "a, b, c" }],
    properties: {
      beginCharacter: "(",
      endCharacter: ")",
      separatorCharacter: ",",
      grow: true,
      shape: "centered", // "centered" | "match"
    },
  },
}

属性	类型	说明
`beginCharacter`	`string`	起始字符
`endCharacter`	`string`	结束字符
`separatorCharacter`	`string`	元素分隔符
`grow`	`boolean`	随内容高度拉伸
`shape`	`"centered" \| "match"`	分隔符形状

#N-ary 属性（sum / integral）

控制上下标极限位置以及操作符是否拉伸：

json

{
  "sum": {
    "children": [
      {
        "text": "x"
      }
    ],
    "subScript": [
      {
        "text": "i=0"
      }
    ],
    "superScript": [
      {
        "text": "n"
      }
    ],
    "properties": {
      "limitLocation": "undOvr",
      "grow": true
    }
  }
}

属性	类型	说明
`limitLocation`	`"subSup" \| "undOvr"`	极限相对操作符的位置
`grow`	`boolean`	操作符随内容拉伸

#分式参数字号

独立缩放分子/分母字号：

json

{
  "fraction": {
    "numerator": [
      {
        "text": "1"
      }
    ],
    "denominator": [
      {
        "text": "2"
      }
    ],
    "numeratorArgumentSize": 80,
    "denominatorArgumentSize": 80
  }
}

#上下标对齐

{
  subSuperScript: {
    children: [{ text: "x" }],
    subScript: [{ text: "i" }],
    superScript: [{ text: "2" }],
    alignScript: true,
  },
}

#符号字符

在段落中插入 Wingdings 等符号字体的字符：

JSON

{
  "sections": [
    {
      "children": [
        {
          "paragraph": {
            "children": [
              "箭头：",
              { "symbolRun": { "char": "F021", "symbolFont": "Wingdings" } },
              " 勾选：",
              { "symbolRun": { "char": "F052", "symbolFont": "Wingdings" } }
            ]
          }
        }
      ]
    }
  ]
}

TypeScript

import { generateDocument } from "@office-open/docx";

await generateDocument({
  sections: [
    {
      children: [
        {
          paragraph: {
            children: [
              "箭头：",
              { symbolRun: { char: "F021", symbolFont: "Wingdings" } },
              " 勾选：",
              { symbolRun: { char: "F052", symbolFont: "Wingdings" } },
            ],
          },
        },
      ],
    },
  ],
});

#SymbolRun 选项

选项	类型	说明
`char`	`string`	十六进制字符代码（如 `"F021"`）
`symbolFont`	`string`	字体名称（默认 `"Wingdings"`）
`bold`	`boolean`	粗体
`italic`	`boolean`	斜体
`color`	`string`	十六进制颜色代码
`size`	`number`	字号（磅）

#拼音标注

拼音标注为东亚文字提供发音指南（假名、拼音等）：

json

{
  "paragraph": {
    "children": [
      {
        "ruby": {
          "properties": {
            "alignment": "center",
            "fontSize": 10,
            "raise": 4,
            "baseFontSize": 18,
            "languageId": "ja-JP"
          },
          "base": { "children": ["漢字"] },
          "text": { "children": ["かんじ"] }
        }
      },
      {
        "ruby": {
          "properties": {
            "alignment": "center",
            "fontSize": 10,
            "raise": 4,
            "baseFontSize": 18,
            "languageId": "zh-CN"
          },
          "base": { "children": ["汉字"] },
          "text": { "children": ["hànzì"] }
        }
      }
    ]
  }
}

#拼音标注选项

属性	类型	说明
`properties`	`RubyPropertiesOptions`	必需的拼音布局属性
`base`	`RubyContentOptions`	格式化的基础文本 run
`text`	`RubyContentOptions`	格式化的标注文本 run

RubyPropertiesOptions 需要 alignment、fontSize、raise、baseFontSize 和 languageId；dirty 可选。