示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载导读uni.previewImage是 uni-app x 中用于全屏预览图片的核心 API它支持多图列表、指示器、循环预览、长按菜单等能力覆盖 Web、微信小程序、Android、iOS 与 HarmonyOS 五大平台uni.closePreviewImage则用于编程式关闭预览。本文以 docs/api/preview-image.md 官方文档为骨架结合本仓库中 示例页面、自动化测试用例 以及 uni-previewImage 开源模块 的源码实现完整讲解两个 API 的参数语义、错误码、完整可运行示例、底层实现原理与自定义 UI 方案读完即可在项目中落地一套带指示器、循环与长按菜单的跨端图片预览功能。一、API 总览与平台兼容性uni.previewImage(options)用于在新窗口中预览图片支持单张与多张预览。调用后会在当前页面之上打开一个全屏预览层用户可通过左右滑动切换图片。各平台支持情况如下数字为支持的 HBuilderX 版本号x表示当前不支持| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.9 | 4.11 | 4.61 |uni.closePreviewImage(options)用于主动关闭正在展示的图片预览。注意微信小程序平台不支持该 API在微信小程序中用户只能通过手势关闭预览| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | x | 3.9 | 4.11 | 4.61 |二、uni.previewImage 参数详解uni.previewImage接受一个PreviewImageOptions对象参数其属性如下| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | current | any | 否 | - | current 为当前显示图片的链接/索引值不填或填写的值无效则为 urls 的第一张。APP 平台仅支持索引值。 | | urls | Arraystring.ImageURIString | 是 | - | 需要预览的图片链接列表 | | showmenu | boolean | 否 | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: 4.61 | 是否显示长按菜单 | | indicator | string | 否 | Web: x; Android: 3.9; iOS: 4.11; HarmonyOS: x | 图片指示器样式 | | loop | boolean | 否 | Web: x; Android: 3.9; iOS: 4.11; HarmonyOS: x | 是否可循环预览 | | longPressActions | LongPressActionsOptions | 否 | Web: x; 微信小程序: 4.41; Android: 4.51; iOS: 4.71; HarmonyOS: x | 长按图片显示操作菜单 | | success | (callback: PreviewImageSuccess) void | 否 | - | 接口调用成功的回调函数 | | fail | (callback: PreviewImageFail) void | 否 | - | 接口调用失败的回调函数 | | complete | (callback: any) void | 否 | - | 接口调用结束的回调函数调用成功、失败都会执行 | | referrerPolicy | string | 否 | 微信小程序: 4.41 | 需要基础库2.13.0origin表示发送完整 referrerno-referrer表示不发送 |关键参数使用要点urls 为必填项。源码中__previewImage在option.urls.length 0时直接构造错误码1001并触发fail与complete回调见 PreviewImage.uts因此传入至少一张图片地址是硬性约束。current 的取值语义分平台Web/小程序可用图片链接字符串定位当前图APP 平台只接受数字索引值。若索引越界或无效会回退到第一张——开源实现中对该逻辑有显式处理见 previewImage.uvue。referrerPolicy 仅微信小程序支持用于控制预览网络图片时是否携带来源信息需基础库 2.13.0 及以上。indicator 指示器属性indicator控制预览时图片指示器的样式合法值如下| 合法值 | 描述 | | :- | :- | | default | 底部圆点指示器 | | number | 顶部数字指示器 | | none | 不显示指示器 |从实现源码看数字指示器渲染为当前页 1 / 总页数的文本如1 / 3圆点指示器按 urls 长度渲染圆点序列并高亮当前项两个指示器均通过v-if条件挂载见 previewImage.uvue。loop 循环预览loop为true时浏览到最后一张可继续循环回到第一张。仓库示例页面在注意事项中明确指出Web 平台不支持 loop 属性且 Web 平台同样不支持 indicator见 preview-image.uvue跨端开发时需用条件编译做降级处理。longPressActions 长按操作菜单longPressActions允许自定义长按图片时弹出的操作菜单其属性如下| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | itemList | Arraystring | 是 | 按钮的文字数组 | | itemColor | string | 否 | 按钮的文字颜色字符串格式默认为 #000000 | | success | (result: LongPressActionsSuccessResult) void | 否 | 接口调用成功的回调函数 | | fail | (result: LongPressActionsFailResult) void | 否 | 接口调用失败的回调函数 | | complete | (result: any) void | 否 | 接口调用结束的回调函数调用成功、失败都会执行 |未传longPressActions时长按默认行为是保存图片到相册传入后则由自定义菜单接管。这一点在开源模块的 readme.md 注释中有明确说明。LongPressActionsSuccessResult 属性| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | tapIndex | number | 是 | 用户点击的菜单按钮索引 | | index | number | 是 | 当前预览的图片索引 |LongPressActionsFailResult 属性| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 错误码 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误 | | errMsg | string | 是 | 错误描述 |在源码层面长按回调通过事件总线传递预览页长按图片后向__UNIPREVIEWLONGPRESS事件写入typesuccess或fail、tapIndex、index__previewImage监听该事件并分发到对应回调菜单被关闭视为用户取消构造错误码1101001触发fail见 PreviewImage.uts。success / fail / complete 回调success预览成功打开后触发回调参数PreviewImageSuccess仅含errSubject调用 API 的名称与errMsg描述信息。fail调用失败时触发参数为PreviewImageFail结构与LongPressActionsFailResult一致。complete无论成功或失败都会触发。在 PreviewImage.uts 中可以看到success与complete是在uni.openDialogPage的success回调里同步触发的即预览层成功打开即视为调用成功。errCode 错误码说明previewImage与closePreviewImage的失败回调共用以下错误码| 合法值 | 描述 | | :- | :- | | 1001 | urls 至少包含一张图片地址 | | 1101001 | 用户取消 | | 1101003 | 文件不存在 | | 1101004 | 图片加载失败 | | 1101005 | 未获取权限 | | 1101010 | 其他错误 |这些错误码在开源模块中以联合类型PreviewImageErrorCode形式声明见 interface.uts开发者在fail回调中可按errCode区分失败原因并给出针对性提示。三、完整可运行示例仓库中的官方示例页面 src/pages/API/preview-image/preview-image.uvue 演示了指示器切换、循环开关、长按行为配置与本地相册追加图片的完整用法基于script setup languts编写可直接在 HBuilderX 中运行到各端调试。页面模板关键片段view classcell-ct stylemargin: 8px; view classcell cell-choose-image v-for(image, index) in imageList :keyindex text stylewidth: 100px; height: 100px;background-color: lightgray; color: red; text-align: center; line-height: 100px;font-size: 14px; v-ifimage.error clickpreviewImage(index)图片路径非法/text image stylewidth: 100px; height: 100px;background-color: white; modeaspectFit :srcimage.src v-if!image.error clickpreviewImage(index) erroronImageLoadError(index,$event as ImageErrorEvent) /image /view image classcell cell-choose-image src/static/plus.png clickchooseImage /image /view模板中每张缩略图都绑定了点击事件图片加载失败时error会替换为图片路径非法占位并保留点击预览能力加号按钮用于从相册追加图片。脚本逻辑核心片段const previewImage (index : number) { let list [] as Arraystring imageList.value.forEach((item : ImageType) { list.push(item.src) }) uni.previewImage({ urls: list, current: index, indicator: currentIndicator.value, loop: isLoop.value, longPressActions: (isLongPress.value ? ({ itemList: [按钮1, 按钮2, 按钮3], itemColor: #ccc, success: (e : LongPressActionsSuccessResult) { uni.showToast({ title: 用户选中了第 (e.index 1) 张图片并选中了第 (e.tapIndex 1) 个选项, position: bottom }) }, fail: (e : LongPressActionsFailResult) { uni.showToast({ title: 用户关闭了action sheet, position: bottom }) } } as LongPressActionsOptions) : null) }) }示例要点图片列表来自本地静态资源与网络图片混合并通过uni.chooseImage动态追加相册图片sourceType: [album]见 preview-image.uvue。indicator提供default圆点、number数字、none不显示三种可切换样式。长按菜单使用longPressActions自定义三个按钮success回调中同时用到index第几张图与tapIndex第几个选项。页面通过defineExpose暴露previewImage、closePreviewImage、testSetCurrentIndicator方法供自动化测试驱动见 preview-image.uvue。关闭预览const closePreviewImage (){ uni.closePreviewImage({}) }四、uni.closePreviewImage 参数与回调closePreviewImage接受ClosePreviewImageOptions仅包含三个标准回调| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | success | (callback: ClosePreviewImageSuccess) void | 否 | 微信小程序: x | 接口调用成功的回调函数 | | fail | (callback: ClosePreviewImageFail) void | 否 | 微信小程序: x | 接口调用失败的回调函数 | | complete | (callback: any) void | 否 | 微信小程序: x | 接口调用结束的回调函数调用成功、失败都会执行 |ClosePreviewImageSuccess仅含errMsg错误信息。ClosePreviewImageFail结构与PreviewImageFail一致包含errCode、errSubject、data、cause、errMsg错误码语义与上一节 errCode 表相同。从开源实现看__closePreviewImage通过向__CLOSEPREVIEWIMAGE事件广播关闭指令随后立即构造errMsg: ok的ClosePreviewImageSuccess并触发success与complete见 PreviewImage.uts。五、底层实现原理从源码看预览层是如何工作的uni-app x 的图片预览在 APP 端基于dialogPage对话框页面机制实现。开源模块 PreviewImage.uts 完整呈现了调用链参数校验urls为空时立即以错误码1001结束调用。注册监听通过uni.$once(__onPreviewLoad, ...)等待预览页就绪再通过uni.$emit(__onPreviewLoadCallback, object)把current、urls、indicator、loop、longPressActions传给预览页。打开预览页uni.openDialogPage({ url: /uni_modules/uni-previewImage/pages/previewImage/previewImage, animationType: fade-in })在栈顶打开全屏预览页。长按菜单通信预览页通过__UNIPREVIEWLONGPRESS事件把菜单点击结果回传由入口函数分发到success/fail/complete。关闭uni.closePreviewImage广播__CLOSEPREVIEWIMAGE事件预览页监听后调用uni.closeDialogPage并配合fade-out动画关闭鸿蒙端因不支持animationType先通过样式设置过渡动画再关闭见 previewImage.uvue。预览页本体是一个基于swiper的全屏组件支持swiperCurrent、circular循环、indicator-dots等能力并区分了 VUE3-VAPOR 与非 VAPOR 两套渲染路径见 previewImage.uvue。此外该开源模块依赖uni-media、uni-network、uni-fileSystemManager三个模块使用原生 SDK 时需要将对应模块配置加入原生项目依赖详见 readme.md。六、开源自定义定制预览界面 UI内置uni.previewImage弹出的界面无法充分自定义。若需要完全控制预览 UI如自定义工具栏、收藏按钮、分享入口等uni-app x 提供了开源的 previewImage 页面实现即本仓库中的 uni-previewImage 模块。将该模块作为 ext api 插件下载到项目uni_modules目录下会覆盖uni.previewImage的默认实现。覆盖后的行为差异需要特别注意调用uni.previewImage会在栈顶页面打开一个 dialogPage该 dialogPage 可以在父页面的getDialogPages中获取到而使用内置实现时是看不到这个 dialogPage 的。这意味着开发者可以直接修改 pages/previewImage/previewImage.uvue 与 uni-previewImageItem 中的模板与样式重塑预览界面通过getDialogPages拿到预览页实例实现页面级联动控制在模块内新增业务逻辑例如批量操作、下载原图、图片信息展示等。七、自动化测试验证本仓库为 preview-image 编写了两组自动化测试可作为功能验收与回归依据preview-image.test.js驱动示例页面分别以default、number、none三种指示器打开预览并截图比对快照Web/小程序端则仅做整页截图。preview-image-multi.test.js通过 preview-image-multi.uvue 页面覆盖1 张、3 张、20 张三种图片数量与number/default/none三种指示器的组合场景每次调用后截图断言并调用testClosePreviewImage关闭。这些用例实测了多图数量边界20 张与指示器全组合验证了 API 在 APP 端的稳定性。八、最佳实践与注意事项urls 必须至少包含一张图片否则必然触发错误码1001调用前建议先做非空校验并给出降级提示。区分平台能力indicator与loop在 Web 不可用、current在 APP 仅支持索引跨端代码请配合#ifdef WEB等条件编译处理。长按菜单的默认行为是保存图片若业务上禁止下载如版权图务必显式传入longPressActions自定义菜单或以showmenu: false微信小程序/HarmonyOS关闭长按菜单。关闭预览在 APP 端可随时调用uni.closePreviewImage编程式关闭如返回键拦截、业务倒计时结束等场景微信小程序端不支持该 API。需要深度定制 UI时引入开源uni-previewImage模块替换内置实现同时注意它会以 dialogPage 形式出现在getDialogPages中页面栈操作需相应调整。错误处理在fail回调中按errCode区分用户取消1101001文件不存在1101003图片加载失败1101004等场景分别给出合理的用户提示避免一刀切的报错文案。参见官方文档docs/api/preview-image.md示例页面src/pages/API/preview-image/preview-image.uvue、src/pages/API/preview-image/preview-image-multi.uvue开源实现模块src/uni_modules/uni-previewImage/readme.md、utssdk/PreviewImage.uts、utssdk/interface.uts、pages/previewImage/previewImage.uvue自动化测试preview-image.test.js、preview-image-multi.test.js关联类型ImageURIString、统一错误规范赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app x 图片预览插件 uni-previewImage 完全指南API 详解、源码剖析与 UTS 插件实践uni app x 图片预览插件 uni previewImage 完全指南API 详解、源码剖析与 UTS 插件实践 uni previewImage 是示例工程前端移动开发跨平台uni-app x uni-previewImage 图片预览插件API 参数、源码原理与实战接入指南uni app x uni previewImage 图片预览插件API 参数、源码原理与实战接入指南 uni previewImage 是 uni app示例工程前端移动开发跨平台uni-app x 图片信息获取实战uni.getImageInfo API 详解与多端实现原理uni app x 图片信息获取实战uni.getImageInfo API 详解与多端实现原理 uni.getImageInfo 是 uni app x 中示例工程前端移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考