Sandpack 使用指南：从基础配置到高级定制-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00615/article/details/148505079

Sandpack 使用指南：从基础配置到高级定制

sandpack A component toolkit for creating live-running code editing experiences, using the power of CodeSandbox. 项目地址: https://gitcode.com/gh_mirrors/sa/sandpack

什么是 Sandpack

Sandpack 是一个强大的浏览器端代码沙盒环境，它允许开发者在网页中直接嵌入可交互的代码编辑器。与传统的静态代码展示不同，Sandpack 提供了完整的代码执行环境，支持实时预览和编辑，非常适合用于文档演示、教学示例或在线代码实验。

核心概念：预设模板（Presets）

Sandpack 的核心组件 <Sandpack /> 被称为预设（preset），它封装了所有独立组件并提供了合理的默认配置。预设机制使得 Sandpack 易于使用，同时保留了高度的可配置性。

模板系统

每个 Sandpack 实例默认使用预定义的模板启动。模板包含了项目所需的所有文件和依赖项：

vanilla：纯 JavaScript/HTML/CSS 环境（默认模板）
react：基于 create-react-app 的 React 项目
vue：基于 vue-cli 的 Vue 项目
angular：Angular 项目模板
以及其他常见框架的模板

选择模板非常简单，只需在组件中指定 template 属性即可：

<Sandpack template="react" />

自定义文件内容

基础文件覆盖

在实际使用中，我们通常需要替换模板中的默认内容。通过 files 属性，可以轻松实现文件内容的覆盖：

<Sandpack
  template="react"
  files={{
    "/App.js": `export default function App() {
  return <h1>你好 Sandpack</h1>
}`,
  }}
/>

关键点：

files 接受一个对象，其中键是文件的相对路径
路径必须完整，包括文件在模板中的实际位置（如 /src/index.js）
只有通过 files 指定的文件会显示在标签页中，其他模板文件仍会被打包但不显示

高级文件配置

除了简单的字符串内容，文件还支持对象格式的详细配置：

files={{
  '/Button.js': {
    code: `export default () => <button>点击</button>`,
    readOnly: true,   // 设为只读
    active: true,     // 设为当前活动文件
    hidden: false     // 控制标签页可见性
  }
}}

注意：

如果没有指定 active 文件，默认使用第一个文件
即使文件被标记为 hidden，如果同时设为 active，仍然会显示

依赖管理

添加 NPM 依赖

通过 customSetup.dependencies 可以添加额外的 npm 包：

<Sandpack
  template="react"
  customSetup={{ 
    dependencies: { 
      "lodash": "^4.17.21",
      "react-icons": "latest"
    }
  }}
/>

外部静态资源

使用 options.externalResources 可以引入 CDN 资源：

<Sandpack
  options={{
    externalResources: [
      "https://cdn.tailwindcss.com",
      "https://unpkg.com/axios/dist/axios.min.js"
    ]
  }}
/>

这些资源会被注入到 HTML 的 head 中，全局可用。

高级配置技巧

只读模式控制

Sandpack 提供了灵活的只读控制：

单个文件只读：

files={{
  "/utils.js": {
    code: utilityCode,
    readOnly: true
  }
}}

全局只读：

<Sandpack
  options={{
    readOnly: true,
    showReadOnly: false // 隐藏只读标签
  }}
/>

文件可见性与活动控制

通过 visibleFiles 和 activeFile 可以精确控制界面显示：

<Sandpack
  options={{
    visibleFiles: ["/src/App.js", "/src/components/Button.js"],
    activeFile: "/src/components/Button.js"
  }}
/>

注意：一旦设置了这些选项，文件对象中的 hidden 和 active 标记将被忽略。

自定义入口文件

可以指定不同的打包入口文件：

<Sandpack
  customSetup={{
    entry: "/src/main.js"
  }}
/>

警告：更改入口文件路径时，需要确保所有相关文件都在控制范围内，模板的默认配置可能不再适用。

完全自定义设置

如果预设模板不能满足需求，可以完全自定义设置：

<Sandpack
  customSetup={{
    entry: "/index.js",
    environment: "create-react-app",
    dependencies: {
      react: "^18.0.0",
      "react-dom": "^18.0.0"
    },
    files: {
      "/index.js": {
        code: `...`
      }
    }
  }}
/>