wp-calypso 组件实战:BulkSelect 全选复选框组件的源码解析与使用指南
wp-calypso 组件实战:BulkSelect 全选复选框组件的源码解析与使用指南
本文以 WordPress.com 前端应用 wp-calypso 中的 client/components/bulk-select 组件为主线,系统讲解其设计思路、API 用法、三态渲染逻辑与无障碍支持,并结合源码、测试用例及 Jetpack 站点总览仪表盘的真实集成案例,帮助你掌握在大型 React 应用中实现"全选 / 半选 / 取消全选"批量操作的标准姿势。读完本文,你将能够独立将该组件接入自己的列表页面,并理解其内部状态机与回调协议。
组件概述:一个复选框完成批量选择
在管理后台类界面中,"全选当前列表所有条目"是最高频的批量操作入口。wp-calypso 将其抽象为一个独立组件 BulkSelect:它渲染一个复选框,通过外部传入的"已选元素数量"与"可选元素总数",自动呈现出三种视觉与逻辑状态——全部选中(勾选)、部分选中(半选图标)、全部未选(空)。组件本身不持有列表数据,只负责"展示状态 + 上报切换意图",这种受控组件设计使其可以无缝接入任意数据源。
组件源码位于 client/components/bulk-select/index.jsx,配套样式在 client/components/bulk-select/style.scss,官方交互示例见 client/components/bulk-select/docs/example.jsx,组件级单元测试在 client/components/bulk-select/test/index.js。
快速上手:最小可用示例
根据 README.md,组件通过 calypso/components/bulk-select 路径导入,最简用法如下:
import BulkSelect from 'calypso/components/bulk-select';
function render() {
return <BulkSelect selectedElements={ 3 } totalElements={ 6 } onToggle={ callback } />;
}
当 selectedElements 为 3、totalElements 为 6 时,组件会呈现"部分选中"状态(显示半选图标);点击复选框后,onToggle 回调会收到一个布尔值,表示"全选"复选框应当切换到的目标状态,你应在该回调中把这个布尔值应用到列表的每一项上。
完整可运行示例
仓库在 client/components/bulk-select/docs/example.jsx 中提供了一个带交互状态的完整示例,展示了如何让组件与真实列表联动:
import { Card, FormLabel } from '@automattic/components';
import { Component } from 'react';
import BulkSelect from 'calypso/components/bulk-select';
import FormInputCheckbox from 'calypso/components/forms/form-checkbox';
export default class extends Component {
static displayName = 'BulkSelects';
state = {
elements: [
{ title: 'Apples', selected: true },
{ title: 'Oranges', selected: false },
],
};
handleToggleAll = ( checkedState ) => {
const newElements = [];
this.state.elements.forEach( ( element ) => {
if ( typeof checkedState !== 'undefined' ) {
element.selected = checkedState;
} else {
element.selected = ! element.selected;
}
newElements.push( element );
} );
this.setState( { elements: newElements } );
};
getSelectedElementsNumber = () => {
return this.state.elements.filter( function ( element ) {
return element.selected;
} ).length;
};
renderElements = () => {
return this.state.elements.map( ( element, index ) => {
const onClick = () => {
element.selected = ! element.selected;
this.forceUpdate();
};
return (
<FormLabel key={ index }>
<FormInputCheckbox onClick={ onClick } checked={ element.selected } readOnly />
<span>{ element.title }</span>
</FormLabel>
);
} );
};
render() {
return (
<Card>
<div>
<BulkSelect
totalElements={ this.state.elements.length }
selectedElements={ this.getSelectedElementsNumber() }
onToggle={ this.handleToggleAll }
/>
</div>
{ this.renderElements() }
</Card>
);
}
}
该示例的关键模式是:selectedElements 由 getSelectedElementsNumber() 实时计算得出,保证组件展示的勾选状态始终与列表实际选中数一致;onToggle 收到目标状态后遍历列表统一赋值。注意这里对 checkedState 做了 typeof 判断以兼容"未传参"场景(此时切换为逐项取反),这是文档示例代码中值得留意的健壮性写法。
Props 详解:受控组件的完整契约
README 中定义了三个核心 props,而源码 client/components/bulk-select/index.jsx 的 propTypes 声明则揭示了完整契约:
| Prop | 类型 | 必填 | 说明 |
|---|---|---|---|
selectedElements |
number | 是 | 当前已选中的元素数量,用于推导勾选状态与半选状态 |
totalElements |
number | 是 | 当前列表中全部可选元素的数量 |
onToggle |
function | 是 | 复选框状态切换时的回调,接收一个布尔值,表示应设置的全选目标状态 |
id |
string | 否 | 传递给复选框的 DOM id(propTypes 中声明,可配合 <label> 使用) |
ariaLabel |
string | 否 | 复选框的无障碍标签,默认值为 translate( 'Select All' )("全选") |
disabled |
boolean | 否 | 禁用复选框,默认 false |
isChecked |
boolean | 否 | 显式覆盖"全选"判定结果(优先级高于内部推导) |
isHalfChecked |
boolean | 否 | 显式覆盖"半选"判定结果(优先级高于内部推导) |
其中 isChecked 与 isHalfChecked 是文档 README 未提及但源码明确支持的两个高级 props,详见下文"三态渲染"一节。组件还通过 i18n-calypso 的 localize 高阶组件包裹(见源码末行 export default localize( BulkSelect )),因此 translate 也可作为注入 props 使用。
三态渲染:全选、半选与未选的状态机
BulkSelect 的渲染逻辑围绕两个判断函数展开(源码 client/components/bulk-select/index.jsx):
hasAllElementsSelected = () => {
return (
this.props.isChecked ??
( this.props.selectedElements && this.props.selectedElements === this.props.totalElements )
);
};
hasSomeElementsSelected = () => {
return (
this.props.isHalfChecked ??
( this.props.selectedElements && this.props.selectedElements < this.props.totalElements )
);
};
由此得到三种状态:
- 全部未选:
selectedElements为 0(或 falsy),复选框不勾选、不显示半选图标; - 部分选中(半选):
0 < selectedElements < totalElements,此时hasSomeElementsSelected()为真,组件会额外渲染一个minus-small的 Gridicon 叠加在复选框上(见getStateIcon方法),并给复选框添加bulk-select__some-checked-icon类名,样式上以主题色--color-primary呈现(见 client/components/bulk-select/style.scss); - 全部选中:
selectedElements === totalElements且大于 0,复选框打勾,并添加is-checked类。
点击复选框时,handleToggleAll 依据当前状态计算目标状态并上报:
handleToggleAll = () => {
const newCheckedState = ! ( this.hasSomeElementsSelected() || this.hasAllElementsSelected() );
this.props.onToggle( newCheckedState );
};
也就是说:当前处于"未选"状态时回调收到 true(要全选),当前处于"全选"或"半选"状态时回调收到 false(要全部取消)。测试 client/components/bulk-select/test/index.js 对这三种情况分别做了断言:未选时点击回调收到 true,半选与全选时点击回调均收到 false。
组件渲染结构为:span.bulk-select > FormLabel.bulk-select__container > FormInputCheckbox + Count + 半选图标。其中 Count(来自 @automattic/components)用于在复选框旁展示当前已选数量,样式 margin-left: 8px 且加粗(font-weight: 600),让用户随时掌握选中进度;底层复选框使用的是 client/components/forms/form-checkbox/index.tsx 中封装的 FormInputCheckbox(基于原生 <input type="checkbox"> 的轻量封装),样式上通过 appearance: none 隐藏了浏览器默认外观,以便自定义主题。
无障碍与可访问性设计
源码 client/components/bulk-select/index.jsx 在无障碍方面做了明确处理:
- 复选框带有
aria-label,默认值为translate( 'Select All' ),即默认向屏幕阅读器播报"全选";调用方可通过ariaLabelprop 覆盖; - 外层使用
<FormLabel>包裹复选框,点击文字/计数区域即可触发切换,扩大了可点击热区; disabledprop 直接透传给原生 input,加载中场景可禁用操作。
单元测试验证了这一点:should add the aria-label to the input 用例断言 aria-label 被正确写入 input 元素;should not mark the input readOnly 用例确认组件没有错误地设置 readOnly,保证复选框始终可交互。
真实集成案例:Jetpack 站点总览仪表盘
BulkSelect 并非孤立的示例组件,它被实际用于 wp-calypso 的 Jetpack 站点总览(Agency Dashboard)页面。集成代码位于 client/jetpack-cloud/sections/agency-dashboard/sites-overview/site-bulk-select/index.tsx,该页面在站点表格上方渲染全选复选框:
<BulkSelect
key="site-bulk-select"
totalElements={ sites.length }
selectedElements={ selectedSites.length }
onToggle={ handleToggleSelect }
isChecked={ isChecked }
isHalfChecked={ isHalfChecked }
disabled={ isLoading }
/>
这个生产级用法有几点值得借鉴:
- 显式传递
isChecked/isHalfChecked:由于"可全选"的对象需要先过滤掉连接异常、监控报错或 Atomic 站点(见handleToggleSelect中的filteredSites逻辑),父组件自行计算全选/半选状态并显式传入,覆盖组件的内部推导,保证展示与真实可选集合一致; disabled={ isLoading }:数据加载期间禁用复选框,避免用户在数据未就绪时误操作;key="site-bulk-select":当站点列表变化时强制重建复选框,确保状态归零;- 选择状态提升:选中站点集合
selectedSites通过SitesOverviewContext上下文管理,全选/取消全选通过setSelectedSites一次性写入,同时记录site_bulk_select_all/site_bulk_unselect_all埋点事件。
该组件被引用在 site-table/index.tsx 与 site-content/index.tsx 中,用于桌面端表格视图与内容视图的批量操作入口,配套 DashboardBulkActions 展示批量操作按钮,是理解"受控全选组件 + 上下文状态管理 + 批量操作面板"完整链路的最佳样板。
单元测试:组件行为的可验证契约
组件测试位于 client/components/bulk-select/test/index.js,使用 @testing-library/react 与 userEvent 编写,覆盖了如下行为契约:
- 渲染后根元素带有
bulk-select类名; - 未选中任何元素时不勾选、不加
is-checked类; - 全部选中时 input 处于
checked状态; - 部分选中时 input 不勾选,但渲染半选图标(
bulk-select__some-checked-icon类); aria-label正确写入 input;- 未设置
readOnly,保证可交互; - 点击复选框触发
onToggle,且分别验证"未选→true""半选→false""全选→false"三种回调参数。
这些测试既是组件的质量保障,也相当于一份"行为规格说明书":任何对该组件的修改都必须保持上述状态转换语义不变,否则相关用例将失败。
接入清单与注意事项
将 BulkSelect 接入你自己的列表页时,建议遵循以下步骤:
- 通过
import BulkSelect from 'calypso/components/bulk-select';引入组件; - 维护列表数据源(state / Redux / Context 均可),计算
selectedElements(已选数量)与totalElements(列表长度); - 实现
onToggle回调:收到true时全选列表所有可选元素,收到false时清空选中; - 若"全选目标"需要过滤部分不可选元素(如加载失败、无权限的条目),自行计算
isChecked/isHalfChecked并显式传入,覆盖内部推导; - 数据加载期间传入
disabled,必要时用key强制重建组件; - 用
ariaLabel提供业务语义化的无障碍标签。
需要特别说明的边界行为:当 selectedElements 为 0 时,hasAllElementsSelected 与 hasSomeElementsSelected 都会返回 falsy(因为内部逻辑要求 selectedElements 为真值才继续比较),此时呈现完全未选状态;当列表为空(totalElements 为 0)时,应确保外层逻辑不会把空列表渲染成全选态。此外,组件是严格受控的——它从不自行修改选中状态,所有状态变化都必须经由父组件通过 props 回流,这一设计保证了数据流的单向可预测性。
总结
BulkSelect 是 wp-calypso 中一个轻量但设计严谨的批量选择组件:三个核心 props 定义了清晰的受控契约,三态渲染状态机自动推导全选/半选/未选,isChecked / isHalfChecked 提供了面向复杂业务的显式覆盖能力,aria-label 与 FormLabel 兼顾了无障碍体验,而 Jetpack 站点总览仪表盘的集成则展示了它在真实生产场景中的完整用法。无论是组件使用者还是想在自有项目中复刻类似能力的开发者,都可以从本文的源码分析与测试契约中获得直接可用的参考。