GitHub_Trending/rea/react-conf-app：Storybook 组件文档与开发环境搭建

【免费下载链接】react-conf-app 项目地址: https://gitcode.com/GitHub_Trending/rea/react-conf-app

在 React 应用开发过程中，组件的复用与测试是提升效率的关键。本文将以 GitHub 热门项目 GitHub_Trending/rea/react-conf-app 为例，详细介绍如何为该项目搭建 Storybook（组件文档工具）环境，帮助开发者更高效地管理和测试组件。通过本文，你将学会：配置 Storybook 开发环境、编写组件故事（Story）、集成现有 UI 组件，并利用项目资源优化文档展示。

项目基础与环境准备

react-conf-app 是基于 Expo 构建的 React Conf 2025 会议应用，使用 TypeScript 开发，包含丰富的 UI 组件和页面。项目结构清晰，核心组件位于 src/components/ 目录，如 Button.tsx、SpeakerImage.tsx 等。

开发环境依赖

项目使用 Bun 作为包管理器，依赖配置文件为 package.json。搭建 Storybook 前需确保已安装以下工具：

• Node.js（v18+）
• Bun（v1.0+）
• Git

初始项目克隆与依赖安装

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/rea/react-conf-app.git
cd react-conf-app

# 安装依赖
bun install

Storybook 环境搭建

安装 Storybook 核心依赖

# 添加 Storybook 及 React 支持
bun add -D @storybook/react @storybook/expo @storybook/addon-essentials @storybook/addon-interactions storybook

# 安装 Expo 集成插件（适配 React Native）
bun add -D @storybook/react-native @storybook/addon-ondevice-actions @storybook/addon-ondevice-controls

初始化 Storybook 配置

执行以下命令生成默认配置文件：

npx storybook@latest init

初始化过程中会自动创建以下关键文件：

• .storybook/main.ts：Storybook 核心配置
• .storybook/preview.tsx：全局预览配置
• src/stories/：默认示例故事目录（可替换为项目实际组件路径）

适配 Expo 项目配置

修改 .storybook/main.ts 以支持 Expo 环境：

import type { StorybookConfig } from '@storybook/react-native';

const config: StorybookConfig = {
  stories: ['../src/components/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-ondevice-controls',
    '@storybook/addon-ondevice-actions',
    '@storybook/addon-essentials',
  ],
  framework: {
    name: '@storybook/react-native',
    options: {},
  },
};

export default config;

编写组件故事（Story）

以项目中的 Button.tsx 组件为例，创建故事文件 src/components/Button.stories.tsx：

import React from 'react';
import { StoryObj, Meta } from '@storybook/react-native';
import Button from './Button';

// 元数据定义：描述组件基本信息
const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  argTypes: {
    label: { control: 'text' },
    onPress: { action: 'pressed' },
    variant: { 
      control: 'select', 
      options: ['primary', 'secondary', 'outline'] 
    },
  },
};

export default meta;

// 默认故事（基础用法）
export const Default: StoryObj<typeof Button> = {
  args: {
    label: 'Click Me',
    variant: 'primary',
  },
};

// 次要样式故事
export const Secondary: StoryObj<typeof Button> = {
  args: {
    label: 'Secondary Button',
    variant: 'secondary',
  },
};

组件故事目录规范

建议将故事文件与组件文件放在同一目录，采用 [组件名].stories.tsx 命名格式，例如：

• src/components/Button.tsx
• src/components/Button.stories.tsx

集成项目主题与资源

全局样式适配

在 .storybook/preview.tsx 中导入项目主题 src/theme.ts：

import { View } from 'react-native';
import { withTheme } from '../src/theme';

// 应用全局主题包装器
export const decorators = [
  (Story) => (
    <View style={{ flex: 1, padding: 20 }}>
      <Story />
    </View>
  ),
];

// 全局参数配置
export const parameters = {
  actions: { argTypesRegex: '^on[A-Z].*' },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
};

静态资源引用

项目中的图片资源位于 assets/images/ 目录，例如会议 Logo conf.png。在故事中引用资源时需使用相对路径：

// 在 SpeakerImage.stories.tsx 中引用图片
import React from 'react';
import { StoryObj } from '@storybook/react-native';
import SpeakerImage from './SpeakerImage';
import speakerPlaceholder from '../../assets/images/reactlogo-white.png';

export const Default: StoryObj<typeof SpeakerImage> = {
  args: {
    source: { uri: speakerPlaceholder },
    size: 80,
  },
};

运行 Storybook 开发服务器

启动命令配置

在 package.json 中添加脚本：

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "storybook:build": "storybook build"
  }
}

启动 Storybook

bun run storybook

浏览器将自动打开 http://localhost:6006，展示组件文档界面。手机端可通过 Expo Go 扫描二维码预览（需确保设备与开发机在同一网络）。

组件文档示例与效果

按钮组件（Button）文档

• 变体展示：primary/secondary/outline 三种样式
• 交互控制：支持动态修改 label、disabled 状态
• 事件监听：onPress 动作日志输出

演讲者卡片（SpeakerImage）组件

• 尺寸调节：通过 controls 面板修改 size 属性
• 加载状态：展示图片加载中的占位效果
• 圆角样式：支持圆形/方形边框切换

常见问题与解决方案

Expo 环境样式冲突

问题：Storybook 中组件样式与 App 中不一致。
解决：在 .storybook/preview.tsx 中导入项目全局样式 src/theme.ts，确保样式上下文统一。

字体图标不显示

问题：项目中使用的自定义字体 Montserrat 未在 Storybook 中加载。
解决：使用 @storybook/addon-styling 插件加载字体：

// .storybook/main.ts 中添加配置
import { loadFonts } from '../src/theme';

async function setup() {
  await loadFonts();
}

setup();

总结与扩展

通过本文步骤，已成功为 react-conf-app 项目搭建 Storybook 环境，实现了组件的可视化开发与文档化管理。后续可进一步扩展：

• 添加 @storybook/addon-docs 生成静态文档站点
• 集成 Chromatic 进行组件视觉测试
• 自动化部署文档至 GitHub Pages

项目的组件库文档可帮助团队协作时统一设计规范，同时为新开发者提供直观的组件使用示例，提升整体开发效率。

【免费下载链接】react-conf-app 项目地址: https://gitcode.com/GitHub_Trending/rea/react-conf-app