Playground 演练场容器

::: playground 容器将静态代码示例转化为交互式、自包含的代码演练场。读者可以直接在浏览器中实时编辑代码，通过一键点击或快捷键执行代码，查看结构化的控制台输出，在实时渲染视图与底层代码之间无缝切换，并即时预览 HTML/CSS 组件。

容器语法

演练场容器支持包含代码块的普通容器、直接引用代码库外部脚本文件的自闭合容器，以及标准代码围栏语法。

1. 包含代码块的普通容器

使用 ::: playground 块将普通代码包裹起来：

::: playground title="响应式变量探索器" icon:code live
```js
const buildYear = docmd.var.get("docmd.buildYear");
const siteTitle = docmd.var.get("site.title");

console.log("站点标题:", siteTitle);
console.log("构建年份:", buildYear);

// 修改客户端响应式页面变量
docmd.var.set("user.plan", "Enterprise");
console.info("已将用户方案更新为:", docmd.var.get("user.plan"));
return `当前年份: ${buildYear}`;
```
:::

以下是由 docmd 直接渲染的实时可交互演练场：

::: playground title=“响应式变量探索器” icon:code live

const buildYear = docmd.var.get("docmd.buildYear");
const siteTitle = docmd.var.get("site.title");

console.log("站点标题:", siteTitle);
console.log("构建年份:", buildYear);

// 修改客户端响应式页面变量
docmd.var.set("user.plan", "Enterprise");
console.info("已将用户方案更新为:", docmd.var.get("user.plan"));
return `当前年份: ${buildYear}`;

:::

2. Live 与 Code 选项卡切换 (tabs)

当在容器配置中启用 tabs（或 mode="tabs"）时，顶栏会渲染交互式的 Live（实时）与 Code（代码）选项卡，允许读者在运行效果与底层源码之间即时切换：

::: playground tabs title="交互式组件（Live 与 Code 切换）" icon:layout live
```html
<div style="padding: 18px; border-radius: 10px; background: #0f172a; color: #38bdf8; font-family: system-ui, sans-serif; border: 1px solid #1e293b;">
  <div style="display:flex; align-items:center; gap:8px; margin-bottom:8px;">
    <span style="display:inline-block; width:10px; height:10px; border-radius:50%; background:#10b981;"></span>
    <strong style="color:#f8fafc; font-size:14px;">选项卡预览模式已激活</strong>
  </div>
  <p style="margin:0 0 12px 0; font-size:13px; color:#94a3b8; line-height:1.5;">
    通过顶部工具栏的选项卡在 <strong>Live</strong> 实时渲染与 <strong>Code</strong> 源代码视图之间自由切换。
  </p>
  <button style="padding:6px 14px; background:#0284c7; color:#fff; border:none; border-radius:6px; font-size:12px; font-weight:600; cursor:pointer;" onclick="console.log('在选项卡预览中触发了操作！')">
    触发控制台日志
  </button>
</div>
```
:::

支持选项卡切换的实时运行演练场：

::: playground tabs title=“交互式组件（Live 与 Code 切换）” icon:layout live

<div style="padding: 18px; border-radius: 10px; background: #0f172a; color: #38bdf8; font-family: system-ui, sans-serif; border: 1px solid #1e293b;">
  <div style="display:flex; align-items:center; gap:8px; margin-bottom:8px;">
    <span style="display:inline-block; width:10px; height:10px; border-radius:50%; background:#10b981;"></span>
    <strong style="color:#f8fafc; font-size:14px;">选项卡预览模式已激活</strong>
  </div>
  <p style="margin:0 0 12px 0; font-size:13px; color:#94a3b8; line-height:1.5;">
    通过顶部工具栏的选项卡在 <strong>Live</strong> 实时渲染与 <strong>Code</strong> 源代码视图之间自由切换。
  </p>
  <button style="padding:6px 14px; background:#0284c7; color:#fff; border:none; border-radius:6px; font-size:12px; font-weight:600; cursor:pointer;" onclick="console.log('在选项卡预览中触发了操作！')">
    触发控制台日志
  </button>
</div>

:::

3. 初始展示代码的选项卡容器 (tabs:code)

如果希望默认向读者展示代码，同时提供即刻切换到实时输出的选项，可指定 tabs:code 或 tabs view="code"：

::: playground tabs:code title="选项卡容器（代码优先）" icon:code live
```js
// 递归计算阶乘
function factorial(n) {
  if (n <= 1) return 1;
  return n * factorial(n - 1);
}

const num = 5;
const result = factorial(num);
console.log(`${num} 的阶乘为:`, result);
return result;
```
:::

代码优先的实时工作演练场：

::: playground tabs:code title=“选项卡容器（代码优先）” icon:code live

// 递归计算阶乘
function factorial(n) {
  if (n <= 1) return 1;
  return n * factorial(n - 1);
}

const num = 5;
const result = factorial(num);
console.log(`${num} 的阶乘为:`, result);
return result;

:::

4. 动态引用代码文件的自闭合容器

无需手动将代码复制粘贴到文档中，您可以通过 src 属性直接引用代码库中的实际脚本或组件文件：

::: playground src="./snippets/counter.js" title="动态引用脚本文件" icon:cpu live /:::

引用本地代码文件 [./snippets/counter.js](file:///Users/mac/Workspace/GitHub/docmd-io/docs/docmd-main/v09/zh/content/containers/snippets/counter.js) 的实时演练场：

::: playground src=“./snippets/counter.js” title=“动态引用脚本文件” icon:cpu live /:::

5. 源码丢失时的优雅警告降级

如果指定的脚本文件路径无效或已被重命名，docmd 会展示醒目的警告提示栏并在编辑器中整洁打印备用代码，而不会导致构建中断：

::: playground src="./snippets/missing-script.js" title="缺少脚本文件的友好警告" icon:alert-triangle /:::

优雅错误降级的实时演练场：

::: playground src=“./snippets/missing-script.js” title=“缺少脚本文件的友好警告” icon:alert-triangle /:::

6. 代码围栏语法

对于无需容器嵌套的快速示例，只需在 Markdown 代码围栏后添加 playground：

```js playground title="斐波那契快速执行器" icon:zap
function fib(n) {
  return n <= 1 ? n : fib(n - 1) + fib(n - 2);
}

console.log("Fib(10) =", fib(10));
return fib(10);
```

实时可运行代码围栏示例：

function fib(n) {
  return n <= 1 ? n : fib(n - 1) + fib(n - 2);
}

console.log("Fib(10) =", fib(10));
return fib(10);

容器属性说明

::: playground 容器支持丰富的元数据配置属性：

交互能力

console.log("来自 docmd 的问候！");
console.info("状态数据:", { status: "active", version: "0.9.9" });
console.warn("注意: 测试警告提示");
return "执行圆满完成";

<button style="padding: 10px 20px; background: #6366f1; color: white; border: none; border-radius: 8px; font-weight: 600; cursor: pointer; transition: transform 0.2s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'" onclick="alert('组件被成功点击！')">
  交互式组件按钮
</button>

console.log("当前主题:", window.docmd?.theme?.get() || "light");
console.log("Docmd 引擎版本:", window.docmd?.var?.get("docmd.version") || "0.9.9");
console.log("Git 分支:", window.docmd?.var?.get("docmd.gitBranch") || "main");
return "SDK 调用正常";

:::
:::

键盘快捷键

演练场编辑器提供主流 IDE 标准快捷键，提升操作效率：

• Cmd + Enter (macOS) 或 Ctrl + Enter (Windows/Linux): 即刻执行当前代码块 * Tab: 插入 2 个空格缩进，避免浏览器焦点失焦 * Shift + Tab: 消除当前行或选区的缩进

关联插件技术文档

有关 AST 解析钩子、构建期脚本安全解析、异常容错机制以及全局插件配置选项的深入技术说明，请参阅 Playground 插件技术架构与参考指南。