TableToolbar

为 DataTable 提供搜索、排序、筛选和批量操作入口，并展示选择状态，适合数据管理界面。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

仅用于 DataTable 的搜索、排序、筛选与批量操作，不独立搭配普通 Table。使用默认内置项或公开 as 角色替换；复制、删除实际业务由回调处理。

需要 DataTable 状态；search / sort / filter 控制默认工具，sortOptions 明确排序项。
直接 as="search" / "bulk" / "sort" / "filter" 替换对应区域；onCopy / onDelete 由业务实现。

导入

import { TableToolbar } from '@snowui-design-system/components';

用法

隐藏字段排序

搜索控件

启用批量操作

排序

筛选

显示清除操作

显示复制操作

显示删除操作

API 参考

属性	类型	默认值	示例	描述
`ariaLabel`	`string`	`—`	`ariaLabel="Example"`	工具栏 role=toolbar 的可访问名称，未传时按当前语言显示；多工具栏场景使用不同名称。
`search`	`boolean`	`true`	`search`	显示默认 SearchInput，并将输入写入 DataTable query；显式 as=search 可替换。
`bulkActionsEnabled`	`boolean`	`true`	`bulkActionsEnabled`	存在已选行时显示默认选择计数与批量操作区域；关闭不清除选择状态。
`sort`	`boolean`	`true`	`sort`	显示默认排序选择入口；排序字段来自 sortOptions 或可排序表头。
`sortOptions`	`TableToolbarSortOption[]`	`—`	`sortOptions={sortOptions}`	自定义内置排序菜单字段和顺序，可包含未展示为表格列的数据字段；显式列表替换自动表头列表，空数组仅保留默认排序。默认行为：未指定。
`filter`	`boolean`	`true`	`filter`	显示默认筛选入口；实际筛选需要 filterKey 和 filterOptions。
`searchPlaceholder`	`string`	`—`	`searchPlaceholder="Search…"`	默认搜索输入的占位文本，未传时按当前语言显示。
`searchAriaLabel`	`string`	`—`	`searchAriaLabel="Example"`	默认搜索输入的可访问名称，未传时按当前语言显示。
`sortLabel`	`string`	`—`	`sortLabel="Example"`	排序入口的可访问名称及提示文字，未传时按当前语言显示。
`filterLabel`	`string`	`—`	`filterLabel="Example"`	筛选入口的可访问名称及提示文字，未传时按当前语言显示。
`filterKey`	`string`	`—`	`filterKey="Example"`	写入 DataTable filters 的字段名；未配置时选择筛选项不会修改数据过滤条件。
`filterOptions`	`TableToolbarFilterOption[]`	`[]`	`filterOptions={filterOptions}`	筛选选项，每项包含 label 和 value；值为 string、number 或 undefined，通过字符串形式匹配所选项，再写回原始值。
`selectedCount`	`number`	`—`	`selectedCount={42}`	显式选择数量；未传时读取 DataTable 当前选中 id 数量，只覆盖展示与回调参数，不改选中集合。
`showClearAction`	`boolean`	`true`	`showClearAction`	在批量操作区显示清除选择按钮。
`showCopyAction`	`boolean`	`true`	`showCopyAction`	在批量操作区显示内置 CopyButton；具体复制由 onCopy 执行。
`showDeleteAction`	`boolean`	`true`	`showDeleteAction`	在批量操作区显示删除按钮；具体删除由 onDelete 执行。
`clearLabel`	`string`	`—`	`clearLabel="Example"`	清除选择按钮的文字，未传时按当前语言显示。
`copyLabel`	`string`	`—`	`copyLabel="Example"`	复制操作的可访问名称及提示文字，未传时按当前语言显示。
`deleteLabel`	`string`	`—`	`deleteLabel="Example"`	删除操作的可访问名称及提示文字，未传时按当前语言显示。
`selectionLabel`	`(count: number) => string`	`—`	`selectionLabel={(value) => { /* handle value */ }}`	接收已选数量并返回选择计数文案；未传时按当前语言显示，仅用于展示。
`onClearSelection`	`(count: number) => void`	`—`	`onClearSelection={(value) => { /* handle value */ }}`	清除按钮点击时接收当前选择数量；提供回调后替换默认 clearSelection，调用方需自行清除。
`onCopy`	`(count: number) => void \| Promise<void>`	`—`	`onCopy={(value) => { /* handle value */ }}`	复制操作接收选择数量，可返回 Promise；由回调执行实际复制，成功后 resolve，失败 reject，执行期间防止重复批量操作。
`onDelete`	`(count: number) => void \| Promise<void>`	`—`	`onDelete={(value) => { /* handle value */ }}`	删除操作接收选择数量，可返回 Promise；由回调执行实际删除，等待时显示加载反馈并阻止重复批量操作。
`bulkActions`	`Snippet<[number]>`	`—`	`bulkActions={bulkActionsContent}`	自定义附加批量操作，接收选择数量；只在有选择且批量操作区启用时显示，执行默认操作时暂不可交互。
`children`	`Snippet`	`—`	`<TableToolbar>Content</TableToolbar>`	显式工具栏内容，无参数；直接 as=search/bulk/sort/filter 可替换对应默认区，其余作为操作内容。
`parts`	`ComponentPartsOf<{ Button: typeof Button; Separator: typeof Separator; Spinner: typeof Spinner; SearchInput: typeof SearchInput; Select: typeof Select; Listbox: typeof Listbox; MenuItem: typeof MenuItem; }>`	`—`	`parts={partsOptions}`	配置工具栏直接拥有的默认 Button、Separator、Spinner、SearchInput、Select、Listbox、MenuItem；不递归接管显式子组件。