React Native Storybook 8

Storybook 是业界标准的 UI 组件构建、文档记录和隔离测试工作台。它不仅广泛用于构建 Web UX，而且是 React Native 唯一的组件工作台，被 Amazon、Shopify、Brex、Wealthsimple、Kraken 等全球众多移动团队使用。

在过去五年里，我们努力缩小 React Native Storybook 和快速发展的 Web 版本之间的差距。今天，我很高兴地宣布，我们终于实现了这一重大里程碑。React Native 8.3 版的 Storybook 是统一这两个项目的发布版本。

它包括

• 🤝 与 Web 版统一的发布计划
• 📱 全新的移动 UI
• ↔️ 新的宽屏布局
• ⚙️ 简化的 Metro 配置
• 🔁 改进的热重载
• 🏆 稳定的 React Native Web 支持

与 Web 版统一的发布计划

在深入了解 8.3 版的各项功能改进之前，为什么这个版本如此重要？这是 React Native (RN) Storybook 的首席维护者 Danny Williams 四年心血的结晶。

Danny 于 2020 年开始维护 React Native Storybook。多年来，他牺牲了无数个夜晚和周末，首先是为了维持项目的运转，然后是为了完成一项艰巨的任务——将 RN Storybook 与 Web 版本重新统一。

在此期间，React Native Storybook 比 Web Storybook 落后了一个主版本。在一个像 Storybook 这样快速发展的项目中，这意味着 RN 用户获得的体验比 Web 用户差，而同时使用 RN 和 Web 的团队则受到版本滞后的阻碍。

现在不会了！RN Storybook 8.3 包含了 Web 版的所有核心功能。代码库支持 RN 和 Web 之间的共享，这意味着我们的团队可以致力于确保 Web 的主要版本在未来不会破坏 RN。这对该项目来说是一个史诗级的里程碑。

全新的移动 UI

RN Storybook 8 中最显著的变化是全新的 UI，这是一个完整的重新设计，针对移动设备优化了 Storybook 的 UI。现在，导航侧边栏和插件面板都从页面底部弹出，方便在手机上用拇指操作。与前一个版本不同，这些面板可以与 Storybook 的主“画布”区域干净地共存。

自 Storybook 8 引入以来，这已经是 Storybook for Web 的一项重大改进，但对于完全运行在移动设备上的 React Native 来说，其意义更为重大。

新的宽屏布局

React Native 也越来越多地用于平板电脑、桌面和 Web 应用程序。为了跟上步伐，我们引入了新的宽屏布局，与 Storybook for Web 的桌面布局相匹配。

简化的 Metro 配置

为了更清晰地配置 Storybook，我们引入了新的 withStorybook 包装器来处理你的 Metro 配置。

// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const withStorybook = require("@storybook/react-native/metro/withStorybook");

const defaultConfig = getDefaultConfig(__dirname);

module.exports = withStorybook(defaultConfig);

该包装器还接受一个选项对象来定制行为。例如，如果你想在 RN Storybook 旁边启动一个 WebSocket 服务器，以便它可以被远程控制（例如，通过 Storybook Web UI、VSCode 扩展或测试脚本）。

// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const withStorybook = require("@storybook/react-native/metro/withStorybook");

const defaultConfig = getDefaultConfig(__dirname);

module.exports = withStorybook(defaultConfig, {
  websockets: {
    port: 7007,
    host: 'localhost',
  },
});

你还可以使用选项来指定备用的配置目录，或根据环境变量完全禁用 Storybook。更多信息，请参阅 文档。

改进的热重载

在旧版本中，RN Storybook 可以热重载现有的 stories，并支持从现有的 story 文件中添加/删除 stories。但是，添加和删除 story 文件需要重启。

现在，得益于 Metro 的改进，你可以添加和删除与 .storybook/main.js 中 stories glob 匹配的 story 文件，Storybook 会自动识别它们。

请注意，使用新的文件 glob 更新 main.js 仍然需要运行 storybook-generate 或重启 Metro。

React Native Web 已稳定

为了庆祝我们的 React Native 8 版本发布，我们还修复了 React Native Web (RNW) Storybook 的各种 bug 和兼容性问题，这是我们基于 Web 的 React Native 组件工作台。

如果你还不熟悉 RNW Storybook，它对 Storybook for RN 是一个很好的补充。虽然 RN 作为原生应用程序运行在你的设备上，但 React Native Web 在浏览器中以 React DOM 的形式运行。因此，它完全兼容 Web Storybook，包括：

• 📚 Storybook Docs（自动文档 + MDX）
• 🧪 Storybook Test Runner 和其他测试工具
• 🧩 大部分 Storybook 的插件，包括 A11y、i18n 等等。
• 👁️ 视觉测试工具，如 Chromatic

最重要的是，它提供了一个可以从 Web 轻松访问的、易于浏览的 stories 集合。

当然，Web 模拟只是一个近似值，某些 RN 组件/功能/交互只在原生设备上可用。

但 RN Storybook 和 RNW Storybook 可以在同一个项目中并存，让你能够拥有两全其美！请参阅 文档，了解如何在你的项目中设置 Storybook RNW。

立即试用

如果你正在开始一个新的 RN 项目，请查看已更新至 v8 的 Storybook for React Native 教程！

如果你正在升级现有的 RN 项目，请先将所有 storybook 依赖项更新到 8.3.1 或更高版本。

// package.json
{
  "devDependencies": {
    "@storybook/react-native": "^8.3.1",
    "@storybook/react": "^8.3.1",
    "@storybook/addon-ondevice-controls": "^8.3.1",
    "@storybook/addon-ondevice-actions": "^8.3.1",
    "@storybook/addon-ondevice-backgrounds": "^8.3.1",
    "@storybook/addon-ondevice-notes": "^8.3.1"
  }
}

然后，向你的项目添加几个新依赖项，这些是更新后的 UI 所必需的。如果你使用 Expo，expo install 是获取与你的设置兼容的版本最安全的方式。

npx expo install react-native-reanimated react-native-gesture-handler @gorhom/bottom-sheet react-native-svg

如果你使用 RN CLI，你需要确保使用与你的 React Native 版本兼容的版本。

npm install react-native-reanimated react-native-gesture-handler @gorhom/bottom-sheet react-native-svg

接下来，通过运行 yarn storybook-generate 来重新生成你的 .storybook/storybook.requires.ts 文件。你应该会在文件中看到一个新的 updateView 函数。

最后，应用新的 Metro 配置包装器来应用 Storybook 设置。

// metro.config.js
const withStorybook = require('@storybook/react-native/metro/withStorybook');

const config = /* existing configuration */;
module.exports = withStorybook(config);

我们在 RN Storybook 的 MIGRATION.md 中记录了本次版本和先前版本的升级过程。

下一步是什么？

我们很高兴终于与 Storybook for Web 同步了。在 8.3 版本发布后，我们计划进行一系列改进：

• 将原生控件与 Web 版保持一致
• 集成和工具的测试
• 🤔… 让我们知道你的建议！

最重要的是，我们计划保持 Storybook for React Native 与 Storybook Web 版同步。

感谢阅读，如果你有任何反馈，请告诉我们，以便我们继续改进。要与我们联系，请加入我们的 Discord 或在 GitHub 上发起讨论。要了解 React Native Storybook 的最新动态，你可以关注 Twitter 上的 Danny_H_W。