Built-in Functions

本文记录当前 core FunctionRegistry 实际注册的 Function。未列出的名称不是 built-in，调用时会产生 unknown function 诊断。

签名总览

text(value: String) -> Content
paragraph(body: Content) -> Content
ref(target: String) -> Content
heading(level: Int = 1, body: Content) -> Content
raw(text: String, lang: String? = none) -> Content
code(text: String, lang: String? = none, block: Bool = false) -> Content
quote(attribution: Content? = none, body: Content) -> Content
callout(kind: String = "note", title: Content? = none, body: Content) -> Content
details(summary: Content? = none, open: Bool = false, body: Content) -> Content
list(body: Content) -> Content
enum(body: Content) -> Content
list::item(body: Content) -> Content
enum::item(value: Int? = none, body: Content) -> Content
task(body: Content) -> Content
task::item(checked: Bool = false, body: Content) -> Content
table::cell(colspan: Int = 1, rowspan: Int = 1, body: Content) -> Content
table(columns: Int, header: Bool = false, align: String? = none, caption: Content? = none, body: Content) -> Content
strong(body: Content) -> Content
emph(body: Content) -> Content
strike(body: Content) -> Content
underline(body: Content) -> Content
kbd(body: Content) -> Content
math(text: String, block: Bool = false) -> Content
link(destination: String, title: String? = none, body: Content) -> Content
image(source: String, alt: String = "", title: String? = none, width: Int? = none, height: Int? = none) -> Content
figure(source: String, alt: String = "", title: String? = none, caption: Content) -> Content
linebreak() -> Content
parbreak() -> Content
rule() -> Content
pagebreak() -> Content

签名中的 body: Content 通常是 trailing Content 参数，因此在调用末尾写成 [...]。命名参数使用 name=value：

#heading(level=2)[标题]
#link(destination="https://example.com", title="示例站点")[打开]

文本、段落与引用

text 构造不会再次解析 Markup 的普通文本。paragraph 显式构造只包含 inline Content 的段落。普通文本和空行分别是它们更自然的宿主写法。

普通文本会自然组成段落。

#paragraph[显式段落可以包含 *加粗* 与 _斜体_。]
#text("*这里的星号保持原样*")

ref 指向 Module 或 label。Wiki Reference 是知识库书写时的语法糖：

[[guide::intro#overview]]
#ref("guide::intro#overview")

Heading

heading 的 level 必须位于 1..=6。标题属于高频块结构，因此保留 Typst 风格的 = 语法：

= 一级标题
== 二级标题

#heading(level=3)[三级标题]

不支持 Markdown Setext 标题。

Raw 与 Code

raw 和 code 都保存未经 Markup 解析的 String。code.block 显式选择 inline 或 block 输出；lang 是可选语言标识。

`inline raw`

```rust
fn main() {}
```

#code(text="let answer = 42", lang="rust")
#code(text="fn main() {}", lang="rust", block=true)

Backtick 与 fenced Raw 是宿主语法。raw 和 code 不接受 trailing Content，源码必须作为 String 参数传入。

Quote

quote 表示真正的转述或摘录。attribution 接受可选 Content，因此可以包含格式或引用：

#quote[
  Knowledge is power.
]

#quote(attribution=[Francis Bacon])[
  Knowledge is power.
]

Quote 不提供 > 语法糖；> 保持为普通文本。

Callout 与 Details

callout 表示作者自己的提示性内容。kind 是供主题和导出使用的稳定分类，默认为 note；title 是可选 Content。

#callout[
  这是一条普通提示。
]

#callout(kind="warning", title=[保存前检查])[
  请确认配置已经写入磁盘。
]

details 只负责折叠状态。summary 是可选 Content，open 默认为 false；HTML renderer 在 summary 为 none 时使用通用的 Details 标题。

#details(summary=[查看详情])[
  默认折叠的内容。
]

#details(open=true)[
  初始展开的内容。
]

可折叠 Callout 由外层 Callout 提供语义和样式，内层 Details 控制展开：

#callout(kind="warning", title=[风险说明])[
  #details(summary=[查看详情])[
    这里是折叠的警告内容。
  ]
]

Callout 与 Details 都不提供 !!!、??? 或 > 简写。

Inline Content

常用 inline Function 与宿主语法如下：

这段文字包含 *加粗*、_斜体_、__下划线__ 和 ~~删除线~~。

按下 #kbd[Ctrl + S] 保存。

kbd 的显式调用已经足够简洁，因此不增加定界符。

List、Enum 与 Task

显式容器只接受对应的 item Element：

#list[
  #list::item[Alpha]
  #list::item[Beta]
]

#enum[
  #enum::item[First]
  #enum::item[Second]
]

#task[
  #task::item[待处理]
  #task::item(checked=true)[已完成]
]

日常书写使用更紧凑的宿主语法：

- Alpha
- Beta

+ First
+ Second

- [ ] 待处理
- [x] 已完成

缩进可以构造嵌套列表或 Task。

Math

math 保存公式源码，block 决定 inline 或 block。$...$ 与 $$...$$ 是高频公式的宿主语法：

行内公式 $x^2 + y^2$。

$$
E = mc^2
$$

#math("x^2 + y^2")
#math("E = mc^2", block=true)

Link、Image 与 Figure

link 使用 trailing Content 作为可见文本。裸 HTTP(S) URL 会自动产生 Link；Markdown 的 [label](url) 不是 Notist 语法。

https://example.com
#link("https://example.com")[示例站点]

图片和图注使用显式 Function：

#image(source="images/flow.png", alt="流程图", width=640)

#figure(source="images/flow.png", alt="流程图")[
  构建流程
]

Video 与 Audio 不属于 core，后续由 media plugin 提供。

Table

显式 Table 适合动态构造，Pipe Table 适合直接阅读和维护：

#table(columns=2, header=true, align="left,right", caption=[库存])[
  #table::cell[名称]
  #table::cell[数量]
  #table::cell[Apple]
  #table::cell[2]
]

| 名称 | 数量 |
| --- | ---: |
| Apple | 2 |

colspan 与 rowspan 必须是正整数。align 是与列数相同的逗号分隔列表，成员为 left、center、right 或 default。

Break

第一行\
仍在同一段落。

#linebreak()
#parbreak()
#rule()
#pagebreak()

行末反斜线是 linebreak 的高频语法糖。rule 当前只提供显式 Function，不把 Markdown 的 ---、*** 或 ___ 识别为分隔线。

源码注释

注释属于 lexer/parser trivia，不是 Element，也没有 comment Function：

可见内容。 // 单行注释

/*
  块注释可以跨行。
  /* 也可以嵌套。 */
*/

URL 中的 https:// 不会被误识别为单行注释。

Plugin 边界

以下能力已经移出 core，不再注册 Function，也不再识别旧语法糖：