怎样在 Quarto 中嵌入自定义 HTML 实现响应式双栏布局

作者：袖梨 2026-06-30

本文详解如何在 quarto 文档中安全、有效地嵌入原生 html 代码，以实现如 gif 背景左栏 + 文本按钮右栏的自定义布局，并指出常见配置错误（如重复 yaml 区块）及正确用法。

本文详解如何在 quarto 文档中安全、有效地嵌入原生 html 代码，以实现如 gif 背景左栏 + 文本按钮右栏的自定义布局，并指出常见配置错误（如重复 yaml 区块）及正确用法。

Quarto 原生支持 HTML 内容嵌入，但需遵循其文档结构规范：YAML 元数据区块必须唯一且位于文件开头，不可拆分或重复出现。你原始代码中将 format: html 单独置于第二个 --- 区块，导致 Quarto 解析失败（YAML 解析中断，后续 HTML 被当作普通文本渲染，而非 DOM 结构）。

✅ 正确写法是将所有元数据整合到一个 YAML 头部中，并确保 HTML 结构直接置于其后（无需额外 <html> 或 <body> 标签包裹——Quarto 会自动注入完整 HTML 模板，你只需提供 <body> 内的有效内容）：

---title: ""format: html---<body style="margin: 0; padding: 0; display: flex; height: 100vh;">  <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></body>

? 关键注意事项：

✅ gif_example.gif 需存放于项目根目录或 resources/ 子目录中（推荐放入 resources/ 并使用 url('resources/gif_example.gif') 提升可移植性）；
✅ <body> 标签虽非必需（Quarto 允许直接写 <div>），但显式声明有助于语义清晰和样式控制；
⚠️ 避免在 Quarto 文档中手动添加 <html>、<head> 或重复 <body> —— 这会导致嵌套冲突或渲染异常；
? 如需为按钮添加真实跳转，将 onclick 替换为 onclick="window.location.href='https://example.com'"，或更推荐使用标准 <a> 标签配合 CSS 按钮样式以保障可访问性。

最终生成的页面将严格按 Flex 布局等分视口，左侧满屏 GIF 背景（居中覆盖），右侧垂直水平居中文本与按钮，适配桌面端主流分辨率。此方案兼顾简洁性与可控性，是 Quarto 中实现定制化 UI 的标准实践。

立即学习“前端免费学习笔记（深入）”；