hextra_mirror/exampleSite/content/docs/guide/shortcodes/asciinema.zh-cn.md

title, linktitle, sidebar

title	linktitle	sidebar
Asciinema Player 组件	Asciinema Player	exclude true

asciinema shortcode 允许你在 Hugo 站点中嵌入使用 asciinema 创建的终端录制。它提供了一个功能丰富的终端播放器，具有播放控制、速度调整和主题自定义等功能。

基本用法

asciinema shortcode 支持本地 .cast 文件和远程 URL。以下是使用本地文件的不同方法：

本地文件

方法 1：Assets 目录（推荐） 将你的 cast 文件放在 Hugo 站点的 assets/ 目录中：

your-site/
├── assets/
│   └── demo.cast
└── content/
    └── my-page.md

在你的 markdown 文件中：

{{</* asciinema file="demo.cast" */>}}

方法 2：Static 目录 将你的 cast 文件放在 static/ 目录中：

your-site/
├── static/
│   └── demo.cast
└── content/
    └── my-page.md

在你的 markdown 文件中：

{{</* asciinema file="demo.cast" */>}}

方法 3：页面包 对于页面包，将 cast 文件与你的 markdown 文件放在一起：

your-site/
└── content/
    └── my-page/
        ├── index.md
        └── demo.cast

在你的 markdown 文件中：

{{</* asciinema file="demo.cast" */>}}

{{< asciinema file="casts/demo.cast" >}}

远程文件

你也可以使用来自任何远程 URL 的 cast 文件：

{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
{{</* asciinema file="https://example.com/demo.cast" */>}}

{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}

文件查找机制

shortcode 会按以下顺序自动查找你的 cast 文件：

1. 页面包资源（如果使用页面包）
2. 全局 assets 目录（assets/）
3. Static 目录（static/）
4. 远程 URL（如果路径以 http:// 或 https:// 开头）

如果找不到文件，Hugo 会显示有用的错误信息，告诉你应该将文件放在哪里。

高级演示

这是一个展示所有可用参数的高级示例：

{{</* asciinema 
  file="demo.cast"
  theme="dracula"
  speed="2"
  autoplay="true"
  loop="true"
  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
*/>}}

{{< asciinema file="casts/demo.cast" theme="dracula" speed="2" autoplay="true" loop="true" markers="1.5:Installation,3.2:Configuration,5.8:Testing"

}}

参数

参数	类型	默认值	描述
file	string	-	.cast 文件路径（必需）。支持本地文件、绝对路径和远程 URL
theme	string	"asciinema"	播放器主题
speed	number	1	播放速度倍数
autoplay	boolean	false	自动开始播放
loop	boolean	false	循环播放
poster	string	""	播放开始前显示的海报（预览帧）。支持 NPT 表示法（如 "npt:1:23"）
markers	string	""	逗号分隔的时间标记。格式："时间:标签" 或仅 "时间"（如 "1.5:Installation,3.2:Configuration,5.8"）