10分钟上手！amis列表组件：3种布局+5大交互技巧让数据展示更高效

2026-02-04 04:29:12作者：仰钰奇

你是否还在为数据展示页面的开发效率低而烦恼？是否因不懂前端技术而无法快速构建美观的列表界面？本文将带你一文掌握amis列表组件的使用方法，通过简单的JSON配置，无需编写复杂代码，即可快速实现专业级的数据展示页面。读完本文后，你将能够：

掌握表格、列表、卡片三种布局的配置方法
实现拖拽排序、批量操作、快速编辑等高级交互
了解列表组件的核心API和最佳实践

列表组件简介

amis是一个前端低代码框架，通过JSON配置就能生成各种页面。列表组件（CRUD组件）是amis中最常用的数据展示组件之一，支持多种布局和丰富的交互方式。官方提供了多个示例文件，位于examples/components/CRUD/目录下，包含List.jsx、Grid.jsx、Table.jsx等多种布局实现。

三种常用布局

表格布局（Table）

表格布局是最传统的数据展示方式，适合展示结构化数据。通过设置type: 'crud'并配置columns属性即可实现。

{
  "type": "crud",
  "api": "/api/sample",
  "columns": [
    { "name": "id", "label": "ID", "sortable": true },
    { "name": "engine", "label": "Rendering engine", "sortable": true },
    { "name": "browser", "label": "Browser" }
  ]
}

上述代码来自examples/components/CRUD/Table.jsx，实现了一个基础的表格布局，包含ID、引擎名称和浏览器三列，其中ID和引擎名称列支持排序。表格布局还支持分页、列显示切换、行操作等功能。

列表布局（List）

列表布局以垂直卡片的形式展示数据，每个条目包含更多详细信息。通过设置mode: 'list'和listItem属性来定义列表项的结构。

{
  "type": "crud",
  "api": "/api/sample",
  "mode": "list",
  "listItem": {
    "body": [
      { "name": "engine", "label": "Rendering engine" },
      { 
        "type": "hbox",
        "columns": [
          { "name": "browser", "label": "Browser" },
          { "name": "platform", "label": "Platform(s)" }
        ]
      },
      { "name": "version", "label": "Engine version" }
    ]
  }
}

以上代码片段来自examples/components/CRUD/List.jsx，定义了一个包含引擎名称、浏览器和平台（横向排列）、引擎版本的列表项布局。列表布局适合展示需要突出条目标题和关键信息的数据。

网格布局（Grid/Cards）

网格布局以卡片形式展示数据，适合图片或内容块式的数据展示。通过设置mode: 'cards'和card属性来定义卡片结构。

{
  "type": "crud",
  "api": "/api/sample",
  "mode": "cards",
  "card": {
    "header": {
      "title": "$engine",
      "subTitle": "$platform",
      "avatar": "<%= data.avatar || 'https://internal-amis-res.cdn.bcebos.com/images/2019-12/1575350573496/4873dbfaf6a5.png' %>"
    },
    "body": [
      { "name": "engine", "label": "engine" },
      { "name": "browser", "label": "Browser" },
      { "name": "platform", "label": "Platform" }
    ]
  }
}

上述代码来自examples/components/CRUD/Grid.jsx，实现了一个带有头像、标题和子标题的卡片布局。网格布局默认采用响应式设计，会根据屏幕宽度自动调整每行显示的卡片数量。

高级交互功能

拖拽排序

通过设置draggable: true可以启用列表项拖拽排序功能，结合saveOrderApi保存排序结果。

{
  "type": "crud",
  "mode": "list",
  "draggable": true,
  "saveOrderApi": {
    "url": "/api/sample/saveOrder"
  },
  "orderField": "weight"
}

以上代码片段来自examples/components/CRUD/List.jsx，启用了拖拽排序功能，并指定了排序字段为"weight"，排序变更后会通过POST请求发送到"/api/sample/saveOrder"接口保存。

批量操作

列表组件支持批量选择和批量操作，通过bulkActions属性配置。

{
  "type": "crud",
  "bulkActions": [
    {
      "label": "批量删除",
      "actionType": "ajax",
      "api": "delete:/api/sample/${ids|raw}",
      "confirmText": "确定要批量删除?"
    },
    {
      "label": "批量修改",
      "actionType": "dialog",
      "dialog": {
        "title": "批量编辑",
        "body": {
          "type": "form",
          "api": "/api/sample/bulkUpdate2",
          "body": [
            { "type": "hidden", "name": "ids" },
            { "type": "input-text", "name": "engine", "label": "Engine" }
          ]
        }
      }
    }
  ]
}

上述代码来自examples/components/CRUD/Table.jsx，定义了两个批量操作：批量删除和批量修改。批量操作会在用户选择列表项后显示，提高了数据管理效率。

快速编辑

通过quickEdit: true可以为列表项字段启用快速编辑功能，无需打开编辑表单即可直接修改数据。

{
  "columns": [
    {
      "name": "version",
      "label": "Engine version",
      "quickEdit": true
    },
    {
      "name": "grade",
      "label": "CSS grade",
      "quickEdit": {
        "saveImmediately": true,
        "mode": "inline",
        "type": "select",
        "options": ["A", "B", "C", "D", "X"]
      }
    }
  ]
}

以上代码来自examples/components/CRUD/Table.jsx，为"Engine version"字段启用了默认的快速编辑功能，为"CSS grade"字段自定义了快速编辑的类型为下拉选择框，并设置了立即保存。

工具栏配置

列表组件头部和底部工具栏可以通过headerToolbar和footerToolbar属性自定义。

{
  "type": "crud",
  "headerToolbar": [
    "filter-toggler",
    "bulkActions",
    {
      "type": "tpl",
      "tpl": "定制内容示例：当前有 ${count} 条数据。",
      "className": "v-middle"
    },
    {
      "type": "columns-toggler",
      "align": "right"
    },
    {
      "type": "pagination",
      "align": "right"
    }
  ],
  "footerToolbar": ["statistics", "switch-per-page", "pagination"]
}