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.jpegs_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.jpegs_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.jpegs_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绑定数据显示模式thumbModethumbMode决定图片在缩略图容器中的填充方式可选值及效果如下取值效果w-full宽度占满高度自适应h-full高度占满宽度自适应contain完整包含在容器内默认值保持比例不裁切cover覆盖整个容器必要时裁切边缘{ type: form, mode: horizontal, data: { image: https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpegs_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 类名方便通过样式进一步微调。显示比例thumbRatiothumbRatio用于固定缩略图容器的宽高比可选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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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缺省时会自动回退为srcoriginalSrc: 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.jpegs_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.jpegs_0,w_400,l_1,f_jpg,q_80 } }从源码看width/height会被透传到缩略图容器与图片元素的内联styleImage.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.jpegs_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.jpegs_0,w_216,l_1,f_jpg,q_80 }, { id: 2, image: https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpegs_0,w_216,l_1,f_jpg,q_80 }, { id: 3, image: https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpegs_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.jpegs_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.jpegs_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.jpegs_0,w_216,l_1,f_jpg,q_80, enlargeAble: true, showToolbar: true } }自定义工具栏ImageActiontoolbarActions属性可以自定义工具栏的展示方式与可用操作其类型为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 事件处理在不配置工具栏时这些基础浏览能力同样可用。ImageActioninterface ImageAction { /* 操作key */ key: rotateRight | rotateLeft | zoomIn | zoomOut | scaleOrigin; /* 动作名称 */ label?: string; /* 动作icon */ icon?: string; /* 动作自定义CSS类 */ iconClassName?: string; /* 动作是否禁用 */ disabled?: boolean; }属性表属性名类型默认值说明版本typestring如果在 Table、Card 和 List 中为image在 Form 中用作静态展示为static-imageclassNamestring外层 CSS 类名innerClassNamestring组件内层 CSS 类名imageClassNamestring图片 CSS 类名thumbClassNamestring图片缩率图 CSS 类名heightstring图片缩率高度widthstring图片缩率宽度titlestring标题imageCaptionstring描述placeholderstring占位文本defaultImagestring无数据时显示的图片srcstring缩略图地址href模板外部链接地址originalSrcstring原图地址enlargeAbleboolean支持放大预览enlargeTitlestring放大预览的标题enlargeCaptionstring放大预览的描述enlargeWithGallarystringtrue在表格中图片的放大功能会默认展示所有图片信息设置为false将关闭放大模式下图片集列表的展示thumbModestringcontain预览图模式可选w-full,h-full,contain,coverthumbRatiostring1:1预览图比例可选1:1,4:3,16:9imageModestringthumb图片展示模式可选thumb,original即缩略图模式 或者 原图模式showToolbarbooleanfalse放大模式下是否展示图片的工具栏2.2.0toolbarActionsImageAction[]图片工具栏支持旋转缩放默认操作全部开启2.2.0maxScalenumber或 模板执行调整图片比例动作时的最大百分比3.4.4minScalenumber或 模板执行调整图片比例动作时的最小百分比3.4.4补充说明几个实现细节defaultImage未配置时组件会使用内置的 SVG 占位图imagePlaceholder见 Image.tsx 常量定义placeholder则在图片数据为空时直接渲染占位文本。src、href、title、imageCaption、originalSrc等字段在渲染前都会经过filter做模板解析均可绑定上下文数据。事件表当前组件会对外派发以下事件可以通过onEvent来监听这些事件并通过actions来配置执行的动作在actions中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据详细查看事件动作。事件名称事件参数说明click上下文数据点击图片时触发mouseenter上下文数据鼠标移入时触发mouseleave上下文数据鼠标移入时触发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.jpegs_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}来配置具体的参数详细请查看事件动作。动作名称动作配置说明preview-预览图片zoomscale: number或scale:模板定义每次放大或缩小图片的百分比大小正值为放大负值为缩小默认 50调整图片比例将图片等比例放大或缩小这两个动作在渲染器中通过 doAction 分发preview直接复用放大预览逻辑zoom则进入handleSelfAction调整组件的scale缩放状态。preview预览图片可以通过配置originalSrc来指定预览的原图地址。下面的例子为图片指定id: previewImage再由按钮通过actionType: previewcomponentId触发预览{ 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.jpegs_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.jpegs_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
amis Image 图片组件完全指南：JSON 配置实现图片展示、放大预览与自定义交互
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.jpegs_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.jpegs_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.jpegs_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绑定数据显示模式thumbModethumbMode决定图片在缩略图容器中的填充方式可选值及效果如下取值效果w-full宽度占满高度自适应h-full高度占满宽度自适应contain完整包含在容器内默认值保持比例不裁切cover覆盖整个容器必要时裁切边缘{ type: form, mode: horizontal, data: { image: https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpegs_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 类名方便通过样式进一步微调。显示比例thumbRatiothumbRatio用于固定缩略图容器的宽高比可选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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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.jpegs_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缺省时会自动回退为srcoriginalSrc: 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.jpegs_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.jpegs_0,w_400,l_1,f_jpg,q_80 } }从源码看width/height会被透传到缩略图容器与图片元素的内联styleImage.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.jpegs_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.jpegs_0,w_216,l_1,f_jpg,q_80 }, { id: 2, image: https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpegs_0,w_216,l_1,f_jpg,q_80 }, { id: 3, image: https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpegs_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.jpegs_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.jpegs_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.jpegs_0,w_216,l_1,f_jpg,q_80, enlargeAble: true, showToolbar: true } }自定义工具栏ImageActiontoolbarActions属性可以自定义工具栏的展示方式与可用操作其类型为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 事件处理在不配置工具栏时这些基础浏览能力同样可用。ImageActioninterface ImageAction { /* 操作key */ key: rotateRight | rotateLeft | zoomIn | zoomOut | scaleOrigin; /* 动作名称 */ label?: string; /* 动作icon */ icon?: string; /* 动作自定义CSS类 */ iconClassName?: string; /* 动作是否禁用 */ disabled?: boolean; }属性表属性名类型默认值说明版本typestring如果在 Table、Card 和 List 中为image在 Form 中用作静态展示为static-imageclassNamestring外层 CSS 类名innerClassNamestring组件内层 CSS 类名imageClassNamestring图片 CSS 类名thumbClassNamestring图片缩率图 CSS 类名heightstring图片缩率高度widthstring图片缩率宽度titlestring标题imageCaptionstring描述placeholderstring占位文本defaultImagestring无数据时显示的图片srcstring缩略图地址href模板外部链接地址originalSrcstring原图地址enlargeAbleboolean支持放大预览enlargeTitlestring放大预览的标题enlargeCaptionstring放大预览的描述enlargeWithGallarystringtrue在表格中图片的放大功能会默认展示所有图片信息设置为false将关闭放大模式下图片集列表的展示thumbModestringcontain预览图模式可选w-full,h-full,contain,coverthumbRatiostring1:1预览图比例可选1:1,4:3,16:9imageModestringthumb图片展示模式可选thumb,original即缩略图模式 或者 原图模式showToolbarbooleanfalse放大模式下是否展示图片的工具栏2.2.0toolbarActionsImageAction[]图片工具栏支持旋转缩放默认操作全部开启2.2.0maxScalenumber或 模板执行调整图片比例动作时的最大百分比3.4.4minScalenumber或 模板执行调整图片比例动作时的最小百分比3.4.4补充说明几个实现细节defaultImage未配置时组件会使用内置的 SVG 占位图imagePlaceholder见 Image.tsx 常量定义placeholder则在图片数据为空时直接渲染占位文本。src、href、title、imageCaption、originalSrc等字段在渲染前都会经过filter做模板解析均可绑定上下文数据。事件表当前组件会对外派发以下事件可以通过onEvent来监听这些事件并通过actions来配置执行的动作在actions中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据详细查看事件动作。事件名称事件参数说明click上下文数据点击图片时触发mouseenter上下文数据鼠标移入时触发mouseleave上下文数据鼠标移入时触发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.jpegs_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}来配置具体的参数详细请查看事件动作。动作名称动作配置说明preview-预览图片zoomscale: number或scale:模板定义每次放大或缩小图片的百分比大小正值为放大负值为缩小默认 50调整图片比例将图片等比例放大或缩小这两个动作在渲染器中通过 doAction 分发preview直接复用放大预览逻辑zoom则进入handleSelfAction调整组件的scale缩放状态。preview预览图片可以通过配置originalSrc来指定预览的原图地址。下面的例子为图片指定id: previewImage再由按钮通过actionType: previewcomponentId触发预览{ 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.jpegs_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.jpegs_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
