在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

airbnb/javascript

菜单

React/JSX 风格指南

相关源文件

目的与范围

本文档概述了 Airbnb React/JSX 风格指南，这是一套用于开发 React 应用程序的全面最佳实践和约定。它涵盖了组件结构、命名约定、JSX 格式化、props 管理、组件生命周期组织以及其他 React 特定的模式。对于非 React 特定的 JavaScript 风格指南，请参阅 JavaScript 风格指南。

React/JSX 风格指南既是开发人员的参考文档，也是 Airbnb JavaScript 代码库中通过 ESLint 配置实现自动化样式强制执行的基础。

风格指南结构和 ESLint 集成

React/JSX 风格指南与 ESLint 配置协同工作，以在 React 应用程序中强制执行一致的代码风格。

图示：React 风格指南实现

来源：packages/eslint-config-airbnb/rules/react.js1-620 react/README.md1-757

组件类型和模式

风格指南根据组件的目的和行为，为何时使用不同类型的 React 组件建立了清晰的模式。

图示：React 组件决策流程

来源：react/README.md34-74 react/README.md657-730

组件类型

根据功能选择组件类型

组件类型何时使用示例
类组件 (Class Component)当需要 state 或 refs 时class MyComponent extends React.Component
函数组件 (Function Component)用于无状态组件function MyComponent(props) { return <div>{props.text}</div>; }
高阶组件 (HOC - Higher Order Component)用于组件组合和复用function withData(WrappedComponent) { ... }

风格指南明确不鼓励使用

  • React.createClass 模式 (已弃用)
  • Mixins (被认为有害)
  • 类组件方法的箭头函数

来源：react/README.md34-74 react/README.md76-80

命名和文件组织

命名约定

ComponentName.jsx       // Component file
index.jsx               // Root component of a directory
  • 组件名称和文件名使用PascalCase：ReservationCard.jsx
  • 组件实例使用camelCase：const reservationItem = <ReservationCard />
  • HOC 应显式设置一个 displayName，其中包含两个组件名称：withFoo(WrappedComponent)
  • 对于目录根组件，请使用 index.jsx 并通过目录名导入

来源：react/README.md83-155 packages/eslint-config-airbnb/rules/react.js329

JSX 语法和格式化

对齐和间距

风格指南为 JSX 格式化提供了明确的规则

格式化规则示例
多行 props 对齐Props 应在新行开始，并保持一致的缩进
闭合括号位置多行组件的行对齐
自闭合标签没有子组件时必需
JSX 中的空格花括号内不留空格，自闭合标签前留空格
JSX 缩进2 个空格，与整体代码风格一致
括号多行 JSX 周围必需

来源：react/README.md173-237 packages/eslint-config-airbnb/rules/react.js76-82 packages/eslint-config-airbnb/rules/react.js85-86 packages/eslint-config-airbnb/rules/react.js380-385

引号和表达式

  • JSX 属性值使用双引号（"）
  • 普通 JavaScript 使用单引号（'）
  • 在 JSX 中使用花括号（无空格）来表示 JavaScript 表达式：<Foo bar={baz} />
  • 跨越多行的表达式请使用括号括起来

来源：react/README.md240-258 packages/eslint-config-airbnb/rules/react.js25-26

Props 管理

Props 命名和格式化

  • Props 名称使用camelCase
  • 组件 Props 值使用PascalCase
  • 布尔值为 true 时省略值：<Input disabled /> (而不是 disabled={true})
  • 非必需 props 始终定义 defaultProps
  • 始终使用 propTypes 验证 props

Props 组织示例

来源：react/README.md290-467 react/README.md227-232 packages/eslint-config-airbnb/rules/react.js397-401

Props 展开 (Props Spreading)

  • 谨慎使用 props 展开
  • 展开 props 时，过滤掉不必要的
  • 适用场景包括 HOC 和测试

来源：react/README.md431-482 packages/eslint-config-airbnb/rules/react.js502-508

组件方法和组织

事件处理器 (Event Handlers)

  • 语义化命名事件处理器

    • 将方法作为 handler 传递给子组件时，使用 handle 前缀
    • 直接处理事件的方法，使用 on 前缀

  • 在构造函数中绑定事件处理器，而不是在 render 方法中

来源：react/README.md555-616 packages/eslint-config-airbnb/rules/react.js89-93

组件方法排序

风格指南规定了类组件方法推荐的顺序

  1. 静态方法
  2. 构造函数
  3. 生命周期方法 (按执行顺序)
  4. 事件处理程序
  5. Getter 方法
  6. Render 方法 (最后是 render())

ESLint 通过 react/sort-comp 规则强制执行此顺序，该规则定义了特定的分组及其顺序

order: [
  'static-variables',
  'static-methods',
  'instance-variables',
  'lifecycle',
  '/^handle.+$/',
  '/^on.+$/',
  'getters',
  'setters',
  'instance-methods',
  'everything-else',
  'rendering',
]

来源： react/README.md657-705 packages/eslint-config-airbnb/rules/react.js249-296

可访问性指南

风格指南包含几项以可访问性为中心的建议

  • 始终在 <img> 标签中包含 alt 属性
  • 不要在 alt 文本中包含“image”或“picture”等冗余词语
  • 仅使用有效的 ARIA 角色
  • 不要在元素上使用 accessKey
  • 避免使用数组索引作为 key prop

来源： react/README.md325-376 packages/eslint-config-airbnb/rules/react.js394-395

关键 ESLint 规则

风格指南通过许多 ESLint 规则强制执行。其中一些最重要的包括

规则目的设置
react/jsx-filename-extension强制 JSX 使用 .jsx 文件只允许在 .jsx 文件中使用
react/jsx-no-bind防止在 JSX 属性中使用 .bind()错误（有例外）
react/destructuring-assignment强制 props/state 解构始终必需
react/no-array-index-key防止使用索引作为 key错误
react/prefer-stateless-function鼓励函数组件错误（PureComponents 除外）
react/prop-types需要 prop 类型验证错误
react/sort-comp强制组件方法排序详细配置的错误
react/jsx-props-no-spreading控制 props 展开HTML 元素的错误

来源： packages/eslint-config-airbnb/rules/react.js108-116 packages/eslint-config-airbnb/rules/react.js227-233 packages/eslint-config-airbnb/rules/react.js394-395 packages/eslint-config-airbnb/rules/react.js446-447 packages/eslint-config-airbnb/rules/react.js502-508

总结

Airbnb React/JSX 风格指南为开发 React 应用程序提供了全面的指导，以实现一致、可维护的模式。它涵盖了从组件声明到 props 管理再到可访问性考虑的方方面面。

这些约定通过 eslint-config-airbnb 的 React 规则集强制执行，使团队能够自动验证代码是否符合这些标准。该风格指南是更大的 Airbnb JavaScript 风格指南系统的重要组成部分，为核心 JavaScript 指南提供了 React 特定的扩展。

来源： react/README.md1-757 packages/eslint-config-airbnb/rules/react.js1-620