数据提供器

将表格数据带到前端，并支持服务端分页和过滤。

Toolpad Studio 函数非常适合将一些后端状态引入页面，但当涉及到提供来自服务端的分页和过滤功能时，它们就显得不足。Toolpad Studio 提供了一个特殊的构造来实现这种用例：数据提供器。数据提供器抽象了服务端集合。它们可以是数据库表、REST API，或任何代表一组共享通用接口的记录的数据。数据提供器被定义为服务端对象，可以直接连接到数据网格，使其完全交互。

按照以下步骤创建新的数据提供器

一个迭代静态列表的数据提供器可能如下所示

import { createDataProvider } from '@toolpad/studio-runtime/server';
import DATA from './movies.json';

export default createDataProvider({
  async getRecords({ paginationModel: { start = 0, pageSize } }) {
    const records = DATA.slice(start, start + pageSize);
    return { records, totalCount: DATA.length };
  },
});

分页

数据提供器支持两种分页样式。基于索引的分页和基于游标的分页。

基于索引的分页

这是一种策略，其中你的数据通过基于起始索引和页面大小返回数据来进行分页。getRecords 方法在其 paginationModel 参数中接收 start 和 pageSize 值，并返回一组代表页面的记录。基于索引的分页是默认设置，但你可以通过将 paginationMode 设置为 'index' 来显式启用它。

export default createDataProvider({
  paginationMode: 'index',
  async getRecords({ paginationModel: { start = 0, pageSize } }) {
    const { page, totalCount } = await db.getRecords(start, pageSize);
    return {
      records: page,
      totalCount,
    };
  },
});

这是一种策略，其中你的数据通过当它基于游标和页面大小返回数据时进行分页。getRecords 方法在其 paginationModel 参数中接收 cursor 和 pageSize 值，并返回一组代表页面的记录。你可以在结果中使用 cursor 属性来指示下一页的游标。传递 null 以表示集合的结尾。你可以通过将 paginationMode 设置为 'cursor' 来启用基于游标的分页。

当 Toolpad Studio 获取初始页面时，paginationModel 的 cursor 属性为 null。任何从 getRecords 函数返回的结果集都必须附带一个 cursor 属性，该属性是一个字符串，其中包含对下一页的引用。当获取后续页面时，paginationModel 中的 cursor 参数包含此值。返回 null 作为此值以指示序列的结尾。

export default createDataProvider({
  paginationMode: 'cursor',
  async getRecords({ paginationModel: { cursor = null, pageSize } }) {
    const { page, nextPageCursor, totalCount } = await db.getRecords(
      cursor,
      pageSize,
    );
    return {
      records: page,
      cursor: nextPageCursor,
      totalCount,
    };
  },
});

过滤

Toolpad Studio 数据源支持服务端过滤。你可以通过读取传递给 getRecords 函数的 filterModel 属性来实现服务端过滤器。此模型包含一个 items 属性和一个 logicOperator。通过组合它们，你可以实现复杂的服务端过滤器。

export default createDataProvider({
  async getRecords({ filterModel }) {
    console.log(filterModel);
  },
});

例如，如果在数据网格中应用了相应的列过滤器，则可能会打印以下内容

{
  logicOperator: 'and',
  items: [
    { field: 'first_name', operator: 'startsWith', value: 'L' },
    { field: 'last_name', operator: 'equals', value: 'Skywalker' },
  ]
}

现在，后端函数在其参数中接收来自 UI 的网格过滤器。

如果你想禁用特定列的过滤，请取消选中列选项 “filterable”

禁用可过滤

排序

Toolpad Studio 数据源支持服务端排序。为了实现这一点，你必须使用传递给 getRecords 方法的 sortModel 属性

export default createDataProvider({
  async getRecords({ sortModel }) {
    console.log(sortModel);
  },
});

根据已设置为排序依据的列，这将导致

[{ field: 'name', sort: 'asc' }];

现在，后端函数在其参数中接收来自 UI 的网格排序模型。

如果你想禁用特定列的排序，请取消选中列选项 “sortable”

禁用可排序

行编辑

数据提供器可以扩展为自动支持行编辑。要启用此功能，你必须向数据提供器接口添加一个 updateRecord 方法，该方法接受要编辑的行的 id，以及一个包含来自行编辑操作的所有更新字段的对象。

export default createDataProvider({
  async getRecords() {
    return prisma.users.findMany();
  },

  async updateRecord(id, data) {
    return prisma.users.update({ where: { id }, data });
  },
});

当此方法在数据提供器中可用时，每行都会获得一个编辑按钮。此编辑按钮使行进入编辑模式。要提交更改，请按处于编辑模式的行上的保存按钮。要放弃更改，请使用取消按钮。

你可以通过取消选中列定义中的 Editable 选项来禁用特定列的编辑功能。

禁用可编辑

行创建

数据提供器可以扩展为支持创建新行。要启用此功能，你必须向数据提供器接口添加一个 createRecord 方法。此方法接收一个对象，其中包含创建 UI 中用户提供的所有值。

export default createDataProvider({
  async getRecords() {
    return prisma.users.findMany();
  },

  async createRecord(data) {
    return prisma.users.create({ data });
  },
});

在你使此方法在数据提供器中可用之后，“添加记录”按钮将出现在数据网格工具栏中。单击此按钮，网格顶部将出现一个新的可编辑行。填写值，然后单击“保存”按钮以完成创建行。你必须从 createRecord 方法返回新创建的行，以便网格可以相应地更新。

删除行

数据提供器可以扩展为自动支持行删除。要启用此功能，你必须向数据提供器接口添加一个 deleteRecord 方法，该方法接受要删除的行的 id。

export default createDataProvider({
  async getRecords({ paginationModel: { start = 0, pageSize } }) {
    return db.query(`SELECT * FROM users`);
  },

  async deleteRecord(id) {
    await db.query(`DELETE FROM users WHERE id = ?`, [id]);
  },
});

当数据提供器包含 deleteRecord 方法时，每行都有一个删除按钮。当用户单击该删除按钮时，将使用该行的 id 调用删除方法，并在成功删除后重新加载数据。

数据提供器中的删除操作

API

请参阅下面的文档，以获得本页中提及的所有函数和接口的完整参考。

createDataProvider