Skip to Content
帮助文档数据处理操作指南获取数据源与数据绑定

获取数据源与数据绑定

在 Zion 平台中，当配置完底层数据库或第三方外部 API 后，即可通过声明数据源来获取数据，并将其与页面和前端组件进行一键式映射绑定。

本指南将系统讲解如何获取数据源、使用条件过滤、去重与限额，并通过一个经典的“博客网站”开发实例展示完整的前后端数据流转闭环。

1. 数据绑定核心使用流程

在 Zion 中，获取并消费数据主要通过以下两个核心路径完成：

建立并配置数据源

您可以在页面中或特定的列表型组件（如列表、选择视图、下拉选择器）中直接配置数据源来获取数据。

数据源的两个主要配置端点：

  • 列表型组件数据配置：直接在列表组件右侧的“数据”面板中选择对应的数据表或 API。
  • 页面级数据源配置：选中页面节点，在右侧“数据”面板中声明一个“页面数据源”。页面数据源常用于拉取详情或作为页面内所有组件的共享数据。

数据拉取控制参数（四项基本原则）：

  • 过滤 (Filter)：配置一组或多组由 AND 或 OR 串联的逻辑条件，用来筛选出符合业务要求的数据。
  • 排序 (Sort)：定义查询结果在页面的展示先后顺序（如按创建时间倒序排列）。若字段已开启了 向量化存储，您可以使用“向量距离”进行相关度排序。注意：若配置了去重，排序字段的声明顺序必须与去重字段保持完全一致。
  • 去重 (Distinct)：当需要获取不重复的数据集时，可勾选指定去重字段，确保相同属性的记录在列表中只展示一次。
  • 数据限额 (Limit)：控制本次数据请求返回的记录最大数。1 表示仅获取匹配的第一条记录（返回单条 JSON 对象），大于 1 则返回包含多条记录的数据数组。
⚠️

过滤条件中的空值特殊处理原则：
在关系型数据库中，任何具体数值与空值（null）进行直接比较判定时，其逻辑结果默认总是为 true（不会进行拦截）。

  • 最佳实践：若您希望当输入值为空时直接返回 false（不显示任何数据），可使用“条件数据”进行包装：例如，原本的筛选条件是 id = ${inputValue}。您可以添加一个条件判定，若发现 inputValue 为空值，则强行向其返回一个数据库中绝对不可能存在的值（如 -1）。由于 id 均为正整数，id = -1 将永远判定为 false，从而实现安全的空数据拦截。

组件级数据绑定

数据源创建并验证通过后，您可以在页面或组件中进行数据绑定（即建立页面显示元素与数据库字段的通路）。

  • 页面数据源绑定：可被页面内的所有非嵌套组件、富文本和行为流节点引用。路径为：“页面内数据” → “数据源”。
  • 列表数据源绑定：在列表项（Item）内部的组件，可以访问当前项的完整数据。路径为：“组件内数据” → “列表”。
    1. 列表内部组件可以读取当前行索引（index）和该项完整数据对象（item）。
    2. 可以将文本直接绑定到 item.title，或图片组件的图片源绑定至 item.cover_image 字段上。

2. 实战演练：简易“博客系统”数据闭环实现

本节将以开发一个经典的“博客发布与阅读系统”为例，带您完整跑通数据的创建、读取、修改 全链路。

第一步：数据模型设计

在 数据库配置 中，我们需要设计以下关联实体表：

  • post（文章表）：包含字段 title（标题-文本）、content（内容-富文本）、published_status（发布状态-布尔）、show_at（上架时间-时间）、like_count（点赞数-整数）、author_account（作者-关联帐户表的一对多字段）。

第二步：创建数据（发表文章）

将用户在前端输入的内容，安全地保存进数据库中：

  1. 页面排版：创建一个“写博客”页面，拖入输入框组件作为标题（input_title），拖入富文本编辑器（rich_content）作为正文，并添加“发布”按钮。
  2. 行为配置：选中发布按钮，在行为面板添加 “创建记录”（或修改表数据）动作，目标表选择 post 表。
  3. 数据映射：将表中的 title 映射绑定为前台 input_title 的输入值；将 content 映射绑定为 rich_content 的内容；将 published_status 直接赋值为常量 true；将作者字段 author_account 绑定为系统的当前登录用户 ID。

添加博客行为配置

第三步：读取列表数据（博客大厅展示）

  1. 列表绑定：在“博客大厅页面”添加列表组件。将其数据源配置选择为 post 数据表。
  2. 查询控制：
    • 过滤条件：设置 published_status = true，只获取已发表的文章，剔除未发表的草稿。
    • 排序控制：设置按 show_at 执行“降序（Descending）”排列，确保最新发表的文章置顶展示。
  3. 前端渲染：双击列表项，将内部的文本标签绑定为 item.title，将封面图绑定至 item.cover_image。

列表数据源配置

第四步：读取单条详情数据（文章阅读详情）

  1. 参数传递：在“文章详情页面”的“数据”中，声明一个 路径参数 post_id。
  2. 跳转绑定：回到博客大厅，选中列表项，为其绑定 “页面跳转” 行为，跳转目标为“文章详情页”。并在跳转传参选项中，将当前项的 ID（item.id）赋值传递给路径参数 post_id。
  3. 详情页面数据配置：进入文章详情页。声明一个页面数据源，目标表为 post，并添加极其关键的过滤条件：id 等于 路径参数.post_id，同时将数据限额设置为 1。
  4. 绑定展示：将详情页的大标题组件和正文富文本组件，直接绑定到该单条页面数据源的 title 和 content 属性上，即可实现精准的文章渲染。

详情页数据源配置

第五步：修改现有记录数据（文章点赞）

  1. 点赞按钮行为：在文章详情页中，选中“点赞（点爱心）”图标，添加“修改数据记录”行为，目标表为 post 表。
  2. 精准过滤锁定：在修改行为属性中，添加修改过滤条件：id 等于 页面数据源.post_id（此步骤极度重要，缺失或错配此过滤会导致全表所有数据被批量误修改）。
  3. 字段变更：在执行修改的属性列表中，指定将字段 like_count 赋值修改为 页面数据源.like_count + 1。这样用户每次点击，点赞数便会在线上实时递增 1。
Last updated on
向量存储与排序使用变量与参数