uni-app x

# uni.saveImageToPhotosAlbum(options)

保存图片到系统相册

# saveImageToPhotosAlbum 兼容性

Web	微信小程序	Android	iOS	HarmonyOS	HarmonyOS(Vapor)
x	4.41	3.9	4.11	4.61	5.0

# 参数

名称

类型

必填

默认值

兼容性

描述

options

SaveImageToPhotosAlbumOptions

是

名称

类型

必备

默认值

兼容性

描述

filePath

string.ImageURIString

是

图片文件路径，可以是临时文件路径也可以是永久文件路径，不支持网络图片路径

success

(callback: SaveImageToPhotosAlbumSuccess) => void

否

接口调用成功的回调函数

fail

(callback: SaveImageToPhotosAlbumFail) => void

否

接口调用失败的回调函数

complete

(callback: any) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

# SaveImageToPhotosAlbumSuccess 的属性值

名称

类型

必备

默认值

兼容性

描述

path

string

是

保存到相册的图片路径

# SaveImageToPhotosAlbumFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值

兼容性

描述

1101001

用户取消

1101002

urls至少包含一张图片地址

1101003

文件不存在

1101004

图片加载失败

1101005

未获取权限

1101006

图片或视频保存失败

1101007

图片裁剪失败

1101008

拍照或录像失败

1101009

图片压缩失败

1101010

其他错误

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

该 API 不支持 Web，请运行 hello uni-app x 到 App 平台体验

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex:1">
  <!-- #endif -->
    <page-head :title="title"></page-head>
    <view class="uni-padding-wrap">
      <image class="image" src="/static/test-image/logo.png"></image>
      <button class="margin-top-10" type="primary" @click="saveImage">将图片保存到手机相册</button>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script setup lang="uts">
  const title = ref("saveImageToPhotosAlbum")

  type TestStateType = {
    success : boolean
  }

  // 使用reactive避免ref数据在自动化测试中无法访问
  const testState = reactive({
    success: false
  } as TestStateType)

  const saveImage = () => {
    uni.saveImageToPhotosAlbum({
      filePath: "/static/test-image/logo.png",
      success: (res) => {
        console.log("saveImageToPhotosAlbum success", JSON.stringify(res));
        uni.showToast({
          position: "center",
          icon: "none",
          title: "图片保存成功，请到手机相册查看"
        });
        testState.success = true;
      },
      fail: (err) => {
        uni.showModal({
          title: "保存图片到相册失败",
          content: JSON.stringify(err),
          showCancel: false
        });
        testState.success = false;
      }
    })
  }

  defineExpose({
    testState,
    saveImage
  })

</script>

<style>
  .margin-top-10 {
    margin-top: 10px;
  }

  .image {
    width: 196px;
    height: 196px;
    align-self: center;
  }
</style>

示例源码如下，请查看 pre > code 标签中的内容

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex:1">
  <!-- #endif -->
    <page-head :title="title"></page-head>
    <view class="uni-padding-wrap">
      <image class="image" src="/static/test-image/logo.png"></image>
      <button class="margin-top-10" type="primary" @click="saveImage">将图片保存到手机相册</button>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script setup lang="uts">
  const title = ref("saveImageToPhotosAlbum")

  type TestStateType = {
    success : boolean
  }

  // 使用reactive避免ref数据在自动化测试中无法访问
  const testState = reactive({
    success: false
  } as TestStateType)

  const saveImage = () => {
    uni.saveImageToPhotosAlbum({
      filePath: "/static/test-image/logo.png",
      success: (res) => {
        console.log("saveImageToPhotosAlbum success", JSON.stringify(res));
        uni.showToast({
          position: "center",
          icon: "none",
          title: "图片保存成功，请到手机相册查看"
        });
        testState.success = true;
      },
      fail: (err) => {
        uni.showModal({
          title: "保存图片到相册失败",
          content: JSON.stringify(err),
          showCancel: false
        });
        testState.success = false;
      }
    })
  }

  defineExpose({
    testState,
    saveImage
  })

</script>

<style>
  .margin-top-10 {
    margin-top: 10px;
  }

  .image {
    width: 196px;
    height: 196px;
    align-self: center;
  }
</style>