touying-author

Touying 作者指南

使用 Touying 编写 Typst 演示文稿，重点关注清晰的结构、可重复的配置和适用于幻灯片的模式。

快速入门

• 导入 Touying 和一个主题，然后使用 #show: <theme>.with(...) 应用主题。
• 将配置集中管理；从单独的文件中引入幻灯片内容。
• 使用标题创建幻灯片；对于自定义布局或动画，请使用 #slide。
• 从 examples/simple.typ 开始制作最简演示文稿，或从 examples/default.typ 开始使用基础主题。

examples/simple.typ 中的代码片段：

#import "@preview/touying:0.6.1": *
#import themes.simple: *

#show: simple-theme.with(
  aspect-ratio: "16-9",
  footer: [Simple slides],
)

最佳实践和代码结构

• 使用单个入口文件（例如 main.typ），在其中应用 #show 和所有 config-* 调用。
• 对于多文件演示文稿，请遵循 globals.typ + main.typ + content.typ 模式；使用 #include 引入内容，使用 #import 引入全局变量，以避免循环引用。
• 文档对共享配置文件同时使用 config.typ（参见 docs/start.md）和 globals.typ（参见 docs/multi-file.md）；选择一个名称，并在项目中保持一致。
• 对于大型演示文稿，将 content.typ 移至 sections/，并从 main.typ 引入 sections/content.typ（以及可选的 sections/another-section.typ）。
• 优先使用 config-page、config-common、config-info、config-colors、config-methods 和 config-store，而不是直接使用 set page 或临时添加全局 show。
• 大多数幻灯片使用标题；使用 config-common(slide-level: n) 选择哪些标题级别会创建幻灯片。
• 仅在需要自定义布局或动画时使用 #slide；始终使用 touying-slide-wrapper 包装幻灯片函数。
• 对于回调式动画（#slide(repeat: n, self => [...])），请显式设置 repeat，并使用 utils.methods(self) 访问 uncover、only 和 alternatives。

单文件结构

.
├── globals.typ
├── main.typ
└── content.typ

多文件结构

.
├── globals.typ
├── main.typ
└── sections/
    ├── content.typ
    └── another-section.typ

核心 API 概览（导出项）

• 幻灯片：touying-slides、slide、touying-slide、touying-slide-wrapper、empty-slide
• 动效：pause、meanwhile、uncover、only、effect、alternatives、alternatives-match、alternatives-fn、alternatives-cases
• 配置：config-common、config-page、config-info、config-colors、config-methods、config-store、default-config、touying-set-config、appendix
• 实用工具：utils.*（适应高度、适应宽度、封面辅助工具、进度、标题辅助工具）
• 组件：components.side-by-side、components.adaptive-columns、components.progressive-outline、components.custom-progressive-outline
• 集成：touying-reducer、touying-equation、touying-mitex、speaker-note、pdfpc.*
• 回顾：touying-recall、touying-fn-wrapper

幻灯片结构和标题

• 使用标题标签控制编号、纲要和书签：使用 <touying:hidden>（参见 docs/code-styles.md）；有关 <touying:unnumbered>、<touying:unoutlined>、<touying:unbookmarked> 和 <touying:skip>，请参见 docs/changelog.md。
• 使用 components.adaptive-columns(outline(...)) 创建目录幻灯片；使用 components.progressive-outline 创建可感知进度的纲要。
• 使用 == <touying:hidden> 插入空白标题幻灯片，并清除之前的标题上下文。
• 使用 #pagebreak() 或 --- 拆分幻灯片，而不更改标题。
• 对于不带页眉和页脚的幻灯片，请使用 #empty-slide[...]。
• 使用 config-common(handout: true)，使讲义输出中每张幻灯片只保留最后一个子幻灯片。
• 使用 #show: appendix，在主演示文稿结束后固定最后一张幻灯片的计数。

examples/default.typ 中的代码片段：

= Outline <touying:hidden>

#components.adaptive-columns(outline(title: none, indent: 1em))

动画和动态内容

• 使用 #pause 和 #meanwhile 实现简单的逐步显示；避免在不支持标记的 context 中使用它们。
• 使用 #uncover 预留布局空间；使用 #only 在隐藏时移除布局空间。
• 如果标记导致警告，请使用带有 repeat 和 utils.methods(self) 的回调式幻灯片。
• 对于数学动画，在 $ ... $ 中使用 pause/meanwhile；如果需要辅助函数来处理行内公式文本，请使用 touying-equation（也可以使用 #pause 或 #pause;）。
• 简单、复杂、回调式动画以及公式动画示例，请参阅 examples/example.typ。

摘自 examples/simple.typ：

== Dynamic slide

Did you know that...

#pause

...you can see the current section at the top of the slide?

摘自 examples/example.typ：

#slide(
  repeat: 3,
  self => [
    #let (uncover, only, alternatives) = utils.methods(self)

    At subslide #self.subslide, we can

    use #uncover("2-")[`#uncover` function] for reserving space,

    use #only("2-")[`#only` function] for not reserving space,

    #alternatives[call `#only` multiple times \u{2717}][use `#alternatives` function #sym.checkmark] for choosing one of the alternatives.
  ],
)

布局和主题

• 保持视觉风格一致：新布局、图形、表格和绘图必须沿用文档现有的字体、颜色和排版层级（除非另有要求）。内部风格也应保持一致（相同函数 → 相同尺寸和颜色）。
• 在 #slide 中使用 composer 创建分栏；传入 (1fr, 2fr) 或自定义的 grid 函数。
• 使用 config-page 设置边距、页眉、页脚和背景；不要直接使用 set page。
• 仅在允许更改布局时，使用 config-methods(cover: utils.semi-transparent-cover.with(alpha: 85%))。
• 使用 config-store 存放主题专属的页眉/页脚或导航元素值。
• 使用 config-common(new-section-slide-fn: none) 禁用自动生成的章节幻灯片，或提供自定义函数替换它们。
• 在 #show: <theme>.with(...) 周围应用全局样式，或在主题中通过 config-methods(init: ...) 应用。
• 使用 config-info(...) 设置标题/作者/日期，并使用 config-common(datetime-format: ...) 控制日期格式。

摘自 examples/default.typ：

#import "@preview/touying:0.6.1": *
#import themes.default: *

#import "@preview/numbly:0.1.0": numbly

#show: default-theme.with(
  aspect-ratio: "16-9",
  config-common(
    slide-level: 3,
    zero-margin-header: false,
  ),
  config-colors(primary: blue),
  config-methods(alert: utils.alert-with-primary-color),
  config-page(
    header: text(gray, utils.display-current-short-heading(level: 2)),
  ),
)

演讲者备注和演示工具

• 使用 #speaker-note[...] 添加备注。
• 使用 config-common(show-notes-on-second-screen: right) 或 bottom 在第二屏幕上显示备注。
• 使用 enable-pdfpc: true 和 typst query --field value --on "<pdfpc-file>" 导出 pdfpc 元数据。

使用随附的文档和示例

• 只阅读任务所需的特定文档；避免加载整个文档树。
• 阅读 docs/start.md 和 docs/intro.md，了解基础知识和导入模式。
• 阅读 docs/multi-file.md，了解多文件布局和包含模式。
• 阅读 docs/layout.md 和 docs/sections.md，了解幻灯片级布局和标题行为。
• 阅读 docs/code-styles.md，了解简单样式与块样式，以及分页技巧。
• 阅读 docs/global-settings.md，了解全局样式和 config-info 的用法。
• 阅读 docs/dynamic/*.md，了解 pause、meanwhile、覆盖行为和公式动画。
• 阅读 docs/themes/*.md，了解主题专属 API 和默认值。
• 阅读 docs/external/*.md，了解 pdfpc 和 Pympress 的用法。
• 阅读 docs/integration/*.md，了解 CeTZ/Fletcher/Theorion/MiTeX 集成。
• 将 examples/*.typ 用作各主题的可运行模板。

文件树（文档和示例）

docs/
├── build-your-own-theme.md
├── changelog.md
├── code-styles.md
├── dynamic
│   ├── complex.md
│   ├── cover.md
│   ├── equation.md
│   ├── handout.md
│   ├── other.md
│   └── simple.md
├── external
│   ├── pdfpc.md
│   ├── pympress.md
│   └── typst-preview.md
├── global-settings.md
├── integration
│   ├── cetz.md
│   ├── codly.md
│   ├── fletcher.md
│   ├── mitex.md
│   ├── pinit.md
│   └── theorion.md
├── intro.md
├── layout.md
├── multi-file.md
├── progress
│   ├── counters.md
│   └── sections.md
├── sections.md
├── start.md
├── themes
│   ├── aqua.md
│   ├── custom.md
│   ├── dewdrop.md
│   ├── metropolis.md
│   ├── simple.md
│   ├── stargazer.md
│   └── university.md
└── utilities
    └── fit-to.md

examples/
├── aqua-zh.typ
├── aqua.typ
├── default.typ
├── dewdrop.typ
├── example.typ
├── metropolis.typ
├── simple.typ
├── stargazer.typ
└── university.typ