> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/permission/album.md).

# 相册

{% hint style="info" %}
**需要进行权限设置**

`fetchAlbumItems`使用前需要设置相册权限。请先查看权限设置指南。
{% endhint %}

***

### 1. 选择相册媒体

**SDK 函数：** `fetchAlbumItems`

用于从用户相册中选择并导入照片·视频的函数。可以同时选择照片和视频，若用户取消选择则返回空数组 `[]`则返回

**签名**

```typescript
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 时 |

**示例**

{% tabs %}
{% tab title="React" %}

```tsx
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);
  }
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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);
  }
}
```

{% endtab %}
{% endtabs %}

**`FetchAlbumItemsOptions`**

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

属性：

* typesArray<'PHOTO' | 'VIDEO'>

  要导入的媒体类型列表。 `'PHOTO'`(照片), `'VIDEO'`(视频) 中选择。未指定时仅导入照片。
* **maxCountnumber** · `10`

  要导入的项目最大数量。
* **maxWidthnumber** · `1024`

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

  图片的 `dataUri`是否返回为 Base64 字符串。

**`AlbumItemResponse`**

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

属性：

* idstring

  项目的唯一 ID。
* **data** · `Uristring`

  媒体数据 URI。 `type`如果是 `PHOTO`并且 `base64` 选项 `true`时将返回为 Base64 字符串。
* type'PHOTO' | 'VIDEO'

  媒体类型。

***

### 2. 获取相册

**SDK 函数：** `fetchAlbumPhotos`

{% hint style="info" %}
**有新版本**

`fetchAlbumPhotos`仅支持照片。如果需要同时选择照片和视频，或需要更细粒度的控制 [`fetchAlbumItems`](#_1-%EC%95%A8%EB%B2%94-%EB%AF%B8%EB%94%94%EC%96%B4-%EC%84%A0%ED%83%9D%ED%95%98%EA%B8%B0)请使用。
{% endhint %}

用于从用户相册加载照片列表的函数。可以设置最大数量和分辨率。

**签名**

```typescript
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 的数组。

**示例**

{% tabs %}
{% tab title="Web（JS）" %}

```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('没有相册读取权限');
    }
  }
}
```

{% endtab %}

{% tab title="Web（React）" %}

```tsx
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>

  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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>
  );
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/permission/album.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.