Playground 演练场插件
@docmd/plugin-playground 插件为 docmd 站点带来交互式、可运行的代码块与实时组件预览。文档作者可以直接在文档中嵌入独立的 JavaScript 执行环境、实时 HTML/CSS 组件以及代码库中的真实脚本文件,而无需引入 Monaco 或 React 等庞大的第三方依赖。
自 v0.9.9 起,@docmd/plugin-playground 直接随 @docmd/core 分发并默认启用。得益于 docmd 的按需资产加载机制,未包含演练场代码块的页面加载 0 KB 额外资产,确保静态内容的极致性能。
核心特性
在文档中编写 ```js playground 或 ::: playground,即可立即实例化一个交互式沙箱。
通过 ::: playground src="./snippets/demo.js" /::: 直接引用代码库中的源脚本,确保文档示例随实际项目代码自动保持同步。
实时拦截并格式化 console.log()、console.info()、console.warn() 和 console.error() 输出,并直观展示返回值。
在隔离的预览框架内渲染动态 UI 组件,并支持在控制台日志与渲染视图之间便捷切换。
原生访问客户端 window.docmd 运行时与响应式页面变量,支持 docmd.var.get() 和 docmd.var.set()。
在顶栏提供交互式选项卡,可在组件实时渲染输出与底层源代码之间即刻在全宽单面板视图中切换(tabs)。
引用的脚本缺失时显示不影响构建的友好警告横幅;代码运行抛出异常时在控制台清晰呈现错误信息。
纯原生 JavaScript 与 CSS 构建(整体体积 < 10 KB),支持常用键盘快捷键(Cmd+Enter / Ctrl+Enter 运行,Tab 缩进)。
插件配置
由于 @docmd/plugin-playground 属于核心插件,默认开箱即用,无需额外配置。您亦可在 docmd.config.json 中自定义全局选项或显式关闭插件:
{
"plugins": {
"playground": {
"enabled": true,
"theme": "default",
"defaultLayout": "split"
}
}
}
配置项说明
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
enabled |
boolean |
true |
全局开启或关闭演练场渲染。 |
theme |
string |
"default" |
匹配当前 docmd 布局的配色主题(default, dark, light)。 |
defaultLayout |
string |
"split" |
默认排版形式(split 为左右分栏,stacked 为上下堆叠)。 |
若需要在整个文档站点禁用客户端代码求值,请在 docmd.config.json 的 "plugins" 下设置 "playground": false。所有演练场代码块将优雅降级为带语法高亮的基础代码块,且不会注入任何演练场脚本或样式。
技术架构与内部原理
Playground 插件采用轻量、无外部依赖的架构设计,确保文档站点的高性能与安全性:
1. 构建期 AST 拦截机制
- 容器与代码围栏钩子:在
markdown-it中注册针对playground的处理规则。 - 按需条件资源加载:仅在包含 Playground 容器或代码块的页面上注入相关样式与脚本,未使用的静态页面保持 100% 纯净,0 KB 额外体积。
2. 源码脚本解析引擎 (src)
- 自动相对于当前文档目录或项目根目录解析本地文件路径。
- 若目标文件丢失,构建器不会中断报错,而是渲染清晰的告警提示框(
.docmd-playground-missing-alert),保证 CI/CD 构建流程顺利通过。
3. 沙箱执行环境
- 代理拦截
console.log、console.info、console.warn、console.error,实时格式化输出到控制台面板。 - 原生集成
docmd-runtime(docmd.var.get()、docmd.var.set())。
- 纯客户端执行:代码仅在访客本地浏览器环境中运行,完全不存在服务端攻击面。
- Iframe 沙箱隔离:HTML 预览在具备
sandbox="allow-scripts allow-modals allow-forms"且未开启allow-same-origin的隔离 iframe 中呈现,彻底阻断对主页面 Cookie、LocalStorage 及 DOM 的读取。 - 域名隔离最佳实践:生产环境中推荐将文档站点部署在独立的文档专属子域名上(例如
docs.example.com)。
脚本驱动示例与工作流
脚本示例 1:引用本地脚本源码 (src)
::: playground src="./snippets/demo.js" title="本地脚本文件" icon:cpu live /:::
脚本示例 2:交互式 HTML 与 CSS 组件预览
Playground 支持在浏览器沙箱中直接呈现丰富的前端 HTML 与 CSS 组件。读者可在 Play 视图中直接体验组件效果,并随时切换至 Code 视图查看和修改源码:
::: playground title="实时通知交互卡片" icon:bell live
```html
<div style="padding: 16px; border-radius: 8px; background: #0f172a; border: 1px solid #1e293b; color: #f8fafc; font-family: system-ui, sans-serif;">
<div style="display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px;">
<strong style="color: #38bdf8; font-size: 14px;">实时消息通知</strong>
<span style="font-size: 11px; background: #0369a1; padding: 2px 8px; border-radius: 10px; color: white;">在线</span>
</div>
<p style="margin: 0 0 12px 0; font-size: 13px; color: #94a3b8; line-height: 1.4;">
在顶部工具栏切换 <strong>Play</strong> 与 <strong>Code</strong> 视图,即可直接调试和修改底层标记代码。
</p>
<button style="padding: 6px 14px; background: #10b981; color: white; border: none; border-radius: 6px; font-size: 12px; font-weight: 600; cursor: pointer;" onclick="alert('通知操作触发成功!')">
确认操作
</button>
</div>
```
:::
实时渲染的交互组件:
脚本示例 3:JavaScript 脚本执行与控制台交互
在客户端沙箱中运行 JavaScript 脚本,完整支持 console.log、console.info 拦截与函数返回值显示:
关联文档与参考
- Playground 容器语法与属性指南:深入了解容器标签属性、Live/Code 视图切换、布局排列及更多实时示例。
- 变量与个性化运行时:了解
docmd-runtime如何与客户端脚本响应联动。 - 容器组件全览:查看
docmd支持的完整容器清单。