企业官网建设流程全解析

amis Image 图片组件完全指南：JSON 配置实现图片展示、放大预览与自定义交互

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis

本指南以 amis 前端低代码框架中的 Image（图片）组件为对象，系统讲解如何通过 JSON Schema 完成图片的缩略图展示、标题说明、尺寸比例控制、点击放大预览、外部链接跳转、自定义点击动作以及事件动作联动。读完本文，你将能够在 Page、Table、List、Card 与 Form 等容器中灵活组合图片组件，并利用onEvent、preview、zoom等能力实现完整的图片交互方案。

基本使用：最简单的图片渲染

Image 组件在 amis 中的核心职责是通过src字段渲染一张图片。最基础的用法是直接在页面 body 中声明一个type: "image"节点，并给定图片地址：

{ "type": "page", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" } }

这里src支持普通的静态 URL，也支持 amis 的模板语法。除了直接写死地址，更常见的做法是配置name属性，将图片地址与上下文数据中的变量关联起来，页面数据变化时图片会自动更新：

{ "type": "page", "data": { "imageUrl": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, "body": { "type": "image", "name": "imageUrl" } }

从 组件实现 的源码可以看到，组件渲染时会对src和name做统一处理：src经过filter(src, data, '| raw')完成模板解析，name则通过getPropValue从上下文取值，二者取其一作为最终图片地址value。这意味着你可以直接在src中书写"${xxx}"模板，也可以借助name引用数据域字段，两种方式可互相替代。

配置标题和说明

通过title与imageCaption可以为图片附加文字信息。title显示为图片下方的标题，imageCaption显示为描述文字，两者均支持模板语法，可绑定上下文数据：

{ "type": "page", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "title": "这是标题", "imageCaption": "这是一段说明" } }

在渲染实现（Image.tsx 中 ImageThumb）中，只有title或caption至少存在一个时，组件才会渲染.Image-info信息区块；title会同步作为<img>的原生title属性，方便鼠标悬停时显示完整文案。

配置缩略图

Image 组件默认以缩略图模式展示，通过thumbMode（显示模式）与thumbRatio（显示比例）可以精确控制缩略图的裁切与占位方式。它们常用于表单的static-image静态展示中，配合name绑定数据：

显示模式（thumbMode）

thumbMode决定图片在缩略图容器中的填充方式，可选值及效果如下：

{ "type": "form", "mode": "horizontal", "data": { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, "body": [ { "type": "static-image", "name": "image", "label": "宽度占满", "thumbMode": "w-full" }, { "type": "static-image", "name": "image", "label": "高度占满", "thumbMode": "h-full" }, { "type": "static-image", "name": "image", "label": "默认", "thumbMode": "contain" }, { "type": "static-image", "name": "image", "label": "覆盖", "thumbMode": "cover" } ] }

源码层面，ImageField 的默认属性 将thumbMode的默认值定义为contain，并在缩略图容器上生成Image-thumb--w-full这类语义化 CSS 类名，方便通过样式进一步微调。

显示比例（thumbRatio）

thumbRatio用于固定缩略图容器的宽高比，可选'1:1'、'4:3'、'16:9'，默认1:1。通常与thumbMode: "cover"搭配使用，让图片以统一的构图展示：

{ "type": "form", "mode": "horizontal", "data": { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, "body": [ { "type": "static-image", "name": "image", "label": "1比1", "thumbRatio": "1:1", "thumbMode": "cover" }, { "type": "static-image", "name": "image", "label": "4比3", "thumbRatio": "4:3", "thumbMode": "cover" }, { "type": "static-image", "name": "image", "label": "16比9", "thumbRatio": "16:9", "thumbMode": "cover" } ] }

注意：thumbMode、thumbRatio只在缩略图模式（imageMode未设置为original）下生效。比例通过Image-thumb--1-1这样的类名挂载到容器上，实际显示尺寸还会受width/height影响。

放大功能：点击查看大图

开启放大与图片集

为图片配置"enlargeAble": true后，鼠标移动到图片上会显示一个可点击的放大图标，点击即可在全屏弹层中预览图片：

{ "type": "page", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "enlargeAble": true } }

在 Table / CRUD 这类列表容器中，图片组件的放大模式默认会收集所有行的图片信息，在预览弹层底部以图片集（Gallery）形式展示，便于逐张浏览。这一行为由enlargeWithGallary控制，默认值为true，显式设置"enlargeWithGallary": true效果相同：

{ "type": "page", "data": { "imageList": [ { "name": "amis", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "name": "amis", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692942/d8e4992057f9.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "name": "tom", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395693148/1314a2a3d3f6.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "name": "jack", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395693379/8f2e79f82be0.jpeg@s_0,w_216,l_1,f_jpg,q_80" } ] }, "body": { "type": "crud", "source": "${imageList}", "syncLocation": false, "columns": [ { "name": "name", "label": "名称" }, { "type": "image", "name": "image_url", "label": "图片", "enlargeAble": true } ] } }

如果希望放大时只预览当前图片、不展示图片集列表，将enlargeWithGallary显式设置为false即可：

{ "type": "page", "data": { "imageList": [ { "name": "amis", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "name": "amis", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692942/d8e4992057f9.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "name": "tom", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395693148/1314a2a3d3f6.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "name": "jack", "image_url": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395693379/8f2e79f82be0.jpeg@s_0,w_216,l_1,f_jpg,q_80" } ] }, "body": { "type": "crud", "source": "${imageList}", "syncLocation": false, "columns": [ { "name": "name", "label": "名称" }, { "type": "image", "name": "image_url", "label": "图片", "enlargeAble": true, "enlargeWithGallary": false } ] } }

指定原图地址

缩略图地址（src）往往经过 CDN 压缩处理，放大预览时应使用更高清的原图。通过originalSrc可以单独指定原图地址，作为放大弹层中的预览来源：

{ "type": "page", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "originalSrc": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg", "enlargeAble": true } }

在 ImageField.handleEnlarge 的实现中，originalSrc缺省时会自动回退为src（originalSrc: originalSrc || src），也就是说不配置原图地址也不会报错，放大时直接使用缩略图。

放大预览的标题与描述

enlargeTitle与enlargeCaption用于配置放大预览弹层中的标题和描述文字，它们会覆盖图片本身的title/imageCaption（见 handleEnlarge 中的优先级处理）：

{ "type": "page", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "originalSrc": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg", "enlargeAble": true, "enlargeTitle": "这是一个标题", "enlargeCaption": "这是一段描述" } }

设置图片高宽

通过width与height可以直接约束图片的显示尺寸，单位为 CSS 长度值：

{ "type": "page", "body": { "type": "image", "width": "200px", "height": "200px", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_400,l_1,f_jpg,q_80" } }

从源码看，width/height会被透传到缩略图容器与图片元素的内联style（Image.tsx 缩略图容器样式绑定），因此也支持%、rem等任意合法 CSS 值。

原图模式

1.2.3 及以上版本

默认情况下 Image 以缩略图模式渲染。通过imageMode: "original"可以切换为原图模式，该模式以块状展示原始图片，宽度尽可能占满父容器，适合直接展示原尺寸大图的场景：

{ "type": "page", "data": { "imageUrl": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg" }, "body": { "type": "image", "imageMode": "original", "name": "imageUrl", "title": "这是标题", "imageCaption": "这是一段说明" } }

imageMode的取值在 schema 类型中定义为'thumb' | 'original'（见 AMISImageSchema 定义），默认thumb。渲染时组件会依据该值选择.Image--thumb或.Image--original两套 DOM 结构，原图模式下thumbMode仍然可配置，用于控制图片在块容器内的裁切方式。

打开外部链接

1.3.3 及以上版本

配置href后，点击图片会跳转到外部链接。需要注意：href与放大功能是冲突的，二者只能二选一——设置了href后点击行为由链接接管，放大图标将不再展示：

{ "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "href": "https://github.com/baidu/amis" }

href本身是模板类型，因此可以直接绑定数据域中的变量，实现“不同数据行跳转不同链接”的需求：

{ "type": "page", "data": { "imageUrl": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg", "imageHref": "https://github.com/baidu/amis" }, "body": { "type": "image", "name": "imageUrl", "href": "${imageHref}" } }

源码中（ImageThumb 的链接渲染），当href存在时组件会整体包一层<a>，默认target="_blank"新窗口打开；schema 还提供了blank与htmlTarget两个底层属性来进一步控制target值。

用作 Field 时

Image 组件具备“字段”能力：当它被用在 Table 的列（Column）、List 的内容、Card 卡片的内容以及表单的 Static-XXX 中时，只需设置name属性即可映射同名字段，从当前行的数据中取图。

Table 中的列类型

在表格列中声明type: "image"并绑定name，即可将该列渲染为图片，不同行自动读取各自的图片地址：

{ "type": "table", "data": { "items": [ { "id": "1", "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "id": "2", "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "id": "3", "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" } ] }, "columns": [ { "name": "id", "label": "Id" }, { "name": "image", "label": "图片", "type": "image" } ] }

List 的内容与 Card 卡片的内容配置方式与 Table 列完全一致，这里不再重复。值得一提的是，在 CRUD2 的字段抽取逻辑 中，static-image字段还会被识别为列表的封面图来源，可见 Image 在列表类组件中的特殊地位。

Form 中静态展示

在 Form 表单中，Image 以static-image类型存在，用于详情展示（如只读的资料卡、头像、证件照等）。配合name从表单数据中取值：

{ "type": "form", "data": { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, "body": [ { "type": "static-image", "name": "image", "label": "颜色", "innerClassName": "no-border" } ] }

从 schema 体系看，static-image与image共用同一个AMISImageSchema类型定义（见 SchemaFull.ts 的字段注册），二者共享全部图片能力，只是注册在表单的静态展示上下文中。

自定义点击行为

1.5.0 及以上版本

除了跳转链接，Image 还支持通过clickAction配置任意点击动作——弹窗、抽屉、刷新、发送请求等都可以。它与href不同，clickAction走 amis 的动作系统，由 handleClick 中的 handleAction 统一分发：

{ "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "class": "cursor-pointer", "clickAction": { "actionType": "dialog", "dialog": { "title": "弹框标题", "body": "这是一个弹框" } } }

需要注意，clickAction与href、放大功能同样存在互斥关系，请按实际交互需求选择一种点击语义。

工具栏

2.2.0 及以上版本

放大预览模式下可以开启图片工具栏，对预览图执行旋转、缩放、还原等操作。配置"showToolbar": true即可开启，默认开启全部操作（右旋转、左旋转、放大、缩小、恢复原始比例）：

{ "type": "page", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "enlargeAble": true, "showToolbar": true } }

自定义工具栏（ImageAction）

toolbarActions属性可以自定义工具栏的展示方式与可用操作，其类型为ImageAction[]，完整定义参考本文 ImageAction 小节。该能力基于 amis-ui 的 ImageGallery 组件 实现，操作键由ImageActionKey枚举约束：

enum ImageActionKey { ROTATE_RIGHT = 'rotateRight', // 右旋转 ROTATE_LEFT = 'rotateLeft', // 左旋转 ZOOM_IN = 'zoomIn', // 等比例放大 ZOOM_OUT = 'zoomOut', // 等比例缩小 SCALE_ORIGIN = 'scaleOrigin' // 恢复原图缩放比例 }

从 ImageGallery 默认工具栏 可以看出，五个操作默认全部启用。此外，预览弹层还内置了滚轮缩放与鼠标拖拽平移能力（wheel / mousedown 事件处理），在不配置工具栏时这些基础浏览能力同样可用。

ImageAction

interface ImageAction { /* 操作key */ key: 'rotateRight' | 'rotateLeft' | 'zoomIn' | 'zoomOut' | 'scaleOrigin'; /* 动作名称 */ label?: string; /* 动作icon */ icon?: string; /* 动作自定义CSS类 */ iconClassName?: string; /* 动作是否禁用 */ disabled?: boolean; }

属性表

补充说明几个实现细节：defaultImage未配置时，组件会使用内置的 SVG 占位图imagePlaceholder（见 Image.tsx 常量定义）；placeholder则在图片数据为空时直接渲染占位文本。src、href、title、imageCaption、originalSrc等字段在渲染前都会经过filter做模板解析，均可绑定上下文数据。

事件表

当前组件会对外派发以下事件，可以通过onEvent来监听这些事件，并通过actions来配置执行的动作，在actions中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据，详细查看事件动作。

click / mouseenter / mouseleave

点击图片 / 鼠标移入图片 / 鼠标移出图片，可以尝试通过${event.context.nativeEvent}获取鼠标事件对象。事件在 ImageField 的事件处理器 中派发，dispatchEvent返回的结果若被prevented，则后续的clickAction等默认行为会被取消，这是 amis 事件系统拦截默认动作的标准用法：

{ "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "onEvent": { "click": { "actions": [ { "actionType": "toast", "args": { "msg": "图片被点击了" } } ] }, "mouseenter": { "actions": [ { "actionType": "toast", "args": { "msg": "鼠标移入图片" } } ] }, "mouseleave": { "actions": [ { "actionType": "toast", "args": { "msg": "鼠标移出图片" } } ] } } }

动作表

当前组件对外暴露以下特性动作，其他组件可以通过指定actionType: 动作名称、componentId: 该组件id来触发这些动作，动作配置可以通过args: {动作配置项名称: xxx}来配置具体的参数，详细请查看事件动作。

这两个动作在渲染器中通过 doAction 分发：preview直接复用放大预览逻辑，zoom则进入handleSelfAction调整组件的scale缩放状态。

preview

预览图片，可以通过配置originalSrc来指定预览的原图地址。下面的例子为图片指定id: "previewImage"，再由按钮通过actionType: "preview"+componentId触发预览：

{ "type": "page", "body": { "type": "container", "body": [ { "type": "container", "body": [ { "type": "image", "className": "mb-1", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "originalSrc": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg", "id": "previewImage" } ] }, { "type": "action", "label": "预览图片", "onEvent": { "click": { "actions": [ { "actionType": "preview", "componentId": "previewImage" } ] } } } ] } }

zoom

调整图片比例，将图片等比例放大或缩小。可以通过配置图片的maxScale和minScale来限制调整的比例范围。下面的示例中，图片设置了maxScale: 200、minScale: 20，两个按钮分别以scale: 50放大、scale: -50缩小：

{ "type": "page", "body": { "type": "container", "body": [ { "type": "flex", "items": [ { "type": "image", "innerClassName": "no-border", "className": "mt-5 mb-5", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80", "maxScale": 200, "minScale": 20, "id": "zoomImage" } ] }, { "type": "action", "label": "放大图片", "onEvent": { "click": { "actions": [ { "actionType": "zoom", "args": { "scale": 50, }, "componentId": "zoomImage" } ] } } }, { "type": "action", "label": "缩小图片", "className": "mx-1", "onEvent": { "click": { "actions": [ { "actionType": "zoom", "args": { "scale": -50, }, "componentId": "zoomImage" } ] } } } ] } }

在 handleSelfAction 的实现中可以看到，maxScale/minScale默认值分别为200与50（均为百分比），且支持配置为模板变量后通过resolveVariableAndFilter动态解析。缩放以步进方式计算：每次在现有scale上累加scale / 100，到达上限或下限后即被钳制，最终通过transform: scale()作用于图片容器。

小结

Image 是 amis 中最常用的展示型组件之一：从基础的src渲染、name数据绑定，到thumbMode/thumbRatio的缩略图控制、enlargeAble放大预览与图片集浏览，再到href外链、clickAction自定义点击、showToolbar工具栏旋转缩放，以及通过onEvent与preview/zoom动作实现跨组件联动，覆盖了页面开发中绝大多数图片场景。其完整的属性定义与实现可以在 Image.tsx 与 ImageGallery.tsx 中进一步查阅，本文所有示例均基于当前仓库版本可直接运行的 Schema。

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis