Ordo UI
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——

源码

packages/patterns/src/components/bulk-action-bar.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

批量操作条:已选计数 + 动作槽 + 清除;selectedCount<=0 不渲染,移动端可换行。