#管理交互式示例 (<Go>)

交互式示例允许用户直接在文档中预览和编辑代码。本指南解释了如何使用专用工作区和 <Go> 组件来管理这些示例。

#概览

交互式示例系统允许您在文档中嵌入实时、可运行的 Lynx 代码。它包括：

1. 源包 (Source Packages)：示例是位于 packages/lynx-example-packages/ 中的真实 npm 包。
2. 构建过程 (Build Process)：脚本将这些包打包为网站的静态资源。
3. <Go> 组件：在 MDX 文件中渲染交互式编辑器和预览的 React 组件。

#1. 使用 <Go> 组件

要在文档中嵌入交互式示例，请使用 <Go> 组件。

#基本用法

从 @lynx 导入 Go 并提供 example ID（对应于包目录名称）。

import { Go } from '@lynx';

<Go example="view" />;

#组件属性

#入口选择

scripts/lynx-example.js 会为每个 Lynx bundle 创建一个 templateFiles 条目。默认情况下，name 是移除 .lynx.bundle 后的 bundle basename： 例如，dist/main.lynx.bundle 会生成 name: "main"。当 basename 冲突时， 生成器会添加足够的父路径片段，得到唯一的路径后缀。例如， dist/a/main.lynx.bundle 和 output/a/main.lynx.bundle 会分别生成 dist/a/main 和 output/a/main。如果产物路径仍无法生成唯一名称，生成会失败。 defaultEntryName 会精确选择这个逻辑名称；它不是文件名或数组下标。

未提供入口名时，go-web 会回退到 templateFiles[0]。生成器不会为该位置 赋予特殊语义，也不会显式排序入口列表。多入口 example 建议设置 defaultEntryName，避免所选入口依赖这一回退逻辑。不存在的入口名不会静默 回退到第一个入口。

#高级示例

<Go
  example="view"
  defaultFile="src/App.tsx"
  defaultEntryName="main"
  highlight={{ 'src/App.tsx': '5-10' }}
/>

#2. 管理示例包

所有交互式示例均作为 packages/lynx-example-packages/ 工作区中的依赖项进行管理。

#目录结构

packages/lynx-example-packages/
├── package.json          # 列出所有示例依赖项的清单
├── pnpm-lock.yaml       # 示例的锁定文件
└── node_modules/        # 安装示例的位置
    └── @lynx-example/   # 官方示例的命名空间

#添加新示例

要使新示例可用于 <Go> 组件：

1. 发布包：您的示例必须是有效的 npm 包（例如 @lynx-example/my-feature）。
2. 添加依赖：将该包添加到 packages/lynx-example-packages/package.json。
3. 安装：在工作区根目录运行 pnpm install 以下载新示例。
4. 重新构建资源：网站构建过程将自动检测并打包新示例。

#3. 构建架构

对于那些对底层工作原理感兴趣的人：

• 脚本：scripts/lynx-example.js 在构建期间运行。
• 过程：
  1. 扫描 node_modules/@lynx-example/ 查找包。
  2. 识别 bundle 文件（.lynx.bundle，.web.bundle）和源代码。
  3. 为每个示例生成 example-metadata.json。
  4. 将资源复制到 docs/public/lynx-examples/。
• 运行时：<Go> 组件在运行时获取此元数据以加载编辑器和预览。