Device.getAlbumItems

함수형 API fetchAlbumItems로도 같은 기능을 쓸 수 있어요.

기능 설명

사용자 앨범에서 사진·동영상을 선택해 가져와요. 선택을 취소하면 빈 배열 []을 반환하고, types를 지정하지 않으면 사진만 선택돼요.

토스앱 Android/iOS 5.261.0 이상에서 사용할 수 있어요. 호출 전에 Device.getAlbumItems.isSupported()로 지원 여부를 확인할 수 있어요. 미지원 버전에서 호출하면 UNSUPPORTED_APP_VERSION 에러가 발생해요.

타입

Device.getAlbumItems(options?: FetchAlbumItemsOptions): Promise<AlbumItemResponse[]>;

Params

type AlbumItemType = "PHOTO" | "VIDEO";

type FetchAlbumItemsOptions = {
  /** 가져올 미디어 유형 목록이에요. 지정하지 않으면 사진만 가져와요. */
  types?: AlbumItemType[];
  /** 가져올 항목의 최대 개수예요. 기본값은 10이에요. */
  maxCount?: number;
  /** 이미지의 최대 폭(px)이에요. 기본값은 1024이에요. */
  maxWidth?: number;
  /** 이미지 dataUri를 Base64로 반환할지 여부예요. 기본값은 false이에요. */
  base64?: boolean;
};

Response

type AlbumItemResponse = {
  id: string;
  dataUri: string;
  type: "PHOTO" | "VIDEO";
};

에러

에러 코드는 catch한 에러의 error.code 값이에요.

코드	설명
NOT_ALLOWED	앨범 접근이 허용되지 않은 경우예요.
INVALID_REQUEST	요청 파라미터가 올바르지 않은 경우예요.
INVALID_DATA	미디어 데이터가 유효하지 않은 경우예요.
UNSUPPORTED_APP_VERSION	실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. Device.getAlbumItems.isSupported()로 사전 확인하고, 발생 시 error.message(업데이트 안내 문구)를 사용자에게 보여주세요.

예시 코드

import { Device } from "@apps-in-toss/web-framework";

async function pickAlbumItems() {
  if (!Device.getAlbumItems.isSupported()) {
    console.warn("현재 토스앱 버전에서는 사용할 수 없어요.");
    return;
  }

  try {
    const items = await Device.getAlbumItems({
      types: ["PHOTO", "VIDEO"],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log("선택이 취소되었어요.");
      return;
    }
    console.log(items);
  } catch (error) {
    console.error(error);
  }
}

document.getElementById("pick-media").addEventListener("click", pickAlbumItems);