相册

需要设置权限

fetchAlbumItems在使用前需要设置相册权限。请先查看权限设置指南。

---

1. 选择相册媒体

SDK 函数： fetchAlbumItems

这是一个从用户相册中选择照片·视频并获取的函数。可以同时选择照片和视频，用户取消选择时返回空数组 []则返回。

签名

function fetchAlbumItems(options?: FetchAlbumItemsOptions): Promise<AlbumItemResponse[]>;

参数

• options · FetchAlbumItemsOptions

  包含查询选项的对象。详细类型见下方 FetchAlbumItemsOptions。

返回值

• Promise<AlbumItemResponse\[]>

  返回所选媒体列表。用户取消时返回空数组。

错误

错误代码	发生条件
NOT_ALLOWED	当未允许访问相册时
INVALID_REQUEST	当请求参数不正确时
INVALID_DATA	当媒体数据无效时
UNSUPPORTED_APP_VERSION	当 Toss App 版本低于 5.261.0 时

示例

React

import { fetchAlbumItems } from '@apps-in-toss/web-framework';

async function pickMedia() {
  try {
    const items = await fetchAlbumItems({
      types: ['PHOTO', 'VIDEO'],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log('已取消选择。');
      return;
    }

    items.forEach((item) => {
      console.log(item.type, item.id);
    });
  } catch (error) {
    console.error('相册查询错误：', error.code);
  }
}

React Native

import { fetchAlbumItems } from '@apps-in-toss/framework';

async function pickMedia() {
  try {
    const items = await fetchAlbumItems({
      types: ['PHOTO', 'VIDEO'],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log('已取消选择。');
      return;
    }

    items.forEach((item) => {
      console.log(item.type, item.id);
    });
  } catch (error) {
    console.error('相册查询错误：', error.code);
  }
}

FetchAlbumItemsOptions

interface FetchAlbumItemsOptions {
  types?: AlbumItemType[];
  maxCount?: number;
  maxWidth?: number;
  base64?: boolean;
}

属性：

• typesArray<'PHOTO' | 'VIDEO'>

  要获取的媒体类型列表。 'PHOTO'（照片）， 'VIDEO'（视频）中选择。如果不指定，则只获取照片。
• maxCountnumber · 10

  要获取的项目最大数量。
• maxWidthnumber · 1024

  图片的最大宽度。单位为像素。
• base64boolean · false

  图片的 dataUri是否将其作为 Base64 字符串返回。

AlbumItemResponse

interface AlbumItemResponse {
  id: string;
  dataUri: string;
  type: AlbumItemType;
}

属性：

• idstring

  是项目的唯一 ID。
• 数据 · Uristring

  是媒体数据 URI。 类型如果是 PHOTO并且是 base64 选项 true则返回为 Base64 字符串。
• type'PHOTO' | 'VIDEO'

  是媒体类型。

---

2. 获取相册

SDK 函数： fetchAlbumPhotos

有新版本

fetchAlbumPhotos仅支持照片。若需同时选择照片和视频，或需要更细致的控制， fetchAlbumItems请使用。

这是一个从用户相册中获取照片列表的函数。可以设置最大数量和分辨率。

签名

function fetchAlbumPhotos(options: { maxCount: number; maxWidth: number; base64: boolean }): Promise<ImageResponse[]>;

参数

• options · 必填

  包含查询选项的对象。

  • options.maxCount · number

    要获取的照片最大数量。
  • options.maxWidth · number

    照片的最大宽度。单位为像素。
  • options.base64 · boolean

    设置是否将图片以 Base64 格式返回。

返回值

• Promise<ImageResponse\[]>

  返回包含相册照片唯一 ID 和数据 URI 的数组。

示例

Web（JS）

import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchAlbumPhotos() {
  try {
    const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
    response.forEach((image) => {
      const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
      console.log('图片 URI：', imageUri);
    });
  } catch (error) {
    if (error instanceof FetchAlbumPhotosPermissionError) {
      console.log('没有相册读取权限');
    }
  }
}

Web（React）

import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // 没有相册读取权限
      }
    }
  };

  return (
    <div>
      {albumPhotos.map((image) => {
        const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
        return <img src={imageUri} key={image.id} />;
      })}
      <button onClick={handlePress}>获取相册</button>

  );
}

React Native

import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Image, View } from 'react-native';

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // 没有相册读取权限
      }
    }
  };

  return (
    <View>
      {albumPhotos.map((image) => {
        const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
        return <Image source={{ uri: imageUri }} key={image.id} />;
      })}
      <Button title="获取相册" onPress={handlePress} />
      <Button
        title="检查权限"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="请求权限"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}