如何自定义Strapi 5中Order集合类型的列表布局

核心思路 #

Strapi 5支持通过项目内的Admin扩展机制，直接替换指定集合的默认列表路由组件，用自定义的卡片/列布局组件替代原生表格。以下是具体实现步骤：

步骤1：初始化Admin扩展结构 #

如果项目中没有src/admin目录，先运行命令生成基础扩展框架：

strapi generate admin:extension

步骤2：创建自定义列布局组件 #

在src/admin/components/OrderCardList/index.tsx中编写卡片式列布局组件，复用Strapi官方UI组件和数据钩子来简化开发：

import React from 'react';
import { Box, Grid, Card, CardContent, Typography } from '@strapi/design-system';
import { useList, useNotification, useLayout } from '@strapi/helper-plugin';
import { useIntl } from 'react-intl';

const OrderCardList = () => {
  const { formatMessage } = useIntl();
  const { toggleNotification } = useNotification();
  const { ListLayout } = useLayout();
  
  // 用useList钩子自动处理数据筛选、分页、排序，替换为你的Order集合UID
  const { data, isLoading, error, filters, setFilters, sort, setSort, pagination, setPagination } = useList('api::order.order');

  // 错误提示逻辑
  React.useEffect(() => {
    if (error) {
      toggleNotification({ 
        type: 'warning', 
        message: formatMessage({ id: 'notification.error', defaultMessage: '加载订单失败' }) 
      });
    }
  }, [error, toggleNotification, formatMessage]);

  // 渲染内容区域
  const renderContent = () => {
    if (isLoading) {
      return <Typography variant="body">加载中...</Typography>;
    }

    // 列布局配置：columns控制总列数，col控制单个卡片占比
    return (
      <Grid gap={4} columns={6}>
        {data.map((order) => (
          <Card key={order.id} col={2}>
            <CardContent>
              <Typography variant="h5" fontWeight="bold">订单 #{order.id}</Typography>
              <Typography variant="body" color="neutral600">客户: {order.attributes.customerName}</Typography>
              <Typography variant="body">状态: {order.attributes.status}</Typography>
              <Typography variant="body">总计: ${order.attributes.total}</Typography>
            </CardContent>
          </Card>
        ))}
      </Grid>
    );
  };

  // 保留原生顶部工具栏（筛选、创建按钮等）
  return (
    <ListLayout
      content={renderContent()}
      filters={filters}
      setFilters={setFilters}
      sort={sort}
      setSort={setSort}
      pagination={pagination}
      setPagination={setPagination}
      title={formatMessage({ id: 'app.components.ListLayout.title', defaultMessage: '订单' })}
      hasCreateAction
      createLabel={formatMessage({ id: 'app.components.ListLayout.create', defaultMessage: '创建订单' })}
    />
  );
};

export default OrderCardList;

步骤3：替换Order集合的默认列表路由 #

在src/admin/app.ts中注册扩展，拦截并替换Order集合的列表页组件：

import { createApp } from '@strapi/admin';
import OrderCardList from './components/OrderCardList';

export default createApp({
  bootstrap(app) {
    // 拦截路由注册逻辑，匹配Order集合的列表路由
    app.registerHook('Route', ({ route }) => {
      // 路由ID格式为`collectionType.application.[集合名].list`，集合名需小写
      if (route.id === 'collectionType.application.order.list') {
        return {
          ...route,
          component: OrderCardList,
        };
      }
      return route;
    });
  },
});

关键注意事项 #

• 集合UID正确性：通过strapi generate content-type创建的集合，UID格式为api::[集合名].[集合名]（比如Order对应api::order.order）；插件内的集合格式为plugin::[插件名].[集合名]。
• 路由ID匹配：路由ID中的集合名必须是小写，比如Order对应order。
• 权限继承：自定义组件会自动继承原生列表页的权限控制，无需额外配置。
• 生效方式：修改完成后重启strapi develop，Admin面板会自动重新构建并加载自定义组件。

内容的提问来源于stack exchange，提问作者Assad Rajab