Polaris Data Table

中文 · English

@standhigher/polaris-data-table 是用于 Shopify Polaris 应用的受控、服务端驱动数据表格基础组件。

它提供熟悉的 Polaris 表格界面，同时由你的应用掌控数据请求、查询状态、权限、URL 状态和持久化。

链接

• npm 包
• GitHub 仓库
• 文档
• Storybook 示例
• API Reference
• 使用指南
• 更新日志

安装

npm install @standhigher/polaris-data-table @shopify/polaris react react-dom

该表格需要 @shopify/polaris >=12 <15、React 18 或更高版本，以及 React DOM 18 或更高版本。请在 Polaris AppProvider 下渲染表格；详见安装指南。

基础用法

Table 是受控组件。请在拥有该表格的页面中保留当前 query、分页数据与 selection。

import {useState} from 'react';
import {
  Table,
  type TableDataPage,
  type TableQuery,
  type TableSelection,
} from '@standhigher/polaris-data-table';

type Product = {
  id: string;
  title: string;
  price: number;
  currencyCode: string;
  createdAt: string;
};

export function ProductsTable({page}: {page: TableDataPage<Product>}) {
  const [query, setQuery] = useState<TableQuery>({page: 1, pageSize: 25});
  const [selection, setSelection] = useState<TableSelection>({
    mode: 'explicit',
    ids: [],
  });

  return (
    <Table
      columns={[
        {key: 'title', title: 'Product', sortable: true},
        {
          key: 'price',
          title: 'Price',
          type: 'money',
          currencyCode: (product: Product) => product.currencyCode,
        },
        {key: 'createdAt', title: 'Created', type: 'datetime'},
      ]}
      data={page.data}
      rowId="id"
      query={query}
      pagination={{total: page.total}}
      formatOptions={{
        locale: 'en-US',
        timeZone: 'America/New_York',
        defaultCurrencyCode: 'USD',
      }}
      selection={selection}
      onSelectionChange={setSelection}
      onQueryChange={setQuery}
    />
  );
}

当 onQueryChange 收到新的 query 时，在服务端加载对应分页，并将返回的 {data, total} 传回 Table。完整数据流约定见第一个受控表格。

能力概览

| 范畴 | 提供的能力 | | --- | --- | | 受控 query 与分页 | 基于页码、兼容 offset 的分页；带类型的 search、sort 与 filter 状态。 | | Polaris 列与格式化 | text、number、money、status、date/time、image、actions 和 custom renderer。 | | Selection 与批量操作 | 显式 selection，或由服务端签发且绑定 query 的跨页 selection token。 | | URL 状态与视图 | query 编解码、可见列状态、filter preset 和 saved-view 辅助工具。 | | 高级表格基础能力 | cursor 数据模型、虚拟窗口、列布局、展开行与行内编辑状态。 | | 渲染器抽象 | 框架无关的 core schema 与 Polaris renderer adapter。 |

兼容性

| 依赖 | 支持版本 | | --- | --- | | Node.js | 20 或更高（开发和 CI） | | React / React DOM | 18 或更高 | | @shopify/polaris | >=12 <15 |

本包仅支持 ESM，并发布 TypeScript 类型声明。peer dependencies 不会被打包进产物。

示例、Storybook 与演示

• 浏览交互式 Storybook 示例。
• 阅读 server query example，了解 offset 分页和格式化。
• 阅读 selection and bulk actions example，了解服务端 selection token。
• 使用 API Reference 查阅导出的类型和函数。

包质量

每次修改均由 CI 运行测试、类型检查、lint、包入口验证、生产构建、Storybook 构建和 npm pack --dry-run。

提交 Pull Request 前，请运行：

npm run lint
npm test
npm run typecheck
npm run build
npm run build-storybook
npm run docs:build
npm pack --dry-run --registry=https://registry.npmjs.org/

本地开发

git clone https://github.com/standhigher/shopify-polaris-table.git
cd shopify-polaris-table
npm ci
npm run docs:start

使用 npm test 运行测试，使用 npm run build-storybook 生成预览，使用 npm run docs:build 生成完整文档站。贡献要求请见 CONTRIBUTING.md。

发布准备

发布只能从已合并的 main 进行。发布前验证包内容与全部检查：

npm run release:check
npm login --auth-type=web --registry=https://registry.npmjs.org/
npm publish --access public --tag latest --auth-type=web --registry=https://registry.npmjs.org/

发布命令默认在交互式终端执行，确保 npm 能打开浏览器验证链接，并通过 passkey、安全密钥或本机指纹完成 npmjs 验证。完整的 registry 检查、版本升级、annotated tag、预发布 tag 和发布后验证流程见发布指南。

贡献与支持

欢迎贡献；开始前请阅读 CONTRIBUTING.md、CODE_OF_CONDUCT.md 与 SECURITY.md。可复现的问题请通过 GitHub Issues 反馈；安全漏洞请使用私密安全公告。

许可证

MIT © StandHigher