Malla文档

显示 API 数据

连接 REST API,运行查询,并将结果绑定到集合列表。

用户指南
中级20 分钟

你将构建: 一个页面,用卡片网格列出来自公共 REST API 的文章,并带有空状态

请先阅读: 快速入门构建落地页

在本教程中,你将连接一个 REST API,编写获取文章列表的查询,并在页面上把每篇文章显示为一张卡片。示例使用 JSONPlaceholder,这是一个无需密钥的免费测试 API,所以只要有一个站点就能跟着做。

显示 API 数据视频即将推出。下面的文字步骤已涵盖全部内容。
显示 API 数据· 7 分钟

连接 API

  1. 打开 Data 工作区

    打开你要处理的页面,然后点击左侧边栏底部的 Data。Data 工作区列出页面的变量、查询、公式以及站点的集成。再次点击 Data 或它的关闭图标,即可回到画布。

  2. 添加 REST 集成

    在 Integrations 旁点击 +(Add integration),选择 REST API。命名为 Placeholder API。

    在 Connection 卡片中,把 Base url 设为 https://jsonplaceholder.typicode.com。Auth type 保持为 none:这个 API 是公开的。

  3. 创建并测试连接

    点击 Create integration。会出现一张 Test connection 卡片:点击 Run test,等待显示 Connected。测试使用已保存的设置,所以修改后请先保存再测试。

编写查询

  1. 添加查询

    在 Queries 旁点击 +(Add query)。在顶部的字段中把查询名从 query 改为 posts。它的结果现在可以通过 queries.posts.data 访问。

  2. 指向该 API

    在 Source 卡片中,把 Integration 设为 Placeholder API。Operation 会切换为 Request。

  3. 填写请求

    在 Input 卡片中,保持 Method 为 GET,把 Path 设为 /posts?_limit=6。路径会拼接在基础 URL 后面,所以这个查询请求的是前六篇文章。

  4. 选择何时运行

    在 When it runs 中选择 Static。查询在发布时运行,文章会写入 HTML,速度快且利于搜索引擎。当数据必须在每次请求时都是最新的,选择 Server;当数据取决于访客在浏览器中的操作时,选择 Client。

  5. 测试

    在 Result 卡片中点击 Run。响应会以树形结构显示:一个包含六个对象的数组,每个对象有 userId、id、title 和 body。

检查点

Data 工作区列出了 posts 查询,标注为 static · Placeholder API,它的 Result 卡片显示六篇文章。

在页面上显示文章

  1. 插入集合列表

    回到画布,选中页面框架或某个区块。在 Layers 标签页中点击 +,选择 Collection list。它是一个三列网格,带有一个子元素 Item,会为每篇文章重复一次。

  2. 用查询作为数据源

    选中列表,在检查器中打开 Collection list。如果 Source 还不是 Expression,就把它设为 Expression。Items 会自动填为 queries.posts.data;如果没有,点击它的绑定按钮并输入。

  3. 在条目中添加文本

    按 T,在 Item 内拖动,添加一段文本作为标题,再添加第二段文本作为正文。条目的每个重复项都会获得相同的图层。

  4. 绑定文本

    选中标题文本。在 Typography 中点击文本旁的绑定按钮,输入 item.title。用同样的方法把第二段文本绑定到 item.body。现在每张卡片都显示自己的文章。

  5. 设置一张卡片的样式

    选中 Item,给它设置内边距、填充色和圆角。样式会作用于每张卡片,因为它们都是同一个条目的重复项。

检查点

画布以网格形式显示六张卡片,每张都有不同的标题和正文。

处理空结果

  1. 编写空状态

    选中集合列表,把 Empty text 设为 No posts yet.。当列表没有条目时,会显示这段文字而不是卡片。

  2. 试一试

    在 Data 工作区中,把查询的 Path 改为 /posts?userId=999。没有用户使用这个 id,所以 API 返回空数组,画布显示你的空状态文字。完成后把路径改回 /posts?_limit=6。

  3. 预览并发布

    按 ⌘↵ 预览页面,然后点击 Publish。静态查询会在发布过程中运行,所以已发布页面的 HTML 中就包含这些文章。

完成

你的页面列出了来自 API 的文章,在没有文章时显示提示信息,并已在预发布环境上线。

你学到了什么

  • 集成保存基础 URL、请求头和密钥;查询可以复用它。
  • 查询选择一个操作,填写其输入,并以静态、服务端或客户端模式运行。
  • 数据源为 Expression 的集合列表,会为查询结果中的每个元素重复一次它的条目,item.* 读取当前元素。

阅读本教程背后的指南: