eslint-plugin-react 的 boolean-prop-naming 规则:统一布尔 Props 命名规范实战指南
eslint-plugin-react 的 boolean-prop-naming 规则:统一布尔 Props 命名规范实战指南
react/boolean-prop-naming 是 eslint-plugin-react 提供的一条样式类(Stylistic Issues)规则,用于强制组件中期望接收布尔值(boolean)的 props 采用一致的命名模式。无论你用 PropTypes、TypeScript 还是 Flow 来定义组件 props,本规则都能基于类型信息自动识别出"布尔型 props",并校验它们的命名是否满足你约定的正则模式(默认要求以 is 或 has 开头)。阅读完本文,你将掌握该规则的完整配置参数(propTypeNames、rule、message、validateNested)、正确的开启方式,并能理解它在 规则源码 层面的检测原理与边界行为。
规则概览:做什么、不做什么
该规则的核心逻辑很简单:遍历组件声明的所有 props,找出其中类型为"布尔"的 prop,然后用你给定的正则表达式测试它的名字,不匹配即报告错误。
需要特别强调的是,本规则的"布尔类型识别"是跨类型系统的:
- 运行时 PropTypes:如
PropTypes.bool、React.PropTypes.bool,以及直接引入的bool标识符; - TypeScript 静态类型:如
enabled: boolean、type Props = {...}、interface、交叉类型与联合类型; - Flow 静态类型:如
enabled: boolean、ObjectTypeAnnotation。
如 规则文档 的 Note 所说明,规则会"无论你如何定义 props 都进行校验",因此你不需要额外切换配置,同一份规则即可同时覆盖三种写法混用的项目。
不符合规则的代码(Incorrect)
使用 createReactClass + PropTypes 定义布尔 prop 却未遵循命名模式:
var Hello = createReactClass({
propTypes: {
enabled: PropTypes.bool
},
render: function() { return <div />; };
});
使用 Flow 类型定义布尔 prop:
type Props = {
enabled: boolean
}
const Hello = (props: Props) => <div />;
符合规则的代码(Correct)
var Hello = createReactClass({
propTypes: {
isEnabled: PropTypes.bool
},
render: function() { return <div />; };
});
type Props = {
isEnabled: boolean
}
const Hello = (props: Props) => <div />
注意:在默认规则 ^(is|has)A-Z+ 下,enabled 因为缺少 is 前缀而被标记;而 isEnabled 完全匹配。非布尔类型的 props(如 PropTypes.string、PropTypes.any)不受此规则约束,测试用例中大量使用 something: PropTypes.any 作为合法示例即可佐证这一点(见 测试文件 中 // ES6 components with non-boolean PropTypes 等用例)。
如何开启该规则
该规则默认不启用——在 规则源码 的 meta.docs 中 recommended: false,因此它不会出现在 react/recommended 预设里,需要手动在 ESLint 配置中开启:
// .eslintrc 传统配置
{
"plugins": ["react"],
"rules": {
"react/boolean-prop-naming": ["error", {
"propTypeNames": ["bool"],
"rule": "^(is|has)A-Z+",
"message": "",
"validateNested": false
}]
}
}
所有规则统一在 规则注册表 中注册,插件通过 lib/rules/boolean-prop-naming.js 导出。开启后,任何不匹配的布尔 prop 都会触发如下默认错误消息:
Prop name `enabled` doesn't match rule `^(is|has)A-Z+`
这条默认消息定义在 源码 messages 表 中(patternMismatch 消息 ID),消息文本使用 ESLint 的 {{ 占位符 }} 模板插值机制渲染。
规则选项详解
完整选项结构如下(来自 文档 与 JSON Schema 定义):
...
"react/boolean-prop-naming": [<enabled>, {
"propTypeNames": Array<string>,
"rule": <string>,
"message": <string>,
"validateNested": <boolean>
}]
...
从 Schema 可以确认以下约束与默认值:
| 选项 | 类型 | 默认值 | Schema 约束 |
|---|---|---|---|
propTypeNames |
Array<string> |
['bool'] |
至少 1 项(minItems: 1),且不能重复(uniqueItems: true) |
rule |
string |
`'^(is | has)A-Z+'` |
message |
string |
默认错误消息 | 至少 1 个字符(minLength: 1) |
validateNested |
boolean |
false |
— |
其余未列出的属性一律被 additionalProperties: false 拒绝,配置时需注意不要拼错键名。
propTypeNames:声明哪些类型算"布尔"
默认情况下,规则只把 PropTypes 中的 bool 视为布尔类型。但实际项目中常有自定义的布尔语义类型,例如 airbnb-prop-types 的 mutuallyExclusiveTrueProps(一组互斥的布尔 props)。你可以扩展名单:
"react/boolean-prop-naming": ["error", { "propTypeNames": ["bool", "mutuallyExclusiveTrueProps"] }]
源码层面,配置读取逻辑为 const propTypeNames = config.propTypeNames || <a href="https://link.gitcode.com/i/a5d72cdf1d40c087c3b72e665b694d44" target="_blank">'bool'];(见 [lib/rules/boolean-prop-naming.js),随后在 regularCheck 中通过 propTypeNames.indexOf(propKey) >= 0 判断某个 prop 的类型名是否在名单内。
值得注意的实现细节:这里匹配的是类型标识符名,因此 PropTypes 的多种写法都能命中:
PropTypes.bool(成员表达式,取.property.name)React.PropTypes.bool- 直接引入的
bool(如import { bool } from 'prop-types',属Identifier节点) PropTypes.bool.isRequired(会跳过isRequired再取bool)
以上各种写法分别由 getPropKey 的不同分支处理(源码 L102-L123),测试用例 // Custom PropTypes that are specified as variables 也验证了直接写 mutuallyExclusiveTrueProps、bool 标识符的场景。
rule:布尔 props 的命名正则
默认模式为 "^(is|has)A-Z+",即要求布尔 prop 以 is 或 has 开头,且紧跟一个大写字母。文档给出的合法示例:
- isEnabled
- isAFK
- hasCondition
- hasLOL
其中 isAFK、hasLOL 这类全大写缩写也能通过,因为模式允许大写字母与数字任意组合([A-Za-z0-9])。
显式声明默认规则:
"react/boolean-prop-naming": "error", { "rule": "^(is|has)[A-Z+" }]
如果只想强制 is 前缀(例如团队约定只用 is 不用 has):
"react/boolean-prop-naming": "error", { "rule": "^is[A-Z+" }]
此时仅以下形式合法:
- isEnabled
- isAFK
源码中 const rule = config.rule ? new RegExp(config.rule) : null;(L85),将配置字符串编译为正则后,在三种检查函数(flowCheck / regularCheck / tsCheck)里统一用 rule.test(propName) === false 判定"不匹配"。另外注意:未配置 rule 时,rule 为 null,规则会直接跳过所有检查(多处 if (!rule) return; 守卫),因此该规则几乎总是需要显式提供 rule 才有意义。
你也可以在正则中加入例外名单,比如测试用例中出现的 (^(is|has|should|without)A-Z+|disabled|required|checked|defaultChecked)——这种写法把 HTML 原生布尔属性名直接列为可接受项。
message:自定义报错文案
默认消息不够友好时,可以自定义提示。自定义消息支持两个模板变量:
propName– 未通过模式校验的 prop 名pattern– 实际用于校验的正则模式
例如 prop 名为 something、模式为 "^(is|has)A-Z+" 时:
message: 'It is better if your prop ({{ propName }}) matches this pattern: ({{ pattern }})'
实际报错渲染为:
It is better if your prop (something) matches this pattern: (^isA-Z+)
注意:报错中渲染的
{{ pattern }}始终是你实际配置的 rule 字符串。上述示例中的^is[A-Z]...是文档为演示模板变量而展示的取值,实际项目中它会原样输出你在rule中填写的正则。
源码中消息渲染走 report 工具 + message 工具:当未提供自定义 message 时使用 messages.patternMismatch 的消息 ID(便于在 ESLint ≥ 4.15 下使用 messageId 机制做多语言/程序化处理);提供了自定义消息时,则以 config.message 优先,模板变量 propName、pattern、component 通过 data 注入(L219-L231)。
validateNested:是否校验嵌套布尔 props
布尔 props 可能藏在对象型 props 的内部,例如 PropTypes.shape({...})。默认 validateNested: false,此时只校验顶层布尔 props,shape 内部的布尔 props 不会被检查。开启后则递归下钻校验深层:
"react/boolean-prop-naming": ["error", { "validateNested": true }]
开启后,如下代码中的 failingItIs(shape 内部、未遵循 is 前缀)也会被报告:
class Hello extends React.Component {
render() {
return (
<div />
);
}
}
Hello.propTypes = {
isSomething: PropTypes.bool.isRequired,
nested: PropTypes.shape({
failingItIs: PropTypes.bool
})
};
源码中通过 nestedPropTypes 判断"当前 prop 的值是函数调用(如 PropTypes.shape({...}))",满足条件且 config.validateNested 为真时,对 prop.value.arguments<a href="https://link.gitcode.com/i/d5e481a9709603d6c958c613f831942f" target="_blank">0].properties 递归执行 runCheck([L27-L32 与 L183-L195)。递归是深度优先的,因此多层 shape 嵌套也能逐层穿透(测试用例中就有两层 nested: PropTypes.shape({ nested: PropTypes.shape({...}) }) 的验证)。
源码级原理:规则是如何检测的
理解规则的工作流有助于排查"为什么没报错"类问题。整体流程可分为三个阶段:
阶段一:定位 propTypes 声明
规则注册了多个 AST 访问器来捕获不同写法的 propTypes 声明:
ClassProperty / PropertyDefinition:处理static propTypes = {...}、Flow 的props: {...}类属性(L311-L331);MemberExpression:处理Hello.propTypes = {...}的赋值语句(L333-L353);ObjectExpression:处理createReactClass({ propTypes: {...} })这类对象字面量写法(L355-L367)。
其中"这是不是 propTypes 声明"的判断由 props 工具 的 isPropTypesDeclaration 完成:Flow 下识别键名为 props 的类属性,其余情况识别属性名是否为 propTypes。
阶段二:识别布尔类型并匹配正则
对收集到的每个 prop 属性节点,依次执行三种类型检查,任一命中即视为"布尔 prop":
| 检查函数 | 适用场景 | 判定条件 |
|---|---|---|
flowCheck |
Flow | 节点类型为 ObjectTypeProperty,且值为 BooleanTypeAnnotation |
regularCheck |
PropTypes | 提取到的类型标识符在 propTypeNames 名单内 |
tsCheck |
TypeScript | 节点类型为 TSPropertySignature,且类型注解为 TSBooleanKeyword |
三者任一满足且 rule.test(propName) === false(即命名不匹配)时,该 prop 进入 invalidProps 列表(L146-L176)。非布尔类型(如 PropTypes.any、string、number 等)在此阶段被自然过滤,这也是规则不会误伤普通 props 的原因。
阶段三:汇总并报告
规则在 Program:exit(程序退出时)统一遍历所有已收集组件,执行 reportInvalidNaming 一次性输出所有违规(L382-L423)。这种"先收集、后报告"的设计允许规则先完整解析 TypeScript 类型别名再校验,从而支持更复杂的类型语法。
额外能力一:propWrapperFunctions 支持
如果项目用 merge、Object.assign、_.assign、forbidExtraProps 等包装函数生成 propTypes,只要在 ESLint 的 settings.propWrapperFunctions 中声明这些函数,规则就能"穿透"包装、校验内部的布尔 props:
{
"settings": {
"propWrapperFunctions": ["merge", "forbidExtraProps"]
}
}
源码通过 propWrapper 工具 的 isPropWrapperFunction 判断调用是否为声明的包装函数,命中后对包装参数中的 ObjectExpression 继续执行 validatePropNaming(L233-L238)。对应的测试用例覆盖了 merge、Object.assign、_.assign、forbidExtraProps 四种包装形式,且支持 'Object.assign'、'_.assign' 这类带命名空间的字符串。
额外能力二:TypeScript 高级类型语法
从 测试文件 的用例可以看出,规则对现代 TypeScript 类型语法支持相当完整:
- 类型别名引用:
type Props = {...}+const Hello = (props: Props) => ...; - React.FC 泛型:
const Hello: React.FC<Props> = (props) => ...; - interface:
interface TestFNType { enabled: boolean }; - 交叉类型:
type Props = {...} & OtherProps,包括命名类型与内联字面量混合交叉; - 联合类型:
type Props = {...} | {...},以及交叉中嵌联合A & (B | C); - 内联对象类型:
const Hello = (props: { enabled: boolean }) => <div />。
实现上,规则用 objectTypeAnnotations 缓存所有 TypeAlias / TSTypeAliasDeclaration / TSInterfaceDeclaration 的类型体(findAllTypeAnnotations),并在 Program:exit 阶段通过 getComponentTypeAnnotation 定位组件 props 的类型注解,再解析交叉/联合结构递归找出所有属性,最终逐个校验(L240-L304)。
常见边界情况与避坑提示
-
isRequired不会导致漏检:PropTypes.bool.isRequired与普通PropTypes.bool一样参与校验。getPropKey专门处理了isRequired成员表达式,先取出.object.property的类型名(即bool)再比对名单(L109-L117)。 -
对象展开不会被误检:
static propTypes = {isSomething: PropTypes.bool, ...spreadProps}中展开进来的属性会被跳过。getPropKey对ExperimentalSpreadProperty/SpreadElement节点返回null,从而不会因取不到.property而报错或崩溃(L103-L107)。 -
shape({}).isRequired不会误报:当值为PropTypes.shape({...}).isRequired时,getPropKey取到的是shape而非bool,不在propTypeNames名单内,因此不会误判(测试用例// Ensure the rule does not throw when a shape prop isRequired)。 -
忘记配置
rule时规则静默失效:如前述,rule缺省为null,所有访问器都会提前return。如果你发现规则"完全没反应",优先检查是否遗漏了rule配置。 -
validateNested只对函数调用形式的嵌套生效:嵌套检测依赖nestedPropTypes(prop 值为函数调用,如PropTypes.shape({...})),普通对象字面量嵌套不在其检测路径中。 -
默认不进入 recommended 预设:需要在配置中显式开启(
"error"或"warn"),它不会随plugin:react/recommended自动启用。
测试与验证
该规则拥有非常完整的测试套件(tests/lib/rules/boolean-prop-naming.js,共 1387 行),覆盖 createReactClass、React.createClass、ES6 类(静态/实例 propTypes)、函数组件、Flow、TypeScript(含 Babel/旧 TS 解析器变体)等场景。测试通过 messageId: 'patternMismatch' 与 data: { propName, pattern } 断言错误内容,其中自定义消息用例验证了模板变量插值的实际输出:
It is better if your prop (something) matches this pattern: (^isA-Z+)
若你修改了该规则或自定义了配置,可运行对应测试确认行为符合预期(测试运行器基于 tests/helpers/ruleTester.js)。
小结
react/boolean-prop-naming 是一条"小而精"的命名一致性规则:通过 rule 正则统一布尔 props 的命名模式,借助 propTypeNames 扩展自定义布尔类型,message 定制报错文案,validateNested 下钻校验 shape 嵌套。在源码层面,它以 AST 类型识别(BooleanTypeAnnotation / TSBooleanKeyword / PropTypes 类型名单)而非运行时值来判断"布尔 props",因此能同时服务 PropTypes、TypeScript、Flow 三类用户;配合 propWrapperFunctions 设置,即使 propTypes 经过包装函数处理也能正常校验。建议在团队项目中结合 is / has 前缀约定开启此规则,让布尔 props 从命名上一眼可辨。