Playground 演练场插件

@docmd/plugin-playground 插件为 docmd 站点带来交互式、可运行的代码块与实时组件预览。文档作者可以直接在文档中嵌入独立的 JavaScript 执行环境、实时 HTML/CSS 组件以及代码库中的真实脚本文件,而无需引入 Monaco 或 React 等庞大的第三方依赖。

内置于 @docmd/core 的核心插件

自 v0.9.9 起,@docmd/plugin-playground 直接随 @docmd/core 分发并默认启用。得益于 docmd 的按需资产加载机制,未包含演练场代码块的页面加载 0 KB 额外资产,确保静态内容的极致性能。

核心特性

Zero-Config 零配置激活

在文档中编写 ```js playground 或 ::: playground,即可立即实例化一个交互式沙箱。

代码库文件动态嵌入

通过 ::: playground src="./snippets/demo.js" /::: 直接引用代码库中的源脚本,确保文档示例随实际项目代码自动保持同步。

控制台日志实时捕获

实时拦截并格式化 console.log()、console.info()、console.warn() 和 console.error() 输出,并直观展示返回值。

实时 HTML & CSS 组件沙箱

在隔离的预览框架内渲染动态 UI 组件,并支持在控制台日志与渲染视图之间便捷切换。

docmd-runtime 深度集成

原生访问客户端 window.docmd 运行时与响应式页面变量,支持 docmd.var.get() 和 docmd.var.set()。

Live 与 Code 视图切换

在顶栏提供交互式选项卡,可在组件实时渲染输出与底层源代码之间即刻在全宽单面板视图中切换(tabs)。

优雅错误降级与提示

引用的脚本缺失时显示不影响构建的友好警告横幅;代码运行抛出异常时在控制台清晰呈现错误信息。

超轻量与极致速度

纯原生 JavaScript 与 CSS 构建(整体体积 < 10 KB),支持常用键盘快捷键(Cmd+Enter / Ctrl+Enter 运行,Tab 缩进)。

插件配置

由于 @docmd/plugin-playground 属于核心插件,默认开箱即用,无需额外配置。您亦可在 docmd.config.json 中自定义全局选项或显式关闭插件:

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 插件采用轻量、无外部依赖的架构设计,确保文档站点的高性能与安全性:

flowchart TD MD[Markdown 源码] --> AST[Markdown-It 语法分析] AST --> Check{是否包含 Playground?} Check -->|否| Clean[0 KB 额外资源输出] Check -->|是| Assets[注入 docmd-playground.css 与 js] AST --> SourceCheck{是否存在 src 属性?} SourceCheck -->|是| ReadFile[解析并内嵌本地脚本源码] SourceCheck -->|否| ParseFence[解析代码围栏内容] ReadFile -->|文件不存在| WarnBlock[输出非破坏性告警卡片] ReadFile -->|成功| Container[生成容器 HTML 结构] ParseFence --> Container Container --> Browser[客户端浏览器运行时] Browser --> Exec[隔离沙箱执行与控制台代理] Browser --> RT[docmd-runtime 响应式变量联动]

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 /:::
js 本地脚本文件

脚本示例 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>
```
:::

实时渲染的交互组件:

html 实时通知交互卡片

脚本示例 3:JavaScript 脚本执行与控制台交互

在客户端沙箱中运行 JavaScript 脚本,完整支持 console.log、console.info 拦截与函数返回值显示:

js 客户端指标监控器

关联文档与参考