常见问题
本页收集了 Touying 使用中的常见问题与解决方案。
主题与配置
如何选择和切换主题?
Touying 提供多个内置主题,通过导入并应用主题函数即可切换:
#import "@preview/touying:0.7.4": *
#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.4": *
#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.
如何在正文中访问当前主题颜色?
主题颜色保存在 self.colors 中。在普通幻灯片正文里,可以用 touying-fn-wrapper 包裹一个函数,让 Touying 把当前幻灯片上下文作为 self 传入:
#import "@preview/touying:0.7.4": *
#import themes.simple: *
#show: simple-theme.with(aspect-ratio: "16-9")
= Section
== Slide
#touying-fn-wrapper((self: none) => text(fill: self.colors.primary)[
This text uses the current theme's primary color.
])
#touying-fn-wrapper((self: none) => rect(
fill: self.colors.secondary,
width: 4em,
height: 1em,
))
如果你正在编写已经接收 self 的主题方法或回调函数,则可以直接使用 self.colors.primary、self.colors.neutral-lightest 等颜色。
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/bottom/right) |
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 支持 |
breakable | true | 是否允许幻灯片内容溢出到下一页 |
clip | false | 是否裁剪溢出内容(仅在 breakable: false 时生效) |
detect-overflow | true | 是否检测溢出并报错(仅在 breakable: false 时生效) |
如何防止幻灯片内容溢出到下一页?
使用 config-common(breakable: false) 可以防止幻灯片内容自动溢出到下一页。默认情况下(breakable: true),超出幻灯片高度的内容会自动创建新页面;设置为 false 后,内容将被限制在单页内,这对于需要保证源码与输出页面一一对应的场景(如 AI 智能体工作 流)非常有用。
配合使用的参数:
clip(默认false):设为true时,超出幻灯片高度的内容会被视觉截断。detect-overflow(默认true):设为true时,会通过布局测量检测溢出,一旦内容高度超出幻灯片高度则直接panic()报错,便于及早发现问题;设为false可避免额外的布局开销。
// Prevent overflow, panic on overflow (default behavior when breakable: false)
#show: simple-theme.with(
config-common(breakable: false),
)
// Prevent overflow and visually clip overflowing content
#show: simple-theme.with(
config-common(breakable: false, clip: true),
)
// Prevent overflow, disable overflow detection (performance-first)
#show: simple-theme.with(
config-common(breakable: false, detect-overflow: false),
)
也可以在演示文稿中途通过 touying-set-config 切换:
== This slide's overflow will be clipped
// Enable clipping for a specific slide
#show: touying-set-config.with(config-common(clip: true))
#lorem(500)
如何使用半透明遮罩替代完全隐藏?
使用 config-methods(cover: utils.semi-transparent-cover) 配置,使被隐藏的内容以半透明形式显示:
#import "@preview/touying:0.7.4": *
#import themes.simple: *
#show: simple-theme.with(
aspect-ratio: "16-9",
config-methods(cover: utils.semi-transparent-cover),
)
= Section
== Slide
#pause
This content is shown with a semi-transparent cover.
如何使用 preamble 在每张幻灯片前插入内容?
使用 config-common(preamble: ...) 在每张幻灯片前插入固定内容,subslide-preamble 在子幻灯片前插入:
#import "@preview/touying:0.7.4": *
#import themes.simple: *
#show: simple-theme.with(
aspect-ratio: "16-9",
config-common(
preamble: text(gray)[This appears before every slide],
subslide-preamble: (2: [Special prelude for subslide 2]),
),
)
= Section
== Slide
Content here.
#pause
More content.
如何使用 --- 分隔幻灯片?
当 horizontal-line-to-pagebreak: true 时,可以在标题之间使用 --- 来创建新幻灯片:
#import "@preview/touying:0.7.4": *
#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.4": *
#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.4": *
#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.4": *
#import themes.simple: *
#show: simple-theme
#slide[
#utils.fit-to-width(1fr)[
== This heading fills the slide width
]
Some content below.
]
目录
如何显示目录?
用 components.adaptive-columns 包裹 Typst 内置的 outline:
#import "@preview/touying:0.7.4": *
#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> 标签可将目录幻灯片本身从目录中隐藏。
如何只保留主目录并禁用自动章节页?
有些主题在遇到新的一级章节(=)时,会自动生成章节页(通常是目录或章节概览)。可以用 config-common(new-section-slide-fn: none) 关闭这些自动章节页,然后只保留你手动编写的主目录页:
#import "@preview/touying:0.7.4": *
#import themes.metropolis: *
#show: metropolis-theme.with(
aspect-ratio: "16-9",
config-common(new-section-slide-fn: none),
)
== Outline <touying:hidden>
#components.adaptive-columns(outline(title: none, indent: 1em))
= First Section
== First Slide
= Second Section
== Second Slide
如何为目录中的章节添加编号?
结合 numbly 包和 #set heading(numbering: ...):
#import "@preview/touying:0.7.4": *
#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.4": *
#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.4": *
#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.4": *
#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.4": *
#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.
]
]
演讲者备注默认不会出现在幻灯片输出中。