React Styleguidist 与第三方库集成指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00187/article/details/148394377

React Styleguidist 与第三方库集成指南

react-styleguidist Isolated React component development environment with a living style guide 项目地址: https://gitcode.com/gh_mirrors/re/react-styleguidist

前言

React Styleguidist 是一个优秀的 React 组件文档工具，但在实际项目中，我们常常需要将其与各种第三方库配合使用。本文将深入探讨 Styleguidist 的工作原理，以及如何与 Redux、Relay、Styled-components 等流行库进行集成。

Styleguidist 工作原理解析

Styleguidist 的核心工作机制包含两个关键部分：

组件加载：通过配置文件加载项目中的 React 组件
文档生成：使用 react-docgen 工具解析组件并生成文档

react-docgen 采用静态分析方式解析组件代码，这意味着：

它不会执行任何 JavaScript 代码
只能识别标准的 React 组件定义方式
对于高阶组件(HOC)包装的组件或动态生成的组件，需要特殊处理

处理高阶组件的最佳实践

对于被高阶组件包装的组件，推荐采用双导出模式：

import React from 'react'
import CSSModules from 'react-css-modules'
import styles from './Button.css'

// 基础组件 - 用于文档生成
export function Button({ color, size, children }) {
  /* ... */
}

// 增强组件 - 用于实际渲染
export default CSSModules(Button, styles)

上下文控制机制

每个示例都在独立的 React 根节点中渲染。要控制全局上下文，可以通过自定义 Wrapper 组件实现：

// styleguide.config.js
const path = require('path')
module.exports = {
  styleguideComponents: {
    Wrapper: path.join(__dirname, 'src/styleguide/Wrapper')
  }
}

TypeScript 支持说明

虽然 Styleguidist 原生支持 TypeScript，但对于从 node_modules 重新导出的第三方组件，需要使用 react-docgen-typescript 来增强支持：

安装 react-docgen-typescript
更新配置文件：

module.exports = {
  propsParser: require('react-docgen-typescript')
    .withCustomConfig('./tsconfig.json')
    .parse
}

主流库集成方案

Redux 集成

单组件使用方案

在 Markdown 示例中直接创建 Store：

// ```jsx inside Markdown
import { Provider } from 'react-redux'
import configureStore from '../utils/configureStore'
const initialState = { app: { name: 'Pizza Delivery' } }
const store = configureStore({ initialState })
;<Provider store={store}>
  <App greeting="Choose your pizza!" />
</Provider>

全局使用方案

创建自定义 Wrapper 组件：

// src/styleguide/Wrapper.js
import React from 'react'
import { Provider } from 'react-redux'
import configureStore from '../utils/configureStore'

const initialState = { app: { name: 'Pizza Delivery' } }
const store = configureStore({ initialState })

export default function Wrapper({ children }) {
  return <Provider store={store}>{children}</Provider>
}

Relay 集成方案

第一步：模拟 Relay 环境

创建模拟 Relay 实现
配置 webpack 别名替换

// styleguide.config.js
module.exports = {
  webpackConfig: {
    resolve: {
      alias: {
        'react-relay': path.join(__dirname, 'src/styleguide/FakeRelay'),
        'real-react-relay': 'react-relay'
      }
    }
  }
}

第二步：提供示例数据

// styleguide.config.js
module.exports = {
  context: {
    sample: path.join(__dirname, 'src/styleguide/sample_data')
  }
}

在示例中使用：

// ```jsx inside Markdown
<MyComponent object={sample.object} />

CSS-in-JS 解决方案

Styled-components

关键点：必须添加 @component JSDoc 注释

import styled from 'styled-components'

const Button = styled.button`
  background-color: salmon;
  color: snow;
`

Button.propTypes = {
  children: PropTypes.node
}

/** @component */
export default Button

注意事项：

仅支持模板字符串语法
不支持对象语法和函数调用形式

主题支持

创建 ThemeProvider 包装器：

// src/Provider.js
import { ThemeProvider } from 'styled-components'
import theme from './theme'

export default function Provider({ children }) {
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>
}

Emotion 和 Theme UI

集成方式与 Styled-components 类似，遵循相同的模式。

CSS Modules 方案

使用 react-css-modules 时，同样需要双导出模式：

import CSSModules from 'react-css-modules'
import styles from './Button.css'

export function Button(props) { /* ... */ }

export default CSSModules(Button, styles)

Styletron 集成

单组件使用

// ```jsx inside Markdown
import { StyletronProvider } from 'styletron-react'
;<StyletronProvider styletron={new Styletron()}>
  <App />
</StyletronProvider>

全局使用

创建 Wrapper 组件：

// src/styleguide/Wrapper.js
export default function Wrapper({ children }) {
  return (
    <StyletronProvider styletron={new Styletron()}>
      {children}
    </StyletronProvider>
  )
}