跳到主要内容

React 规则

// .eslintrc.js

module.exports = {
  extends: [
    'airbnb',
    'airbnb/hooks',
    'airbnb-typescript',
    // ...
  ],
};

React 规则​

提示

参看 Airbnb React/JSX Style Guide

注意
  • 截止至目前，eslint-config-airbnb 仍不支持 ESLint 9.x 版本，使用时请注意。使用时请使用 ESLint 8.x 版本，耐心等待 eslint-config-airbnb 升级。
  • 由于 eslint-config-airbnb 项目的一些管理问题，导致其更新比较缓慢，后续需要持续关注项目情况。部分规则可能不适用于现在项目的实际情况，请根据实际情况进行覆盖。
规则名称错误级别配置选项描述
jsx-quoteserrorprefer-double强制 JSX 属性使用双引号（如 <Component prop="value" />）
class-methods-use-thiserrorexceptMethods: [...]（包含 React 生命周期方法）类方法必须使用 this，但排除 React 生命周期方法（如 render, componentDidMount 等）
react/display-nameoffignoreTranspilerName: false关闭组件必须定义 displayName 的检查
react/forbid-prop-typeserrorforbid: ['any', 'array', 'object']禁止使用 PropTypes.any、array、object
react/forbid-dom-propsoffforbid: []关闭禁止特定 DOM 属性的检查
react/jsx-boolean-valueerrornever布尔属性值必须显式写为 ={true}（如 <Component active={true} />）
react/jsx-closing-bracket-locationerrorline-alignedJSX 闭合括号必须与标签开始对齐
react/jsx-closing-tag-locationerror-闭合标签必须与开始标签对齐
react/jsx-curly-spacingerrornever, allowMultiline: trueJSX 花括号内禁止空格，但允许多行内容
react/jsx-handler-namesoffeventHandlerPrefix: 'handle', eventHandlerPropPrefix: 'on'关闭事件处理函数命名检查
react/jsx-indent-propserror2JSX 属性缩进为 2 个空格
react/jsx-keyoff-关闭检查列表元素缺少 key 属性
react/jsx-max-props-per-lineerrormaximum: 1, when: 'multiline'单行最多 1 个属性，多行时不受限制
react/jsx-no-binderror允许箭头函数、忽略 DOM 组件等禁止在 JSX 中使用 .bind() 或箭头函数（性能优化）
react/jsx-no-duplicate-propserrorignoreCase: true禁止重复的 JSX 属性（不区分大小写）
react/jsx-no-literalsoffnoStrings: true关闭禁止 JSX 中使用字符串字面量的检查
react/jsx-no-undeferror-禁止使用未定义的 JSX 组件
react/jsx-pascal-caseerrorallowAllCaps: true组件名必须使用帕斯卡命名法（如 MyComponent）
react/sort-prop-typesoff忽略大小写、回调函数位置等关闭对 propTypes 排序的检查
react/jsx-sort-propsoff保留属性优先（如 key, ref）关闭对 JSX 属性排序的检查
react/jsx-uses-reacterror-防止 React 被标记为未使用（React 17+ 需注意）
react/jsx-uses-varserror-防止 JSX 中使用的变量被标记为未使用
react/no-dangerwarn-警告使用 dangerouslySetInnerHTML（XSS 风险）
react/no-deprecatederror-禁止使用已废弃的 React API（如 componentWillMount）
react/no-did-update-set-stateerror-禁止在 componentDidUpdate 中调用 setState（可能导致循环）
react/no-will-update-set-stateerror-禁止在 componentWillUpdate 中调用 setState
react/no-is-mountederror-禁止使用已废弃的 this.isMounted()
react/no-string-refserror-禁止使用字符串类型的 ref（推荐函数或 createRef）
react/prefer-es6-classerroralways强制使用 ES6 类组件（而非 React.createClass）
react/prefer-stateless-functionerrorignorePureComponents: true优先使用无状态函数组件（允许 PureComponent）
react/prop-typeserror必须声明 propTypes强制组件定义 PropTypes
react/react-in-jsx-scopeerror-确保 JSX 中 React 在作用域内（React 17+ 可关闭）
react/self-closing-comperror-强制没有子组件的标签自闭合（如 <Component />）
react/sort-comperror定义生命周期方法的顺序和分组强制组件方法按约定顺序排列
react/jsx-wrap-multilineserror多行 JSX 用括号包裹并换行强制多行 JSX 用括号包裹并换行
react/jsx-no-target-blankerrorenforceDynamicLinks: 'always'强制 target="_blank" 时包含 rel="noopener noreferrer"
react/jsx-filename-extensionerrorextensions: ['.jsx']仅允许在 .jsx 文件中编写 JSX
react/no-unescaped-entitieserror-禁止未转义的 HTML 实体（如 > 应写为 &gt;）
react/no-array-index-keyerror-禁止用数组索引作为 key（可能导致渲染问题）
react/no-unused-stateerror-禁止未使用的 state 字段
react/jsx-curly-brace-presenceerrorprops: 'never', children: 'never'禁止 JSX 属性或子元素中不必要的花括号
react/function-component-definitionerror强制函数组件使用函数声明或箭头函数统一函数组件的定义方式
react/jsx-no-constructed-context-valueserror-禁止将未缓存的直接创建的对象/数组作为 Context 值

React Hooks​

专为 React Hooks 设计的 Airbnb 规则集，用于确保 Hooks 的正确使用，例如依赖项的完整性检查。

module.exports = {
  extends: [
    // ...
    'plugin:react-hooks/recommended-latest',
  ],
};
注意

截止目前 eslint-config-airbnb 对 eslint-plugin-react-hooks 的支持仍为旧版本，不支持 React Compiler 规则，需要手动配置。

核心 Hooks 规则​

规则名称错误级别配置选项描述
react-hooks/rules-of-hookserror-强制遵守 React Hooks 规则（只能在函数组件或自定义 Hook 中调用）
react-hooks/exhaustive-depswarn-验证 React Hooks 的依赖数组是否包含所有必要的依赖项

React Compiler 规则​

规则名称错误级别配置选项描述
react-hooks/configerror-验证编译器配置选项
react-hooks/error-boundarieserror-验证使用错误边界而不是 try/catch 来处理子组件错误
react-hooks/component-hook-factorieserror-验证定义嵌套组件或 Hook 的高阶函数
react-hooks/gatingerror-验证门控模式的配置
react-hooks/globalserror-防止在渲染期间对全局变量进行赋值/修改
react-hooks/immutabilityerror-防止修改 props、state 和其他不可变值
react-hooks/preserve-manual-memoizationerror-确保编译器保留现有的手动记忆化
react-hooks/purityerror-通过检查已知的不纯函数来验证组件/Hook 的纯度
react-hooks/refserror-验证 ref 的正确使用，避免在渲染期间读取/写入
react-hooks/set-state-in-effecterror-防止在 Effect 中同步调用 setState
react-hooks/set-state-in-rendererror-防止在渲染期间设置状态
react-hooks/static-componentserror-验证组件是静态的，不会在每次渲染时重新创建
react-hooks/unsupported-syntaxwarn-防止使用 React Compiler 不支持的语法
react-hooks/use-memoerror-验证 useMemo Hook 的使用（检查是否有返回值）
react-hooks/incompatible-librarywarn-防止使用与记忆化不兼容的库

a11y​

规则名称错误级别配置选项描述
jsx-a11y/accessible-emojioff-已废弃，要求 Emoji 包含无障碍提示（推荐用 <span role="img"> 替代）
jsx-a11y/alt-texterrorelements: ['img', 'object', 'area', 'input[type="image"]强制图片等媒体元素必须有 alt 属性
jsx-a11y/anchor-has-contenterrorcomponents: []强制 <a> 标签必须有内容（可配置自定义组件）
jsx-a11y/anchor-is-validerrorcomponents: ['Link'], specialLink: ['to'], aspects: [...]强制 <a> 标签使用有效 href 或路由属性（如 React Router 的 to）
jsx-a11y/aria-activedescendant-has-tabindexerror-使用 aria-activedescendant 时必须定义 tabIndex
jsx-a11y/aria-propserror-强制 ARIA 属性名称合法
jsx-a11y/aria-proptypeserror-强制 ARIA 属性值类型合法
jsx-a11y/aria-roleerrorignoreNonDOM: false强制 ARIA role 值合法（默认检查非 DOM 元素）
jsx-a11y/aria-unsupported-elementserror-禁止在非交互元素上使用 ARIA 角色/属性
jsx-a11y/autocomplete-validoffinputComponents: []强制 autocomplete 属性合法（已关闭）
jsx-a11y/click-events-have-key-eventserror-强制点击事件（如 onClick）绑定键盘事件（如 onKeyUp）
jsx-a11y/control-has-associated-labelerrorignoreElements: [...], ignoreRoles: [...], depth: 5强制交互控件（如按钮）关联标签
jsx-a11y/heading-has-contenterrorcomponents: ['']强制标题标签（如 <h1>）包含内容
jsx-a11y/html-has-langerror-强制 <html> 标签定义 lang 属性
jsx-a11y/iframe-has-titleerror-强制 <iframe> 包含 title 属性
jsx-a11y/img-redundant-alterror-禁止冗余的 alt 文本（如 "image of..."）
jsx-a11y/interactive-supports-focuserror-强制交互元素（如按钮）支持聚焦
jsx-a11y/label-has-associated-controlerrorassert: 'both', depth: 25强制 <label> 关联表单控件（如 input）
jsx-a11y/langerror-强制 lang 属性值符合语言代码规范
jsx-a11y/media-has-captionerroraudio: [], video: [], track: []强制 <audio>/<video> 包含字幕
jsx-a11y/mouse-events-have-key-eventserror-强制鼠标事件（如 onMouseOver）绑定键盘事件
jsx-a11y/no-access-keyerror-禁止使用 accessKey（易与辅助技术快捷键冲突）
jsx-a11y/no-autofocuserrorignoreNonDOM: true禁止使用 autoFocus（允许非原生 DOM 元素）
jsx-a11y/no-distracting-elementserrorelements: ['marquee', 'blink']禁止干扰性元素（如 <marquee>）
jsx-a11y/no-noninteractive-element-interactionserrorhandlers: [...]禁止非交互元素（如 <div>）绑定交互事件
jsx-a11y/no-noninteractive-tabindexerrorroles: ['tabpanel']禁止非交互元素使用 tabIndex（允许 tabpanel 角色）
jsx-a11y/no-onchangeoff-已关闭，推荐用 onBlur 替代 onChange
jsx-a11y/no-redundant-roleserror-禁止冗余 ARIA 角色（如 <button role="button">）
jsx-a11y/no-static-element-interactionserrorhandlers: [...]禁止静态元素（如 <div>）绑定交互事件
jsx-a11y/role-has-required-aria-propserror-强制 ARIA 角色具备必要属性（如 checkbox 需 aria-checked）
jsx-a11y/role-supports-aria-propserror-强制 ARIA 属性与角色兼容（如 aria-hidden 不能用于 role="alert"）
jsx-a11y/scopeerror-强制 <th> 使用 scope 属性（如 scope="col"）
jsx-a11y/tabindex-no-positiveerror-禁止 tabIndex > 0（破坏自然键盘导航顺序）
jsx-a11y/label-has-foroffcomponents: [], required: { every: [...] }已废弃，强制 <label> 关联控件（改用 label-has-associated-control）

React Perf​

eslint-plugin-react-perf 旨在帮助避免 React 应用中不必要的重新渲染，提升性能。

// .eslintrc.js

module.exports = {
  extends: [
    // ...
    'plugin:react-perf/recommended',
  ],
};
规则名称错误级别配置选项描述
jsx-no-new-object-as-properror-禁止使用 {...} 作为 JSX 属性值
jsx-no-new-array-as-properror-禁止使用 [...] 作为 JSX 属性值
jsx-no-new-function-as-properror-禁止使用函数作为 JSX 属性值

TanStack Query​

@tanstack/eslint-plugin-query 用于强制执行 TanStack Query 最佳实践，并帮助您避免常见错误。

// .eslintrc.js

module.exports = {
  extends: [
    // ...
    'plugin:@tanstack/query/recommended',
  ],
};
规则名称错误级别配置选项描述
@tanstack/query/exhaustive-depserror-确保 Query 的依赖数组（如 queryKey）完整且正确，避免过时闭包问题
@tanstack/query/no-rest-destructuringwarn-警告或避免在 Query 返回的结果中使用 Rest 解构，以防止非响应式更新
@tanstack/query/stable-query-clienterror-确保 QueryClient 实例是稳定的，避免不必要的重新创建。
@tanstack/query/no-unstable-depserror-禁止在 Query 的依赖数组中使用不稳定的值（如内联对象或函数）
@tanstack/query/infinite-query-property-ordererror-强制执行 Infinite Query 相关属性（如 pages, pageParams）的特定顺序
@tanstack/query/no-void-query-fnerror-禁止 queryFn 返回 void，它应该返回一个 Promise 或抛出错误
@tanstack/query/mutation-property-ordererror-规范 Mutation 操作中相关属性（如 mutationKey, mutationFn）的书写顺序