fetchAlbumPhotos

기기 앨범에서 사진 목록을 불러옵니다. 가져올 최대 개수와 해상도 상한을 설정할 수 있고, 선택적으로 Base64 인코딩된 데이터 URI로 반환받을 수 있습니다. 갤러리 미리보기, 이미지 선택 UI 등에 활용할 수 있습니다.

시그니처

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

declare const fetchAlbumPhotos: PermissionFunctionWithDialog<
  (options?: FetchAlbumPhotosOptions) => Promise<ImageResponse[]>
>;

interface FetchAlbumPhotosOptions {
  /** 가져올 사진의 최대 개수. 기본값 10. */
  maxCount?: number;
  /** 사진의 최대 폭(픽셀). 기본값 1024. */
  maxWidth?: number;
  /** true이면 Base64 문자열로 반환. 기본값 false. */
  base64?: boolean;
}

interface ImageResponse {
  /** 사진의 고유 ID */
  id: string;
  /** 사진의 데이터 URI. base64 옵션이 true인 경우 Base64 문자열. */
  dataUri: string;
}

파라미터

이름	타입	필수	설명
options.maxCount	number	—	가져올 사진의 최대 개수입니다. 기본값은 10이에요.
options.maxWidth	number	—	사진의 최대 폭(픽셀)을 제한합니다. 기본값은 1024이에요.
options.base64	boolean	—	true이면 dataUri를 Base64 문자열로 반환합니다. 기본값은 false이에요.

반환값

• Promise<ImageResponse[]> — 사진 고유 ID와 데이터 URI를 담은 배열.
  • base64: false (기본) 시 dataUri는 기기 로컬 경로 또는 파일 URI입니다.
  • base64: true 시 dataUri는 Base64 문자열이며, <img> 태그에 사용하려면 data:image/jpeg;base64, prefix를 붙여야 합니다.
• 권한 denied 시 호출이 실패합니다. "권한" 섹션 참고.

권한

photos 권한이 필요합니다. 권한이 명시적으로 denied 상태이면 호출이 실패하므로 try/catch로 감싸세요. notDetermined 상태에서는 호출이 그대로 진행될 수 있지만, 사용자 경험상 먼저 다이얼로그로 승격시키는 것이 안전합니다. 상세 처리 패턴은 Guides — 권한 처리 패턴을 참고하세요.

함수 객체에 권한 유틸이 붙어있습니다:

const status = await fetchAlbumPhotos.getPermission();
// 'allowed' | 'denied' | 'notDetermined'

if (status !== 'allowed') {
  await fetchAlbumPhotos.openPermissionDialog();
}

예제

최소 예제

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

async function loadPhotos() {
  const photos = await fetchAlbumPhotos({ maxCount: 5 });
  console.log(photos.map((p) => p.id));
}

실전 예제 — Base64 이미지 목록 표시

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

interface Photo {
  id: string;
  dataUri: string;
}

export function AlbumPhotoGrid() {
  const [photos, setPhotos] = useState<Photo[]>([]);
  const [message, setMessage] = useState('');
  const [pending, setPending] = useState(false);

  async function loadAlbum() {
    setPending(true);
    setMessage('');
    try {
      const status = await fetchAlbumPhotos.getPermission();
      if (status === 'denied') {
        setMessage('설정에서 사진 접근 권한을 허용해 주세요.');
        return;
      }
      if (status === 'notDetermined') {
        await fetchAlbumPhotos.openPermissionDialog();
      }

      const result = await fetchAlbumPhotos({ maxCount: 9, maxWidth: 360, base64: true });
      setPhotos(result);
    } catch (error) {
      setMessage('앨범을 불러오지 못했어요. 다시 시도해 주세요.');
      console.error(error);
    } finally {
      setPending(false);
    }
  }

  return (
    <div>
      <button type="button" onClick={loadAlbum} disabled={pending}>
        {pending ? '불러오는 중...' : '앨범 불러오기'}
      </button>
      {message && <p role="status">{message}</p>}
      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 4 }}>
        {photos.map((photo) => (
          <img
            key={photo.id}
            src={`data:image/jpeg;base64,${photo.dataUri}`}
            alt=""
            style={{ width: '100%', aspectRatio: '1', objectFit: 'cover' }}
          />
        ))}
      </div>
    </div>
  );
}

직접 실행해 보기

sdk-example의 Camera 페이지에서 fetchAlbumPhotos 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• openCamera — 기기 카메라로 사진을 촬영합니다.
• fetchContacts — 연락처 목록을 페이지 단위로 조회합니다.

관련 가이드

• Recipes — 앨범 사진 선택 UI 패턴
• Guides — 권한 처리 패턴

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.