PowerWiki Docs v1.0
文档 HTML 渲染

HTML 渲染指南

在 PowerWiki 中,HTML 文件既可以作为安全清洗后的普通文章,也可以声明沙箱模式,作为完整的交互页面嵌入正文。

稳定可用 Sandbox 零构建 离线可运行

概览

HTML 文件进入仓库后,会被识别为 type: html 的文章。默认情况下,页面会经过白名单清洗,只保留安全的正文结构。若页面需要脚本、Canvas、WebGL 等能力,可在 <head> 中声明沙箱模式。

文章模式 白名单清洗,图片自动重写,适合普通内容页。
沙箱模式 完整页面运行在隔离 iframe,脚本样式均可用。
安全边界 不透明源,无法读取 Wiki 的 Cookie 与同源接口。

快速开始

  1. 把 .html 文件提交到内容仓库的任意目录。
  2. 在 <head> 中加入一行渲染声明。
  3. 推送后刷新文章页,正文会自动嵌入完整页面。
demo.html html
<!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>

沙箱模式

声明沙箱模式后,文章正文会变成一个 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 请求
WebAssemblywasm需正确 MIME 类型

安全模型

推荐做法

仅对可信仓库中的页面开启沙箱模式;第三方 HTML 仍建议保持默认清洗模式。

API 参考

字段类型必填说明
typestring是固定为 html
pathstring是仓库内的相对路径
titlestring否未提供时取首个标题或文件名
htmlstring否沙箱模式下为 iframe 片段
rawstring否原始文件内容

文章详情接口返回的 html 字段就是正文 HTML。沙箱模式下它是受控的 iframe,而不是原页面内容。

快捷键

快捷键作用
/聚焦搜索框
T切换深色 / 浅色主题
Esc清空搜索或关闭目录
↑ ↓在侧边栏链接间移动焦点

常见问题

为什么页面里的 localStorage 会报错?

沙箱 iframe 处于不透明源,访问 Web Storage 会抛出异常。建议用内存变量保存状态,必要时应使用 try / catch 包裹。

可以使用外部 CDN 资源吗?

可以,但不推荐。外部资源会让页面离线不可用,也受 CSP 限制。演示页应尽量内联样式与脚本。

为什么脚本没有执行?

请确认 <meta name="powerwiki-render" content="sandbox"> 位于 <head> 内,并且文件名以 .html 结尾。

页面高度可以自定义吗?

正文 iframe 的高度由 Wiki 主题控制;页面内部超出部分会自然滚动。也可以在新窗口打开完整页面获得全屏体验。