wp-calypso 组件实战:BulkSelect 全选复选框组件的源码解析与使用指南

原创2026-09-22 17:54:331,925 阅读
文章标签:前端CMS

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' ),即默认向屏幕阅读器播报"全选";调用方可通过 ariaLabel prop 覆盖;
  • 外层使用 <FormLabel> 包裹复选框,点击文字/计数区域即可触发切换,扩大了可点击热区;
  • disabled prop 直接透传给原生 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 }
/>

这个生产级用法有几点值得借鉴:

  1. 显式传递 isChecked / isHalfChecked:由于"可全选"的对象需要先过滤掉连接异常、监控报错或 Atomic 站点(见 handleToggleSelect 中的 filteredSites 逻辑),父组件自行计算全选/半选状态并显式传入,覆盖组件的内部推导,保证展示与真实可选集合一致;
  2. disabled={ isLoading }:数据加载期间禁用复选框,避免用户在数据未就绪时误操作;
  3. key="site-bulk-select":当站点列表变化时强制重建复选框,确保状态归零;
  4. 选择状态提升:选中站点集合 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 接入你自己的列表页时,建议遵循以下步骤:

  1. 通过 import BulkSelect from 'calypso/components/bulk-select'; 引入组件;
  2. 维护列表数据源(state / Redux / Context 均可),计算 selectedElements(已选数量)与 totalElements(列表长度);
  3. 实现 onToggle 回调:收到 true 时全选列表所有可选元素,收到 false 时清空选中;
  4. 若"全选目标"需要过滤部分不可选元素(如加载失败、无权限的条目),自行计算 isChecked / isHalfChecked 并显式传入,覆盖内部推导;
  5. 数据加载期间传入 disabled,必要时用 key 强制重建组件;
  6. 用 ariaLabel 提供业务语义化的无障碍标签。

需要特别说明的边界行为:当 selectedElements 为 0 时,hasAllElementsSelected 与 hasSomeElementsSelected 都会返回 falsy(因为内部逻辑要求 selectedElements 为真值才继续比较),此时呈现完全未选状态;当列表为空(totalElements 为 0)时,应确保外层逻辑不会把空列表渲染成全选态。此外,组件是严格受控的——它从不自行修改选中状态,所有状态变化都必须经由父组件通过 props 回流,这一设计保证了数据流的单向可预测性。

总结

BulkSelect 是 wp-calypso 中一个轻量但设计严谨的批量选择组件:三个核心 props 定义了清晰的受控契约,三态渲染状态机自动推导全选/半选/未选,isChecked / isHalfChecked 提供了面向复杂业务的显式覆盖能力,aria-label 与 FormLabel 兼顾了无障碍体验,而 Jetpack 站点总览仪表盘的集成则展示了它在真实生产场景中的完整用法。无论是组件使用者还是想在自有项目中复刻类似能力的开发者,都可以从本文的源码分析与测试契约中获得直接可用的参考。

登录后查看全文
wp-calypso