Cuttlefish Docs
  • 简体中文

    • spz-data-source

    AI 摘要

    • 该页面由脚本自动同步生成，优先用于补齐目录可见性与基础说明。
    • 若原始文档缺失，请先在 cuttlefish 对应组件补充最小文档后再同步。

    原始文档（英文）

    spz-data-source 用于统一获取商品、商品列表、专辑等数据，并将结果分发给下游组件（如 spz-render、spz-list）。

    何时使用

    • 需要在页面中集中管理数据请求并复用请求结果时
    • 需要将数据以 custom:<id>.getData 方式提供给渲染组件时
    • 需要根据不同数据源类型（单商品、商品列表、专辑、推荐等）做统一接入时

    支持布局

    • container

    代码演示

    单商品

    <spz-data-source
  id="source"
  layout="container"
  source-type="product"
  source-id="b3d660c5-52e4-418d-a996-c3b2eb6d35fb"
  items="data.product"
>
  <spz-render layout="container" src="custom:source.getData">
    <template>
      <div>${data.title}</div>
    </template>
  </spz-render>
</spz-data-source>

    多商品列表

    <spz-data-source
  id="source-list"
  layout="container"
  source-type="product-list"
  source-id="b3d660c5-52e4-418d-a996-c3b2eb6d35fb,b3d660c5-52e4-418d-a996-c3b2eb6d35fc"
  items="data.list"
>
  <spz-render layout="container" src="custom:source-list.getData">
    <template>
      ${data.map((item) => `<div>${item.title}</div>`).join('')}
    </template>
  </spz-render>
</spz-data-source>

    专辑商品

    <spz-data-source
  id="source-collection"
  layout="container"
  source-type="collection"
  source-id="75a2e91a-ab0e-484f-9803-f52d8a9ac4e7"
>
  <spz-list
    layout="container"
    src="custom:source-collection.getData"
    list="data.products"
    total="data.count"
    page-size="10"
  >
    <template>
      <div>${data.title}</div>
    </template>
  </spz-list>
</spz-data-source>

    属性

    属性名说明类型是否必需
    source-type数据源类型。可选：product、product-list、collection、recently-viewed、recommendation、random。默认 productstring否
    source-id数据源 ID。不同 source-type 下语义不同（商品 ID、专辑 ID、逗号分隔商品 ID 列表）string否
    items数据提取表达式。用于从响应对象中提取目标字段，例如 data.product、data.liststring否
    product-data直接注入 JSON 数据，存在时优先使用该数据而不是远程请求string否
    page-size分页请求 size，对 product-list、collection、recommendation、random 等列表类型生效number否
    init-page初始页码，默认 0number否
    index在父级数据源列表中的索引，用于嵌套数据源按索引取值string | number否
    data-random编辑模式标记。存在时内部强制使用 random 数据源boolean否

    运行时状态属性

    属性名说明类型
    data-empty数据为空或请求失败时自动挂载到元素上boolean
    finish请求流程执行后自动挂载到元素上boolean

    方法

    getData

    获取并返回当前数据源结果，支持被其他组件通过 custom:<id>.getData 调用。

    参数名说明类型是否必需
    param请求参数对象，常见结构：{ params: { page, limit } }。未传时使用默认分页参数object否
    type指定提取类型（用于父子数据源场景）string否
    id指定数据项 ID 或索引（用于父子数据源场景）string | number否

    返回值：

    • Promise<any>

    注意事项

    • spz-data-source 本身不负责 UI 渲染，推荐与 spz-render、spz-list 搭配使用。
    • 当存在父级 spz-data-source 时，子级会优先尝试复用父级数据，减少重复请求。
    • items 表达式决定了下游拿到的数据结构，建议和模板中的数据访问路径保持一致。