#数据网格

数据网格用于需要排序、选择、批量操作和远程分页的资源集合。它建立在表格、复选框、筛选栏和分页组件上，不接管查询、权限或数据获取。

npm install @a3s-lab/ui@0.4.0

<section class="data-grid" data-responsive="stack" aria-labelledby="grid-title">
  <header>
    <div data-grid-identity><h2 id="grid-title">运行环境</h2></div>
  </header>
  <div data-grid-viewport tabindex="0">
    <table class="table">
      <thead>
        <tr>
          <th>
            <input type="checkbox" data-grid-select-all aria-label="选择全部" />
          </th>
          <th aria-sort="none">
            <button type="button" data-grid-sort="name">名称</button>
          </th>
        </tr>
      </thead>
      <tbody>
        <tr data-value="production">
          <td data-grid-select-cell>
            <input
              type="checkbox"
              data-grid-select
              value="production"
              aria-label="选择生产环境"
            />
          </td>
          <td data-label="名称">生产环境</td>
        </tr>
      </tbody>
    </table>
  </div>
</section>

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

#用法

先加载运行时和数据网格控制器，或直接使用完整 JavaScript 包。

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/data-grid.min.js" defer></script>

<section class="data-grid" data-responsive="stack" aria-labelledby="grid-title">
  <header>
    <div data-grid-identity><h2 id="grid-title">运行环境</h2></div>
  </header>
  <div data-grid-viewport tabindex="0">
    <table class="table">
      <thead>
        <tr>
          <th>
            <input type="checkbox" data-grid-select-all aria-label="选择全部" />
          </th>
          <th aria-sort="none">
            <button type="button" data-grid-sort="name">名称</button>
          </th>
        </tr>
      </thead>
      <tbody>
        <tr data-value="production">
          <td data-grid-select-cell>
            <input
              type="checkbox"
              data-grid-select
              value="production"
              aria-label="选择生产环境"
            />
          </td>
          <td data-label="名称">生产环境</td>
        </tr>
      </tbody>
    </table>
  </div>
</section>

#参数

#JavaScript API

const grid = document.querySelector(".data-grid");
grid.setSelection(["production", "staging"]);
grid.toggleSelection("preview", true);
grid.setSort("name", "ascending");
grid.setState("loading", { message: "正在刷新运行环境…" });
console.log(grid.getState());
grid.addEventListener("a3s:data-grid-sort", ({ detail }) => loadPage(detail));

getSelection()、setSelection()、toggleSelection()、selectAll() 和 clearSelection() 会同步行复选框、选中行、表头复选框与嵌套的批量操作栏。getSort() 与 setSort() 控制唯一排序列。getState() 返回视图、选择与排序快照，setState() 切换反馈区，refresh({ preserveSelection, preserveSort }) 用于替换行后重新绑定。

a3s:data-grid-before-selection-change、a3s:data-grid-before-sort 和 a3s:data-grid-before-row-action 是可取消前置钩子。完成事件为 a3s:data-grid-selection-change、a3s:data-grid-sort、a3s:data-grid-row-action 与 a3s:data-grid-state-change。详情包含 previous、current、source 和 originalEvent，并保留 values、selectedCount、key、direction 兼容字段。控制器不重排行、不请求数据，也不替宿主授权命令。

#状态与变体

客户端集合可以直接替换行；服务端集合在后台加载时应保留当前筛选、排序、已有行与列宽。为空、错误和权限不足分别提供 data-grid-state="empty"、error 与 permission-denied 区域，让每种状态都说明问题与恢复动作。行操作属于网格契约，不需要单独的公共组件。

默认模式在窄屏保留横向滚动；只有当记录字段仍能线性阅读时才使用 data-responsive="stack"。大量列、可编辑单元格或列间比较任务应继续使用滚动表格。

#无障碍

表头必须使用真实 <th>，可排序列把 aria-sort 放在表头而不是按钮上。每个复选框都需要包含行名称的标签；批量操作出现后不移动焦点。服务端更新结果数量时使用礼貌播报，加载期间不要清空当前选择而不解释原因。