在 Quarto 中如何安全嵌入 HTML 实现响应式双栏布局

时间：2026-07-05 11:30:45 编辑：袖梨来源：一聚教程网

本文介绍在 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——既保障可维护性，又利于未来升级兼容性。

推荐专题

最新下载

热门教程

在 Quarto 中如何安全嵌入 HTML 实现响应式双栏布局

相关文章

热门栏目

php教程

asp.net教程

手机开发

css教程

网页制作

办公数码

jsp教程