画廊视图

插件简介

plugin-gallery-view 是一个画廊视图区块插件，用于以图片卡片和轮播的方式展示多条数据记录。它适合产品展示、案例展示、影像资料、作品集浏览、图文内容导览等场景。

当前版本支持以下能力：

• 支持封面流、缩略图、纵向三种展示模式，对应界面选项值分别为 Effect cover flow、Thumbs、Vertical
• 支持封面、标题、简介字段映射
• 支持附件字段作为封面图来源
• 支持关联字段封面自动补充查询 appends
• 支持配置布局模式、卡片间距、显示数量、图片适应方式、轮播间隔
• 支持一键恢复默认外观参数
• 支持容器尺寸较小时自动进入紧凑布局
• 支持点击条目后打开记录详情弹窗
• 支持在未绑定数据源时使用内置假数据预览
• 支持扩展封面字段可选接口

使用前准备

在配置画廊视图区块前，建议先准备好对应的数据表和字段。字段不一定要全部具备，但准备越完整，展示效果越好。

推荐准备的字段如下：

• 封面字段：用于显示图片，例如“封面图”“主图”“缩略图”
• 标题字段：用于显示卡片标题，例如“标题”“名称”“大事记标题”
• 简介字段：用于显示简短说明，例如“简介”“说明”“内容摘要”

字段准备建议：

• 封面字段 建议优先使用附件字段
• 如果封面图来自关联表，可以直接映射关联字段，插件会自动补充资源查询所需的 appends
• 标题字段 建议使用较短的文本，避免在小尺寸布局中占用过多空间
• 简介字段 建议使用摘要型内容，便于卡片展示

版本依赖要求：

• @nocobase/client: 2.x
• @nocobase/server: 2.x
• @nocobase/test: 2.x

快速上手

下面用最短路径说明如何快速配置一个可用的画廊视图区块。

1. 添加画廊视图区块

在目标页面中添加区块后，选择：

• 区块名称：Gallery view
• 中文名称：画廊视图

该区块面向多条记录数据进行展示，会按当前数据源查询结果渲染画廊内容。

点击 创建区块 后，可以在数据区块列表中看到画廊视图入口：

2. 选择数据表

将画廊视图区块绑定到你要展示的数据表，例如：

• 项目大事记
• 产品资料
• 影像资料
• 案例展示记录

建议优先确认数据表中至少有封面字段和标题字段，这样可以先得到一个基础可读的画廊展示。

选择数据表示例：

3. 配置字段映射

选择完 数据表 后，会弹出 字段映射。

建议的最小配置是：

• 封面字段
• 标题字段
• 简介字段

字段映射建议：

• 封面字段 选择封面图字段
• 标题字段 选择主标题字段
• 简介字段 选择摘要说明字段

字段映射示例：

4. 设置布局与外观

完成字段映射后，继续设置：

• 布局模式
• 卡片间距
• 显示数量
• 图片适应方式
• 轮播间隔

常见组合建议：

• 需要更强视觉中心感时，使用封面流模式 Effect cover flow
• 需要主图加缩略图联动时，使用缩略图模式 Thumbs
• 需要在较高区域连续浏览内容时，使用纵向模式 Vertical

布局与外观设置示例：

5. 验证展示效果

配置完成后，重点检查以下几点：

• 是否已经按预期显示封面图、标题和简介
• 图片填充方式是否符合预期
• 轮播速度是否合适
• 显示数量在当前容器尺寸下是否合适
• 点击条目后是否会打开记录详情
• 数据范围和默认排序是否符合预期

画廊视图效果示例：

布局模式 为封面流 Effect cover flow 的效果示例：

布局模式 为缩略图 Thumbs 的效果示例：

布局模式 为纵向 Vertical 的效果示例：

点击条目后的详情弹窗示例：

配置详解

字段映射

字段映射用于告诉画廊视图区块，页面上每一部分内容应该读取哪个字段。

封面字段（Cover field）

用途：

• 显示每条记录的封面图片

推荐选择：

• 附件字段
• 存放图片地址的文本字段
• 关联表中的图片字段

展示效果：

• 如果字段中有图片，区块会读取首张图片作为封面图进行展示

注意：

• 默认支持附件字段接口
• 字段值支持数组、对象、字符串图片地址
• 如果映射到关联字段，插件会自动补充 appends 并刷新数据
• 如果未读取到图片，会显示占位图

标题字段（Title field）

用途：

• 显示每张卡片的主标题

推荐选择：

• 文本字段
• 能代表这条记录主题的字段

展示效果：

• 卡片内容区会优先显示这个字段作为标题

简介字段（Description field）

用途：

• 显示卡片摘要说明

推荐选择：

• 多行文本字段
• 用于描述内容简介的字段

展示效果：

• 卡片中会显示简介内容
• 在较小尺寸下，部分布局会自动隐藏简介，以优先保证图片展示效果

字段表达式

字段映射支持变量表达式，例如：

{{ ctx.collection.cover }}
{{ ctx.collection.title }}
{{ ctx.collection.description }}

说明：

• 如果当前集合本身存在 cover、title、description 字段，插件会优先按这组字段名进行展示

布局模式

布局模式 用于控制画廊采用哪种展示样式，界面字段名为 Layout mode。

可选值：

• Effect cover flow
• Thumbs
• Vertical

封面流（Effect cover flow）

适用场景：

• 强调中心卡片
• 更适合视觉展示型页面

展示效果：

• 中间卡片高亮显示
• 支持自动轮播
• 点击下方图文信息区域可打开详情弹窗

注意：

• 在较小尺寸下会自动进入紧凑布局
• 紧凑布局下会减少可见卡片数、缩小卡片间距、隐藏简介内容

缩略图（Thumbs）

适用场景：

• 需要主图和缩略图联动浏览
• 需要快速切换图片内容

展示效果：

• 主图支持轮播切换
• 底部缩略图支持联动定位
• 主图上叠加标题和简介

纵向（Vertical）

适用场景：

• 需要在较高区域中连续浏览多条内容

展示效果：

• 竖向轮播展示
• 支持鼠标滚轮切换
• 图片上叠加标题和简介

注意：

• 在较小高度下会自动切换为紧凑布局

外观

外观配置用于调整画廊的视觉样式和轮播行为。

卡片间距（Card gap）

用途：

• 控制卡片之间的间距

展示效果：

• 数值越大，卡片之间的空间越大

显示数量（Display count）

用途：

• 控制默认展示数量

展示效果：

• 用于影响当前布局下的可见卡片数量

注意：

• 当区块过窄或过矮时，插件会优先保证图片展示效果
• 实际展示数量可能会根据容器尺寸自动调整，不一定严格等于配置值

图片适应方式（Image fit）

用途：

• 控制图片在卡片中的填充方式

可选值：

• cover
• contain
• fill
• none

展示效果：

• 控制图片裁切、缩放与留白方式

轮播间隔（Carousel interval）

用途：

• 控制自动轮播间隔

展示效果：

• 0 表示关闭自动轮播
• 大于 0 时按设置间隔自动播放

恢复默认（Restore default）

用途：

• 一键恢复默认外观参数

默认外观参数如下：

{
  layoutMode: 'effectCoverFlow',
  cardGap: 16,
  displayCount: 4,
  imageFit: 'cover',
  carouselInterval: 3000,
}

数据范围

数据范围 用于控制画廊最终加载哪些记录。

使用建议：

• 如果只想展示当前项目的数据，可以在这里限制查询范围
• 如果只想展示某个分类或状态的数据，也可以结合数据范围做过滤

展示效果：

• 画廊只会渲染数据范围内的记录

默认排序

默认排序 用于控制画廊记录的先后顺序。

使用建议：

• 如果希望按时间顺序展示，可以按时间字段升序或降序排序
• 如果希望置顶某类重点内容，也可以通过默认排序控制顺序

展示效果：

• 最终卡片顺序会按排序结果渲染

点击条目弹窗

画廊视图区块默认注册了条目点击事件。

事件名：

• itemClick

当前内置流程：

• popupSettings

默认行为：

• 点击条目时，通过 openView 打开当前记录的详情弹窗

展示效果：

• 用户点击卡片后，可以直接查看该记录的详情

注意：

• 弹窗打开时会根据当前记录主键生成 filterByTk
• 默认关闭了路由跳转式导航，目的是保证再次点击时仍能正确触发弹窗流程

注意事项

• 封面字段 默认支持附件类字段接口，其他字段接口需要额外注册

// client/plugin.tsx，multipleEntryModesAttachment 为想要注册的类型
const galleryViewPlugin = this.app.pm.get<any>('@youchaoyun/plugin-gallery-view');
galleryViewPlugin?.registerGalleryCoverFieldInterfaces?.(['multipleEntryModesAttachment']);

• 当封面字段来自关联字段时，插件会自动追加资源查询字段并刷新资源
• 显示数量 是参考值，紧凑布局下会被自动调整
• 当区块高度或宽度较小时，插件会自动隐藏部分描述信息
• 轮播间隔 设置为 0 时不会自动轮播
• 如果区块尚未配置数据源，配置态下会使用内置假数据进行预览
• 已配置数据源但没有记录时，会显示 暂无数据
• 记录存在但没有图片时，会显示占位图

使用建议

• 以视觉展示为主时，优先使用封面流 Effect cover flow
• 需要主图与缩略图联动时，优先使用缩略图 Thumbs
• 页面区域较高、记录较多时，优先使用纵向 Vertical
• 封面图建议使用比例相近、质量较高的图片
• 标题字段 建议使用简短文本，避免标题过长影响布局
• 简介字段 建议使用摘要型内容，避免小尺寸场景下信息过密