#批量操作栏

批量操作栏只在集合存在选择时出现，把选择范围、可操作数量、批量命令和退出选择模式的方式放在同一个稳定区域。

npm install @a3s-lab/ui@0.4.1

<section
class="bulk-action-bar"
data-state="selected"
data-bulk-focus-return="#bulk-action-bar-collection-zh"
role="region"
aria-label="已选环境操作"
>
<div data-bulk-selection>
  已选 <output data-selected-count>3</output> 项
</div>
<span data-bulk-summary aria-live="polite">
  其中 2 项可以归档
</span>
<div data-bulk-actions>
  <button type="button" class="btn" data-variant="outline" data-bulk-action="move">
    移动
  </button>
  <button type="button" class="btn" data-variant="outline" data-bulk-action="archive">
    归档 2 项
  </button>
  <button type="button" class="btn" data-variant="destructive" data-bulk-action="delete">
    删除
  </button>
  <button type="button" class="btn" data-variant="ghost" data-bulk-action="clear" data-bulk-clear>
    清除选择
  </button>
</div>
</section>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#用法

把操作栏放在拥有选择状态的集合旁边。根元素要使用具体集合的可访问名称，始终显示准确的选中数量；选择部分可操作时，命令标签必须写出实际可处理数量。宿主负责权限、确认、请求、乐观更新、回滚和重试。

可以加载完整运行时，也可以只加载拆分入口：

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/bulk-action-bar.min.js" defer></script>

上面的集成预览是 HTML、React 和 Vue 的唯一示例来源。打开预览工具栏中的源码面板，可以在同一个工作区切换安装命令、入口文件和示例文件，并复制当前代码。

#契约

setPending(action, true, { message, allowClear }) 会禁用进行中的命令和所有冲突命令，同时保留原有的禁用状态。allowClear 默认是 true；如果退出选择模式会和宿主请求冲突，可以传入 false。进行中点击清除不会取消请求，操作栏会保留到宿主完成处理。

#状态与恢复

实时预览工具栏中的状态验收矩阵会验证 empty 隐藏完整区域、selected 保留范围、loading 禁用冲突命令，以及 disabled 对每个命令使用原生禁用语义。

<section class="bulk-action-bar" data-state="selected" data-result="error" role="region" aria-label="已选运行操作">
    <div data-bulk-selection>
      已选 <output data-selected-count>2</output> 项
    </div>
    <span data-bulk-summary role="status">
      归档失败：缺少生产环境权限。获得权限后重试，或清除选择。
    </span>
    <div data-bulk-actions>
      <button type="button" class="btn" data-size="sm" data-variant="outline" data-bulk-action="archive">
        重试归档 2 项
      </button>
      <button type="button" class="btn" data-size="sm" data-variant="ghost" data-bulk-action="clear" data-bulk-clear>
        清除选择
      </button>
    </div>
  </section>

选择了 5 项但只有 3 项可重试时，命令应写成“重试 3 项”，不能写“重试 5 项”然后由服务端静默跳过 2 项。不可逆命令仍需通过警报对话框确认，并明确影响数量。

#可访问性与归属

根区域必须说明它影响的集合，而且出现时不能自动抢走焦点。选择数量、可操作数量、进度和结果都要使用文字表达。进行中的命令保留原标签，根区域暴露 aria-busy="true"；只有 allowClear 允许时才保留清除入口。请求被拒绝后保留选择和焦点上下文，让恢复命令仍然可达。清除成功或完成后操作栏隐藏，应把焦点还给稳定的集合目标，而不是留在已经隐藏的按钮上。

React 和 Vue 使用同一套控制器事件和方法，适配器不会创建第二份框架私有选择状态，也不会在组件内执行网络请求。