深入理解 jsx-eslint/eslint-plugin-react 中的 forbid-component-props 规则

什么是 forbid-component-props 规则？

forbid-component-props 是 jsx-eslint/eslint-plugin-react 插件中的一个 ESLint 规则，它用于禁止在 React 组件上使用特定的 props。这个规则的核心目的是帮助开发者避免使用那些可能导致代码复杂化或违反最佳实践的 props。

为什么需要这个规则？

在 React 开发中，某些 props 的使用可能会导致代码维护性下降。例如：

1. className 和 style props：直接传递这些样式相关的 props 可能导致组件与样式紧密耦合，违反了关注点分离原则
2. 特定业务 props：某些业务相关的 props 可能只应在特定组件中使用

通过禁止这些 props 的使用，可以强制开发者采用更合理的组件设计模式，如使用组合模式或高阶组件。

基本用法

默认情况下，该规则会禁止在组件上使用 className 和 style 这两个 props，但允许在 DOM 元素上使用它们。

错误示例

<MyComponent className="foo" />
<MyComponent style={{color: 'red'}} />

正确示例

<MyComponent customProp="value" />
<div className="foo" />
<div style={{color: 'red'}} />

配置选项

基本配置

在 ESLint 配置文件中，可以这样启用该规则：

{
  "rules": {
    "react/forbid-component-props": ["error", {
      "forbid": ["className", "style"]
    }]
  }
}

高级配置

1. 自定义禁止的 props

可以指定任意需要禁止的 props：

{
  "forbid": ["className", "style", "data-test-id"]
}

2. 为特定组件设置例外

{
  "forbid": [
    {
      "propName": "className",
      "allowedFor": ["SpecialComponent", "AnotherComponent"]
    }
  ]
}

3. 禁止特定组件使用某些 props

{
  "forbid": [
    {
      "propName": "dangerousProp",
      "disallowedFor": ["SensitiveComponent"],
      "message": "Avoid using dangerousProp in SensitiveComponent"
    }
  ]
}

4. 使用通配符模式匹配

{
  "forbid": [
    {
      "propNamePattern": "**-*",
      "message": "Avoid using kebab-case props"
    }
  ]
}

5. 组合多种条件

{
  "forbid": [
    {
      "propName": "specialProp",
      "allowedFor": ["BaseComponent"],
      "allowedForPatterns": ["*Special*"],
      "message": "specialProp should only be used in BaseComponent or components with 'Special' in their name"
    }
  ]
}

实际应用场景

场景一：禁止内联样式

{
  "react/forbid-component-props": ["error", {
    "forbid": ["style"]
  }]
}

这可以强制开发者使用 CSS 模块或 styled-components 等更可维护的样式方案。

场景二：限制业务特定 props

{
  "react/forbid-component-props": ["error", {
    "forbid": [
      {
        "propName": "userData",
        "allowedFor": ["UserProfile"],
        "message": "userData prop should only be used in UserProfile component"
      }
    ]
  }]
}

这样可以确保业务逻辑不会在组件间随意传播。

场景三：禁止特定命名模式的 props

{
  "react/forbid-component-props": ["error", {
    "forbid": [
      {
        "propNamePattern": "on*",
        "disallowedFor": ["PureComponent"],
        "message": "Event handlers should not be used in PureComponent"
      }
    ]
  }]
}

最佳实践建议

1. 渐进式采用：可以先从禁止最可能出问题的 props 开始，如 className 和 style
2. 结合团队规范：根据团队约定的组件设计规范来配置禁止的 props
3. 提供替代方案：在禁止某些 props 时，确保团队了解推荐的替代方案
4. 自定义错误信息：为每个禁止的 prop 提供清晰的错误信息，说明为什么禁止以及替代方案

与其他规则的关系

forbid-component-props 规则与 forbid-dom-props 规则是互补的：

• forbid-component-props：针对自定义组件
• forbid-dom-props：针对原生 DOM 元素

合理搭配使用这两个规则可以全面控制项目中 props 的使用规范。

总结

forbid-component-props 是一个强大的工具，可以帮助团队维护一致的 React 组件设计规范。通过合理配置，它可以：

• 防止样式相关的 props 导致组件与样式耦合
• 限制业务特定 props 的传播范围
• 强制使用更合理的组件设计模式
• 提高代码的可维护性和一致性

正确使用这个规则需要结合项目的具体需求和团队的开发规范，但它无疑是提升 React 代码质量的有力工具。