PatternsApp Patterns
BulkActionBar
@mox-hub/patterns 模式 · App Patterns · canonical
bulk-action-bar@mox-hub/patternsApp Patternscanonicalsrc/components/bulk-action-bar.tsx变体演示bulk-action-bar
已选 3 项
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| selectedCount* | number | — | — |
| onClear* | () => void | — | — |
| actions* | ReactNode | — | — |
| labels* | Partial<BulkActionBarLabels> | — | — |
| className* | string | — | — |
源码
import type { ReactNode } from 'react';
import { X } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import { Separator } from '@mox-hub/ui/components/separator';
import { usePatternLabels } from '../lib/i18n';
/**
* BulkActionBar —— 表格多选批量操作条(数据展示平面,W4 P1 / B11)。
*
* 选中集合非空时出现在表格上方或底部,展示「已选 N 项」、消费方注入的批量动作
* 与清除选择入口;选中数为 0(或负数)时整体不渲染。
*
* 边界:
* - 纯展示 / 受控件——选中集合与动作语义都由消费方持有,本件不取数、不发请求;
* - `actions` 是 ReactNode 插槽,动作按钮的 variant / 危险色由消费方决定;
* - 布局走 `flex-wrap`,窄屏时「已选 N 项 / 动作 / 清除」按行折行,不横向溢出;
* - a11y:根节点 `role="region"` + `aria-label`,清除按钮带独立 `aria-label`。
*/
export interface BulkActionBarLabels {
/** 区域无障碍名 */
region: string;
/** 选中计数文案(默认「已选 N 项」) */
selected: (count: number) => string;
/** 清除选择按钮文案 / 无障碍名 */
clear: string;
}
export const BULK_ACTION_BAR_DEFAULT_LABELS: BulkActionBarLabels = {
region: '批量操作',
selected: (count) => `已选 ${count} 项`,
clear: '清除',
};
export interface BulkActionBarProps {
/** 当前选中条数;<= 0 时返回 null */
selectedCount: number;
/** 清除选择 */
onClear: () => void;
/** 批量动作按钮(由消费方注入) */
actions: ReactNode;
labels?: Partial<BulkActionBarLabels>;
className?: string;
}
export function BulkActionBar({
selectedCount,
onClear,
actions,
labels,
className,
}: BulkActionBarProps) {
const D = usePatternLabels('bulkActionBar', BULK_ACTION_BAR_DEFAULT_LABELS);
const text: BulkActionBarLabels = {
region: labels?.region ?? D.region,
selected: labels?.selected ?? D.selected,
clear: labels?.clear ?? D.clear,
};
if (selectedCount <= 0) return null;
return (
<div
role="region"
aria-label={text.region}
data-slot="bulk-action-bar"
className={cn(
'flex flex-wrap items-center gap-x-3 gap-y-2 rounded-lg border border-border bg-card px-3 py-2',
className,
)}
>
<span
aria-live="polite"
className="shrink-0 text-xs font-medium text-foreground"
>
{text.selected(selectedCount)}
</span>
<Separator
orientation="vertical"
className="hidden h-4 self-center sm:block"
/>
<div className="flex min-w-0 flex-1 flex-wrap items-center gap-1.5">
{actions}
</div>
<Button
type="button"
variant="ghost"
size="xs"
aria-label={text.clear}
title={text.clear}
onClick={onClear}
className="shrink-0"
>
<X aria-hidden />
{text.clear}
</Button>
</div>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
批量操作条:已选计数 + 动作槽 + 清除;selectedCount<=0 不渲染,移动端可换行。