在 Quarto 中如何安全嵌入 HTML 实现响应式双栏布局
作者：袖梨
2026-07-05
本文介绍在 quarto 中正确嵌入原生 html 的方法，重点解决因 yaml 元数据格式错误导致的 html 渲染失败问题，并演示如何构建左右等宽、左侧 gif 背景、右侧居中文本与按钮的响应式页面布局。
本文介绍在 quarto 中正确嵌入原生 html 的方法，重点解决因 yaml 元数据格式错误导致的 html 渲染失败问题，并演示如何构建左右等宽、左侧 gif 背景、右侧居中文本与按钮的响应式页面布局。
Quarto 默认支持在 .qmd 文件中直接编写 HTML，但需严格遵循其文档结构规范：YAML 元数据块（front matter）必须唯一且连续置于文件开头，不可拆分或重复声明。原始代码中将 --- 分割为两段（分别定义 title 和 format），导致 Quarto 解析失败，HTML 内容被忽略或转义输出。
✅ 正确写法是合并 YAML 配置为单个 front matter 块：
---title: ""format: html---
随后紧跟 HTML 内容（无需额外 <html> 或 <body> 标签包裹——Quarto 会自动注入完整 HTML 文档结构）。但需注意：直接使用 <body> 标签虽可工作，但更推荐语义化、可维护的写法，即用 <div> 替代，并通过 CSS 控制全屏布局：
<div style=" margin: 0; padding: 0; display: flex; height: 100vh; width: 100vw;"> <div style=" flex: 1; background: url('gif_example.gif') no-repeat center center; background-size: cover; "></div> <div style=" flex: 1; display: flex; flex-direction: column; justify-content: center; align-items: center; text-align: center; padding: 2rem; "> <p>To jest napis na prawej stronie</p> <button onclick="window.location.href='#'">Przycisk</button> </div></div>
? 关键注意事项：
立即学习“前端免费学习笔记（深入）”；
- 路径问题：确保 gif_example.gif 位于 Quarto 项目根目录或 ./images/ 等已配置的静态资源路径下（推荐放入 images/ 文件夹，并引用为 images/gif_example.gif）；
- 交互增强：示例中为按钮添加了 onclick 跳转逻辑，实际使用时请替换 # 为真实 URL（如 https://example.com）或锚点；
- 响应式补充：若需适配移动设备，建议添加媒体查询或使用 Quarto 内置布局类（如 {.column-margin}），或引入 Bootstrap Grid（通过 format: html: default: true 启用）；
- 安全性提醒：Quarto 默认对用户 HTML 进行基本转义防护；如需执行内联脚本（如 onclick），无需额外配置，但避免动态拼接不可信内容。
? 最佳实践建议：对于复杂布局，优先使用 Quarto 原生语法（如 ::: {.columns} + ::: {.column}）实现语义化分栏；仅当原生能力不足时，再嵌入定制 HTML——既保障可维护性，又利于未来升级兼容性。
