For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/media/chooseImage.md.

chooseImage

选择图片。

扫码预览

扫码预览 chooseImage

使用限制

WARNING

Android、iOS:选择结果不受 sizeType 影响;调用方无法控制返回图片尺寸。 Android、iOS:仅当数组只包含 camera 时打开相机;其他组合均打开相册,user 和 environment 不生效;传入多个来源或 user、environment 时实际入口与配置不一致。

支持版本

前端库版本不低于 0.0.26。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

接入准备

权限要求

类型标识是否必须平台说明
系统权限相册访问权限按条件Android、iOS从相册选择图片时,系统或豆包图片选择器可能按系统版本请求访问权限
系统权限相机权限按条件Android、iOSsourceType 只传 camera 时需要使用相机

授权行为

  • Android:API 直接打开豆包图片选择器或相机。系统需要权限时会由对应选择器发起申请;拒绝或撤销后选择失败,请在系统设置中开启相册或相机权限后重试。
  • iOS:API 直接打开豆包相册选择器或系统相机。首次需要时系统会请求相册或相机权限;拒绝或撤销后选择失败,请在系统设置中开启后重试。

前置条件

  • 在可展示图片选择器的前台页面中,由用户操作触发调用

使用说明

  • 图片属于用户数据,仅在业务必需时选择,并及时释放不再使用的临时文件。

调用方式

异步 API

chooseImage(params?: ChooseImageParams): Promise<ChooseImageResult>

入参

名称类型必填默认值约束说明
countnumber否9正整数最多可选图片张数。使用相机时固定返回一张图片。
imageIdstring否--H5 场景下可复用的 input 元素 ID。
sizeTypeChooseImageSizeType[]否--允许返回的图片尺寸类型。Android、iOS:选择结果不受 sizeType 影响。
sourceTypeChooseImageSourceType[]否["album"]-允许选择的图片来源。Android、iOS:仅当数组只包含 camera 时打开相机;其他组合均打开相册,user 和 environment 不生效。

调用示例

import { chooseImage } from '@doubao-dev/framework/api';

const { tempFilePaths } = await chooseImage({
  count: 1,
  sourceType: ['album']
});

console.log(tempFilePaths);

成功返回

名称类型必返说明
tempFilePathsstring[]是图片临时文件路径列表。
tempFilesChooseImageFile[]是图片临时文件信息列表。
tempFiles[].originalFileObjFile否原始浏览器 File 对象。
tempFiles[].pathstring是本地临时文件路径。
tempFiles[].sizenumber是文件大小,单位 B。
tempFiles[].typestring否文件 MIME 类型。

返回示例

{
  "tempFilePaths": ["appletfile://temp/example.jpg"],
  "tempFiles": [
    {
      "path": "appletfile://temp/example.jpg",
      "size": 245760,
      "type": "image/jpeg"
    }
  ]
}

平台差异

  • 使用相机时固定返回一张图片。