HTML 渲染指南
在 PowerWiki 中,HTML 文件既可以作为安全清洗后的普通文章,也可以声明沙箱模式,作为完整的交互页面嵌入正文。
概览
HTML 文件进入仓库后,会被识别为 type: html 的文章。默认情况下,页面会经过白名单清洗,只保留安全的正文结构。若页面需要脚本、Canvas、WebGL 等能力,可在 <head> 中声明沙箱模式。
快速开始
- 把
.html文件提交到内容仓库的任意目录。 - 在
<head>中加入一行渲染声明。 - 推送后刷新文章页,正文会自动嵌入完整页面。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="powerwiki-render" content="sandbox">
<title>我的交互页面</title>
</head>
<body>
<canvas id="scene"></canvas>
<script>/* 页面自己的脚本 */</script>
</body>
</html>
<!-- 推荐写法 -->
<meta name="powerwiki-render" content="sandbox">
<!-- 兼容别名 -->
<meta name="powerwiki-render" content="full">
git add docs/demo.html
git commit -m "feat: add sandbox demo page"
git push origin main
沙箱模式
声明沙箱模式后,文章正文会变成一个 iframe,其 sandbox 属性允许脚本、表单、弹窗与下载,但不包含 allow-same-origin。
页面无法读取 Cookie、localStorage、IndexedDB,也不能调用站内的同源接口。请把需要的状态保存在内存中。
原始页面同时会在 /full/<仓库路径> 下提供,带 Content-Security-Policy: sandbox 响应头,可在新窗口独立打开。
资源解析
相对路径以 HTML 文件所在目录为基准解析;根绝对路径 /static/... 会映射回仓库中的同目录结构。支持的资源类型包括:
| 类型 | 扩展名 | 说明 |
|---|---|---|
| 图片 | png / jpg / gif / webp / svg / avif | 内联或外链引用均可 |
| 样式脚本 | css / js / mjs | 同目录或子目录 |
| 字体 | woff / woff2 / ttf / otf / eot | 配合 @font-face |
| 媒体 | mp3 / wav / ogg / mp4 / webm | 支持 Range 请求 |
| WebAssembly | wasm | 需正确 MIME 类型 |
安全模型
- 路径校验:拒绝目录穿越、隐藏文件段、符号链接与超限文件。
- 渲染隔离:沙箱 iframe 没有同源权限,无法访问父页面 DOM。
- 响应头:
nosniff、Cross-Origin-Resource-Policy与按类型设置的 CSP。 - 类型白名单:
/full/仅提供页面与静态资源,不暴露 JSON、密钥或配置文件。
仅对可信仓库中的页面开启沙箱模式;第三方 HTML 仍建议保持默认清洗模式。
API 参考
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 固定为 html |
| path | string | 是 | 仓库内的相对路径 |
| title | string | 否 | 未提供时取首个标题或文件名 |
| html | string | 否 | 沙箱模式下为 iframe 片段 |
| raw | string | 否 | 原始文件内容 |
文章详情接口返回的 html 字段就是正文 HTML。沙箱模式下它是受控的 iframe,而不是原页面内容。
快捷键
| 快捷键 | 作用 |
|---|---|
| / | 聚焦搜索框 |
| T | 切换深色 / 浅色主题 |
| Esc | 清空搜索或关闭目录 |
| ↑ ↓ | 在侧边栏链接间移动焦点 |
常见问题
为什么页面里的 localStorage 会报错?
沙箱 iframe 处于不透明源,访问 Web Storage 会抛出异常。建议用内存变量保存状态,必要时应使用 try / catch 包裹。
可以使用外部 CDN 资源吗?
可以,但不推荐。外部资源会让页面离线不可用,也受 CSP 限制。演示页应尽量内联样式与脚本。
为什么脚本没有执行?
请确认 <meta name="powerwiki-render" content="sandbox"> 位于 <head> 内,并且文件名以 .html 结尾。
页面高度可以自定义吗?
正文 iframe 的高度由 Wiki 主题控制;页面内部超出部分会自然滚动。也可以在新窗口打开完整页面获得全屏体验。