Back to Uni App

Preview Image

docs/api/preview-image.md

2.3.321.5 KB
Original Source
<!-- ## uni.previewImage(options) @previewimage -->

::: sourceCode

uni.previewImage(options) @previewimage

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-media

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-media

:::

预览图片

previewImage 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
4.04.413.94.114.615.0

参数

名称类型必填默认值兼容性描述
optionsPreviewImageOptions-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
currentany-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -current 为当前显示图片的链接/索引值,不填或填写的值无效则为 urls 的第一张。APP平台仅支持索引值。
urlsArray<string.ImageURIString>-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -需要预览的图片链接列表
showmenuboolean-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0是否显示长按菜单
indicator"default" | "number" | "none"-Web: x; 微信小程序: -; Android: 3.9; iOS: 4.11; HarmonyOS: x图片指示器样式
loopboolean-Web: x; 微信小程序: -; Android: 3.9; iOS: 4.11; HarmonyOS: x是否可循环预览
longPressActionsLongPressActionsOptions-Web: x; 微信小程序: 4.41; Android: 4.51; iOS: 4.71; HarmonyOS: x长按图片显示操作菜单。
success(callback: PreviewImageSuccess) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -接口调用成功的回调函数
fail(callback: PreviewImageFail) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -接口调用失败的回调函数
complete(callback: any) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -接口调用结束的回调函数(调用成功、失败都会执行)
referrerPolicystring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -需要基础库: 2.13.0

origin: 发送完整的referrer; no-referrer: 不发送。格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本; |

longPressActions 的属性描述
名称类型必备默认值兼容性描述
itemListArray<string>-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -按钮的文字数组
itemColorstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -按钮的文字颜色,字符串格式,默认为"#000000"
success(result: LongPressActionsSuccessResult) => void-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -接口调用成功的回调函数
fail(result: LongPressActionsFailResult) => void-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -接口调用失败的回调函数
complete(result: any) => void-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -接口调用结束的回调函数(调用成功、失败都会执行)
LongPressActionsSuccessResult 的属性值 @longpressactionssuccessresult-values
名称类型必备默认值兼容性描述
tapIndexnumber-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -接口调用失败的回调函数
indexnumber-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -接口调用结束的回调函数(调用成功、失败都会执行)
LongPressActionsFailResult 的属性值 @longpressactionsfailresult-values
名称类型必备默认值兼容性描述
errCodenumber-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误码
errSubjectstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -统一错误主题(模块)名称
dataany-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误信息中包含的数据
causeError-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
errMsgstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

errCode 的属性描述

合法值兼容性描述
1001Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -urls至少包含一张图片地址
1101001Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -用户取消
1101003Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -文件不存在
1101004Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -图片加载失败
1101005Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -未获取权限
1101010Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -其他错误

PreviewImageSuccess 的属性值 @previewimagesuccess-values

名称类型必备默认值兼容性描述
errSubjectstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -调用API的名称
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -描述信息

PreviewImageFail 的属性值 @previewimagefail-values

名称类型必备默认值兼容性描述
errCodenumber-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误码
errSubjectstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -统一错误主题(模块)名称
dataany-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误信息中包含的数据
causeError-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
errMsgstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

errCode 的属性描述

合法值兼容性描述
1001Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -urls至少包含一张图片地址
1101001Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -用户取消
1101003Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -文件不存在
1101004Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -图片加载失败
1101005Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -未获取权限
1101010Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -其他错误

示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/preview-image/preview-image

appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/preview-image/preview-image

示例

vue
<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <view style="padding-left: 8px; padding-right: 8px">
      <view>
        <text class="text-desc">图片指示器样式</text>
        <radio-group class="cell-ct" style="background-color: white" @change="onIndicatorChanged">
          <view class="indicator-it" v-for="(item, index) in indicator" :key="item.value">
            <radio :disabled="isWeb" :checked="index == 0" :value="item.value">{{
              item.name
            }}</radio>
          </view>
        </radio-group>
      </view>
      <view>
        <checkbox-group @change="onCheckboxChange" style="margin-top: 16px; margin-left: 8px">
          <checkbox :disabled="isWeb" :checked="isLoop" style="margin-right: 15px">循环播放</checkbox>
        </checkbox-group>
      </view>
      <view>
        <text class="text-desc">长按行为</text>
        <radio-group class="cell-ct" style="background-color: white; margin-bottom: 16px;" @change="onLongPressCheckboxChange">
          <view class="indicator-it" v-for="(item, index) in longPressAction" :key="item.value">
            <radio :disabled="isWeb" :checked="index == 1" :value="item.value">{{
              item.name
            }}</radio>
          </view>
        </radio-group>
      </view>
      <view style="background-color: white">
        <text class="text-desc">点击图片开始预览</text>
        <view class="cell-ct" style="margin: 8px;">
          <view class="cell cell-choose-image" v-for="(image, index) in imageList" :key="index">
            <text style="width: 100px; height: 100px;background-color: lightgray; color: red; text-align: center; line-height: 100px;font-size: 14px;" v-if="image.error"
              @click="previewImage(index)">图片路径非法</text>
            <image style="width: 100px; height: 100px;background-color: white;" mode="aspectFit" :src="image.src"
              v-if="!image.error" @click="previewImage(index)"
              @error="onImageLoadError(index,$event as ImageErrorEvent)">
            </image>
          </view>
          <image class="cell cell-choose-image" src="/static/plus.png" @click="chooseImage">
          </image>
        </view>
      </view>
      <view style="margin:8px;">
        <text style="color: black;font-size: 18px;margin-bottom: 4px;">注意事项:</text>
        <text style="font-size: 17px;margin-left: 4px;color: darkgray;">1、indicator属性仅App平台支持。</text>
        <text style="font-size: 17px;margin-left: 4px;color: darkgray;">2、Web平台不支持loop属性。</text>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script setup lang="uts">
  type Indicator = "number" | "default" | "none"
  type ItemType = {
    value : Indicator,
    name : string
  }

  type ImageType = {
    src : string,
    error : boolean
  }

  type LongPressType = {
    value : string,
    name : string
  }

  const imageList = ref([
    { src: "https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/[email protected]", error: false },
    { src: "/static/test-image/logo.png", error: false },
    { src: "/static/test-image/logo.svg", error: false },
    // #ifdef APP
    { src: "/static/uni2.png", error: false },
    // #endif
  ] as ImageType[])

  const indicator = ref([{
    value: "default",
    name: "圆点"
  }, {
    value: "number",
    name: "数字"
  }, {
    value: "none",
    name: "不显示"
  }] as ItemType[])

  const longPressAction = ref([{
    value: "0",
    name: "默认长按行为"
  }, {
    value: "1",
    name: "自定义长按行为"
  }] as LongPressType[])

  const currentIndicator = ref("default"  as Indicator)

  // #ifdef WEB
  const isWeb = ref(true)
  // #endif
  // #ifndef WEB
  const isWeb = ref(false)
  // #endif

  // #ifdef APP-IOS
  const isIOS = ref(true)
  // #endif
  // #ifndef APP-IOS
  const isIOS = ref(false)
  // #endif

  const isLongPress = ref(true)
  const isLoop = ref(true)

  const previewImage = (index : number) => {
    let list = [] as Array<string>
    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)
    })
  }

  const chooseImage = () => {
    uni.chooseImage({
      sourceType: ['album'],
      count: 1,
      success: (e) => {
        imageList.value = imageList.value.concat({ src: e.tempFilePaths[0], error: false } as ImageType)
        // imageList.value = imageList.value.concat(e.tempFilePaths)
      },
      fail(_) {
      }
    })
  }

  const onIndicatorChanged = (e : UniRadioGroupChangeEvent) => {
    currentIndicator.value = e.detail.value as Indicator
  }

  const onCheckboxChange = (_ : UniCheckboxGroupChangeEvent) => {
    isLoop.value = !isLoop.value
  }

  const onLongPressCheckboxChange = (e: UniRadioGroupChangeEvent) => {
    isLongPress.value = (e.detail.value == "1")
  }

  const onImageLoadError = (index : number, error : UniImageErrorEvent) => {
    imageList.value[index].error = true
  }

  const closePreviewImage = ()=>{
    uni.closePreviewImage({})
  }

  const testSetCurrentIndicator = (value:string) =>{
    currentIndicator.value = value as Indicator
  }

  defineExpose({
  	testSetCurrentIndicator,
    previewImage,
    closePreviewImage
  })
</script>

<style>
  .text-desc {
    margin-top: 16px;
    margin-left: 8px;
    margin-bottom: 16px;
    font-weight: bold;
  }

  .cell-ct {
    display: flex;
    flex-wrap: wrap;
    flex-direction: row;
  }

  .cell {
    margin-left: 3px;
    margin-right: 3px;
    width: 100px;
    height: 100px;
  }

  .cell-choose-image {
    border-width: 1px;
    border-style: solid;
    border-color: lightgray;
  }

  .indicator-it {
    margin: 8px;
  }
  .cell-pd {
    padding: 11px 0px;
  }
</style>

:::

参见

开源自定义@custom

内置的previewImage弹出的界面,无法充分自定义。所以uni-app x提供了开源的previewImage页面,开发者可以自己定义UI。

开源插件地址:https://ext.dcloud.net.cn/plugin?id=21314

这个插件是ext api,下载到项目下会覆盖uni.previewImage的实现。

单独下载开源插件后,调用uni.previewImage,会在栈顶页面打开一个dialogPage,在父页面的getDialogPages中可以看到。使用内置的uni.previewImage看不到。

该开源插件目前仅支持Android。后续会补充其他平台。

<!-- ## uni.closePreviewImage(options) @closepreviewimage -->

::: sourceCode

uni.closePreviewImage(options) @closepreviewimage

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-media

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-media

:::

关闭图片预览

closePreviewImage 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
4.0<a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a>3.94.114.615.0

参数

名称类型必填默认值兼容性描述
optionsClosePreviewImageOptions-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
success(callback: ClosePreviewImageSuccess) => void-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -接口调用成功的回调函数
fail(callback: ClosePreviewImageFail) => void-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -接口调用失败的回调函数
complete(callback: any) => void-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -接口调用结束的回调函数(调用成功、失败都会执行)

ClosePreviewImageSuccess 的属性值 @closepreviewimagesuccess-values

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -错误信息

ClosePreviewImageFail 的属性值 @closepreviewimagefail-values

名称类型必备默认值兼容性描述
errCodenumber-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -错误码
errSubjectstring-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -统一错误主题(模块)名称
dataany-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -错误信息中包含的数据
causeError-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
errMsgstring-Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -

errCode 的属性描述

合法值兼容性描述
1001Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -urls至少包含一张图片地址
1101001Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -用户取消
1101003Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -文件不存在
1101004Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -图片加载失败
1101005Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -未获取权限
1101010Web: -; 微信小程序: x; Android: -; iOS: -; HarmonyOS: -其他错误
<!-- UTSAPIJSON.closePreviewImage.example -->

参见

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息