常见问题

本页收集了 Touying 使用中的常见问题与解决方案。

主题与配置

如何选择和切换主题？

Touying 提供多个内置主题，通过导入并应用主题函数即可切换：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
= Section

== Slide

Using the simple theme.

其他内置主题包括 themes.default、themes.metropolis、themes.aqua、themes.dewdrop、themes.stargazer、themes.university 等。

如何自定义主题颜色？

使用 config-colors(primary: ...) 自定义主题的主色调：

#import "@preview/touying:0.7.0": *
#import themes.metropolis: *
#show: metropolis-theme.with(
  aspect-ratio: "16-9",
  config-colors(primary: rgb("#d94f00")),
  config-info(title: [Custom Color], author: [Author]),
)
= Section

== Slide

The header now uses the custom primary color.

config-common 配置参考

config-common 有哪些常用配置项？

config-common 是 Touying 的核心配置函数，以下是常用配置项及其默认值和说明：

配置项	默认值	说明
`handout`	`false`	讲义模式，禁用动画
`slide-level`	`2`	控制哪个标题级别创建新幻灯片
`frozen-counters`	`()`	冻结计数器列表
`show-strong-with-alert`	`true`	粗体文本使用 alert 样式
`show-notes-on-second-screen`	`none`	第二屏幕演讲者备注（`none`/`right`/`left`）
`horizontal-line-to-pagebreak`	`true`	将 `---` 水平线转换为分页符
`nontight-list-enum-and-terms`	`false`	列表项间距控制
`show-hide-set-list-marker-none`	`true`	`#pause` 后隐藏列表标记
`show-bibliography-as-footnote`	`none`	参考文献显示为脚注
`scale-list-items`	`none`	缩放列表项大小
`new-section-slide-fn`	`none`	章节幻灯片函数
`freeze-slide-counter`	`false`	冻结幻灯片计数器
`enable-pdfpc`	`true`	启用 pdfpc 支持

如何使用半透明遮罩替代完全隐藏？

使用 config-methods(cover: utils.semi-transparent-cover) 配置，使被隐藏的内容以半透明形式显示：

#show: simple-theme.with(
  config-methods(cover: utils.semi-transparent-cover),
)

如何使用 preamble 在每张幻灯片前插入内容？

使用 config-common(preamble: ...) 在每张幻灯片前插入固定内容，subslide-preamble 在子幻灯片前插入：

#show: simple-theme.with(
  config-common(
    preamble: [Page #utils.slide-counter.display()],
    subslide-preamble: [Subslide #self.subslide],
  ),
)

如何使用 `---` 分隔幻灯片？

当 horizontal-line-to-pagebreak: true 时，可以在标题之间使用 --- 来创建新幻灯片：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
= Section

== First Slide

Content here.

---

== Second Slide

Created by `---`.

如何让列表项在 #pause 后隐藏标记符号？

show-hide-set-list-marker-none: true 会在 #pause 后隐藏列表标记：

#show: simple-theme.with(
  config-common(show-hide-set-list-marker-none: true),
)

如何缩放列表项大小？

使用 scale-list-items: 0.8 将列表项缩小到原始大小的 80%：

#show: simple-theme.with(
  config-common(scale-list-items: 0.8),
)

布局与分栏

如何创建两栏布局？

使用带 composer 参数的 slide 将内容分成多列：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide(composer: (1fr, 1fr))[
  == Left Column

  Some text on the left side.
][
  == Right Column

  Some text on the right side.
]

如需不等宽的列，可调整分数比例，例如 (2fr, 1fr)。

如何将内容放置在绝对位置？

使用 Typst 的 place 函数进行绝对定位：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  Main slide content here.

  #place(bottom + right, dx: -1em, dy: -1em)[
    #rect(fill: blue.lighten(80%), inset: 0.5em)[Note]
  ]
]

如何让内容填满幻灯片的剩余高度或宽度？

使用 utils.fit-to-height 或 utils.fit-to-width：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  #utils.fit-to-width(1fr)[
    == This heading fills the slide width
  ]

  Some content below.
]

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme.with(aspect-ratio: "16-9")
== Outline <touying:hidden>

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

= First Section

== Introduction

Hello, Touying!

= Second Section

== Details

More content here.

<touying:hidden> 标签可将目录幻灯片本身从目录中隐藏。

如何为目录中的章节添加编号？

结合 numbly 包和 #set heading(numbering: ...)：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#import "@preview/numbly:0.1.0": numbly
#set heading(numbering: numbly("{1}.", default: "1.1"))
#show: simple-theme.with(aspect-ratio: "16-9")
== Outline <touying:hidden>

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

= First Section

== First Slide

= Second Section

== Second Slide

如何显示带进度高亮的目录？

使用 components.progressive-outline 高亮当前章节：

#import "@preview/touying:0.7.0": *
#import themes.dewdrop: *
#show: dewdrop-theme.with(aspect-ratio: "16-9")
= First Section

== Outline

#components.progressive-outline()

= Second Section

== Slide

参考文献与引用

如何将引用显示为脚注？

将 bibliography(...) 值传递给 config-common(show-bibliography-as-footnote: ...)：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#let bib = bytes(
  "@book{knuth,
    title={The Art of Computer Programming},
    author={Donald E. Knuth},
    year={1968},
    publisher={Addison-Wesley},
  }",
)
#show: simple-theme.with(
  aspect-ratio: "16-9",
  config-common(show-bibliography-as-footnote: bibliography(bib)),
)
= Citations

== Footnote Example

This is a famous book. @knuth

如何在末尾添加参考文献幻灯片？

使用 magic.bibliography(...) 显示参考文献幻灯片：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#let bib = bytes(
  "@book{knuth,
    title={The Art of Computer Programming},
    author={Donald E. Knuth},
    year={1968},
    publisher={Addison-Wesley},
  }",
)
#show: simple-theme.with(
  aspect-ratio: "16-9",
  config-common(show-bibliography-as-footnote: bibliography(bib)),
)
= Intro

== Slide

Some cited content. @knuth

== References

#magic.bibliography(title: none)

演讲者备注

如何为幻灯片添加演讲者备注？

在幻灯片的任意位置使用 #speaker-note[...] 函数：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  == My Slide

  Visible content here.

  #speaker-note[
    - Remind the audience of the previous topic.
    - Emphasize the key takeaway.
    - Time check: should be at 10 min mark.
  ]
]

演讲者备注默认不会出现在幻灯片输出中。

如何在第二屏幕上显示演讲者备注？

使用 config-common(show-notes-on-second-screen: right) 在幻灯片旁边显示备注：

#show: simple-theme.with(
  aspect-ratio: "16-9",
  config-common(show-notes-on-second-screen: right),
)

此功能与 pdfpc 和 pympress 等演示工具兼容。

幻灯片编号与附录

如何在页脚显示幻灯片编号？

使用 utils.slide-counter.display() 显示当前编号，utils.last-slide-number 显示总数：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme.with(
  aspect-ratio: "16-9",
  config-page(
    footer: context [
      #utils.slide-counter.display() / #utils.last-slide-number
    ],
  ),
)
= Section

== First Slide

The footer shows the slide number.

== Second Slide

Still counting.

如何将幻灯片标记为不计数？

在标题上添加 <touying:unnumbered> 标签：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
= Title Slide <touying:unnumbered>

== Welcome

This slide is not counted.

== Normal Slide

This slide is counted.

如何使用附录以不影响幻灯片总数？

在主要内容之后使用 #show: appendix。此后的幻灯片不会递增幻灯片计数器：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme.with(aspect-ratio: "16-9")
= Main Content

== Introduction

This is slide 1.

== Results

This is slide 2.

#show: appendix

= Appendix

== Extra Material

This slide is in the appendix and does not increment the main counter.

动画与动态内容

如何使用 `#pause` 逐步展示内容？

在 #slide 内的内容块之间放置 #pause：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  First point.

  #pause

  Second point revealed on click.

  #pause

  Third point revealed on second click.
]

如何仅在特定子幻灯片上显示内容？

使用 #only("...") 在特定子幻灯片上显示内容，或用 #uncover("...") 显示内容同时保留其占位空间：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  #only("1")[Shown on subslide 1 only.]
  #only("2-")[Shown from subslide 2 onward.]
  #uncover("3-")[Revealed on subslide 3, space reserved before.]
]

为什么 `#pause` 在 `context` 表达式内不起作用？

#pause 使用元数据注入机制，在 context { ... } 块内无法正常工作。请改用回调式 slide 来访问 self.subslide：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide(self => {
  let (uncover, only) = utils.methods(self)
  [First content.]
  linebreak()
  uncover("2-")[Revealed on subslide 2.]
  linebreak()
  only("3")[Only on subslide 3.]
})

如何在 CeTZ 绘图中使用 `#pause`？

使用 touying-reducer 包裹 CeTZ canvas，使 Touying 能够为其添加动画：

#import "@preview/cetz:0.4.2"

#let cetz-canvas = touying-reducer.with(
  reduce: cetz.canvas,
  cover: cetz.draw.hide.with(bounds: true),
)

#slide[
  #cetz-canvas({
    import cetz.draw: *
    rect((0, 0), (4, 3))
    (pause,)
    circle((2, 1.5), radius: 1)
  })
]

如何在 Fletcher 图表中使用 `#pause`？

使用 touying-reducer 包裹 Fletcher 图表：

#import "@preview/fletcher:0.5.8": diagram, node, edge

#let fletcher-diagram = touying-reducer.with(
  reduce: diagram,
  cover: fletcher.hide,
)

#slide[
  #fletcher-diagram(
    node((0, 0), [A]),
    edge("->"),
    (pause,),
    node((1, 0), [B]),
  )
]

如何在子幻灯片间展示替换内容？

使用 #alternatives 在不同版本的内容之间切换：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  The answer is: #alternatives[42][*forty-two*][_the ultimate answer_].
]

如何开启讲义模式（禁用动画）？

在主题设置中使用 config-common(handout: true)：

#show: simple-theme.with(
  aspect-ratio: "16-9",
  config-common(handout: true),
)

在讲义模式下，每张幻灯片只输出最后一个子幻灯片。

字体与文本

如何更改演示文稿的字体？

在主题设置之前或之后使用 #set text(...) 规则：

#import "@preview/touying:0.7.0": *
#import themes.metropolis: *
#show: metropolis-theme.with(
  aspect-ratio: "16-9",
  config-info(title: [Custom Font]),
)
#set text(font: "New Computer Modern", size: 22pt)
= Section

== Slide

Text now uses the custom font.

对于数学公式，还需设置数学字体：

#show math.equation: set text(font: "New Computer Modern Math")

如何对段落文本进行两端对齐？

使用 #set par(justify: true)：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#set par(justify: true)
#slide[
  == Justified Text

  #lorem(40)
]

标题与章节

如何禁用自动章节幻灯片？

设置 config-common(new-section-slide-fn: none)：

#import "@preview/touying:0.7.0": *
#import themes.metropolis: *
#show: metropolis-theme.with(
  aspect-ratio: "16-9",
  config-common(new-section-slide-fn: none),
  config-info(title: [No Auto Sections]),
)
= Section

== Slide

No automatic section slide was created for the `= Section` heading.

如何完全隐藏一张幻灯片？

在幻灯片标题上添加 <touying:hidden> 标签：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
== Visible Slide

This slide appears in the output.

== Hidden Slide <touying:hidden>

This slide is hidden and does not appear in the output or outline.

== Another Visible Slide

Back to normal.

如何将幻灯片从目录中排除但仍然显示？

使用 <touying:unoutlined> 标签：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
== Outline <touying:hidden>

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

= Section

== Normal Slide

Appears in the outline.

== Interstitial Slide <touying:unoutlined>

This slide shows but is not listed in the outline.

== Another Normal Slide

Also appears in the outline.

如何控制哪个标题级别创建新幻灯片？

使用 config-common(slide-level: ...)，默认值因主题而异：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme.with(
  aspect-ratio: "16-9",
  config-common(slide-level: 2),
)
= Section

This text is part of the section slide.

== Subsection Slide

Each `==` heading creates a new slide.

=== Sub-subheading

Sub-subheadings do not create new slides.

如何添加自定义页眉或页脚？

使用 config-page(header: ..., footer: ...)：

#import "@preview/touying:0.7.0": *
#import themes.default: *
#show: default-theme.with(
  aspect-ratio: "16-9",
  config-page(
    header: text(gray)[My Custom Header],
    footer: context align(right, text(gray)[
      Slide #utils.slide-counter.display()
    ]),
  ),
)
= Section

== Slide

Slide with a custom header and footer.

测试与开发

如何运行 Touying 的测试套件？

Touying 使用 tytanic 测试框架。

安装 tytanic：

cargo binstall tytanic

运行测试：

tt run

测试位于 tests/ 目录下，分为：

features/ — 功能测试
themes/ — 主题测试
integration/ — 第三方包集成测试（cetz、fletcher、pinit、theorion、codly、mitex）
issues/ — 回归测试
examples/ — 示例测试

如何为 Touying 贡献代码？

贡献流程：

Fork touying-typ/touying 仓库
创建功能分支：git checkout -b feature/my-feature
修改代码并用 typstyle 格式化
运行 tt run 确保所有测试通过
提交并推送到你的 fork
创建 Pull Request

其他问题

如何设置演示文稿的标题、作者和日期？

使用 config-info(...)：

#import "@preview/touying:0.7.0": *
#import themes.metropolis: *
#show: metropolis-theme.with(
  aspect-ratio: "16-9",
  config-info(
    title: [My Presentation],
    subtitle: [A Subtitle],
    author: [Jane Doe],
    date: datetime.today(),
    institution: [My University],
  ),
)
#title-slide()
= Introduction

== First Slide

Content here.

如何为单张幻灯片覆盖配置？

使用 touying-set-config 包裹需要更改的内容：

#import "@preview/touying:0.7.0": *
#import themes.simple: *
#show: simple-theme
#slide[
  Normal slide.
]

#touying-set-config(config-page(fill: rgb("#fff3cd")))[
  #slide[
    This slide has a yellow background.
  ]
]

#slide[
  Back to normal.
]

如何创建多文件演示文稿？

从主入口文件导入 lib.typ，并用 include 引入各章节：

// main.typ
#import "@preview/touying:0.7.0": *
#import themes.simple: *

#show: simple-theme.with(aspect-ratio: "16-9")

#include "intro.typ"
#include "methods.typ"
#include "results.typ"

每个被引入的文件正常使用标题即可，无需在每个文件中重复导入。

如何在页眉或页脚中显示当前章节名称？

使用 utils.display-current-heading(...) 或 utils.display-current-short-heading(...)：

#import "@preview/touying:0.7.0": *
#import themes.default: *
#show: default-theme.with(
  aspect-ratio: "16-9",
  config-page(
    header: context text(gray)[
      #utils.display-current-heading(level: 1)
    ],
  ),
)
= My Section

== Slide

The header shows the current section name.

如何将 Touying 与 `pinit` 包配合使用？

正常导入两个包并在幻灯片中使用 #pin/#pinit-highlight：

#import "@preview/touying:0.7.0": *
#import "@preview/pinit:0.2.2": *
#import themes.simple: *

#show: simple-theme.with(aspect-ratio: "16-9")

#slide[
  A #pin(1)key term#pin(2) to highlight.

  #pinit-highlight(1, 2)
]

如需带动画的 pin 展示效果，请使用回调式 slide，以便 #pause 与 pinit 正确交互。

如何在子幻灯片间冻结计数器（图表、公式）？

使用 config-common(frozen-counters: true) 防止计数器在子幻灯片之间递增：

#show: simple-theme.with(
  config-common(frozen-counters: true),
)

常见问题

主题与配置​

如何选择和切换主题？​

如何自定义主题颜色？​

config-common 配置参考​

config-common 有哪些常用配置项？​

如何使用半透明遮罩替代完全隐藏？​

如何使用 preamble 在每张幻灯片前插入内容？​

如何使用 --- 分隔幻灯片？​

如何让列表项在 #pause 后隐藏标记符号？​

如何缩放列表项大小？​

布局与分栏​

如何创建两栏布局？​

如何将内容放置在绝对位置？​

如何让内容填满幻灯片的剩余高度或宽度？​

目录​

如何显示目录？​

如何为目录中的章节添加编号？​

如何显示带进度高亮的目录？​

参考文献与引用​

如何将引用显示为脚注？​

如何在末尾添加参考文献幻灯片？​

演讲者备注​

如何为幻灯片添加演讲者备注？​

如何在第二屏幕上显示演讲者备注？​

幻灯片编号与附录​

如何在页脚显示幻灯片编号？​

如何将幻灯片标记为不计数？​

如何使用附录以不影响幻灯片总数？​

动画与动态内容​

如何使用 #pause 逐步展示内容？​

如何仅在特定子幻灯片上显示内容？​

为什么 #pause 在 context 表达式内不起作用？​

如何在 CeTZ 绘图中使用 #pause？​

如何在 Fletcher 图表中使用 #pause？​

如何在子幻灯片间展示替换内容？​

如何开启讲义模式（禁用动画）？​

字体与文本​

如何更改演示文稿的字体？​

如何对段落文本进行两端对齐？​

标题与章节​

如何禁用自动章节幻灯片？​

如何完全隐藏一张幻灯片？​

如何将幻灯片从目录中排除但仍然显示？​

如何控制哪个标题级别创建新幻灯片？​

如何添加自定义页眉或页脚？​

测试与开发​

如何运行 Touying 的测试套件？​

如何为 Touying 贡献代码？​

其他问题​

如何设置演示文稿的标题、作者和日期？​

如何为单张幻灯片覆盖配置？​

如何创建多文件演示文稿？​

如何在页眉或页脚中显示当前章节名称？​

如何将 Touying 与 pinit 包配合使用？​

如何在子幻灯片间冻结计数器（图表、公式）？​