> 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/file-storage/storage.md).

# 存储

### 使用存储

**SDK 对象：** `Storage`

`Storage` 可以使用原生的存储。删除 Toss 应用时，存储中的数据也会一并删除。

{% hint style="info" %}
**`AsyncStorage`无法使用**

在 App in Toss 环境中 `AsyncStorage`无法使用。使用该 API 可能会导致画面变白（white-out）问题。
{% endhint %}

**签名**

```typescript
Storage: {
  getItem: typeof getItem;
  setItem: typeof setItem;
  removeItem: typeof removeItem;
  clearItems: typeof clearItems;
}
```

**属性**

* getItem 的类型为 typeof getItem

  从本地存储中获取值的函数。
* setItem 的类型为 typeof setItem

  将值保存到本地存储的函数。
* removeItem 的类型为 typeof removeItem

  从本地存储中删除值的函数。
* clearItems 的类型为 typeof clearItems

  删除本地存储中所有数据的函数。

**体验示例应用**

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 在仓库中 [with-storage](https://github.com/toss/apps-in-toss-examples/tree/main/with-storage) 下载代码，或扫描下方二维码亲自体验。

二维码链接: intoss\://with-storage

### 保存值

**SDK 函数：** `setItem`

`setItem` 函数会将字符串数据保存到本地存储中。需要在退出应用后重新运行时仍保留数据时使用。

**签名**

```typescript
function setItem(key: string, value: string): Promise<void>;
```

**参数**

* **key** · 必需 · `string`

  请输入要保存项目的键。
* **value** · 必需 · `string`

  请输入要保存项目的值。

**返回值**

* `Promise<void>`

  项目成功保存后不会返回任何值。

**示例**

`my-key`在…中保存项目

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

```js
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleSetStorageItem(value) {
  const storageValue = await Storage.setItem(KEY, value);
}

async function handleGetStorageItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}

async function handleRemoveStorageItem() {
  await Storage.removeItem(KEY);
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { Storage } from '@apps-in-toss/web-framework';
import { Button, Text } from '@toss/tds-mobile';
import { useState } from 'react';

const KEY = 'my-key';

function StorageTestPage() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onClick={handleSet}>保存</Button>
      <Button onClick={handleGet}>获取</Button>
      <Button onClick={handleRemove}>删除</Button>
    </>
  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Storage } from '@apps-in-toss/framework';
import { Button, Text } from '@toss/tds-react-native';
import { useState } from 'react';

const KEY = 'my-key';

function StorageTestPage() {
  const [storageValue, setStorageValue] = useState<string | null>(null);

  async function handleSet() {
    await Storage.setItem(KEY, 'my-value');
  }

  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return (
    <>
      <Text>{storageValue}</Text>
      <Button onPress={handleSet}>保存</Button>
      <Button onPress={handleGet}>获取</Button>
      <Button onPress={handleRemove}>删除</Button>
    </>
  );
}
```

{% endtab %}
{% endtabs %}

### 获取值

**SDK 函数：** `getItem`

`getItem` 函数会获取本地存储中保存的字符串数据。

**签名**

```typescript
function getItem(key: string): Promise<string | null>;
```

**参数**

* **key** · 必需 · `string`

  请输入要获取项目的键。

**返回值**

* `Promise<string | null>`

  返回指定键中保存的字符串值。如果没有值， `null`则返回

**示例**

`my-key`获取保存在…中的项目

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

```js
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleGetItem() {
  const storageValue = await Storage.getItem(KEY);
  return storageValue;
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  return <Button onClick={handleGet}>获取</Button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleGet() {
    const storageValue = await Storage.getItem(KEY);
    setStorageValue(storageValue);
  }

  return <Button onPress={handleGet}>获取</Button>;
}
```

{% endtab %}
{% endtabs %}

### 删除值

**SDK 函数：** `removeItem`

`removeItem` 函数会删除对应特定键的值。

**签名**

```typescript
declare function removeItem(key: string): Promise<void>;
```

**参数**

* **key** · 必需 · `string`

  请输入要删除项目的键。

**返回值**

* `Promise<void>`

  删除项目后不会返回任何值。

**示例**

`my-key`删除保存在…中的项目

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

```js
import { Storage } from '@apps-in-toss/web-framework';

const KEY = 'my-key';

async function handleRemoveItem() {
  await Storage.removeItem(KEY);
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return <Button onClick={handleRemove}>删除</Button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

const KEY = 'my-key';

function StorageClearButton() {
  async function handleRemove() {
    await Storage.removeItem(KEY);
  }

  return <Button onPress={handleRemove}>删除</Button>;
}
```

{% endtab %}
{% endtabs %}

### 初始化存储

**SDK 函数：** `clearItems`

`clearItems` 函数会删除本地存储中保存的所有数据。

**签名**

```typescript
declare function clearItems(): Promise<void>;
```

**返回值**

* `Promise<void>`

  删除项目后不会返回任何值，并且存储会被初始化。

**示例**

初始化存储

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

```js
import { Storage } from '@apps-in-toss/web-framework';

async function handleClearItems() {
  await Storage.clearItems();
  console.log('Storage cleared');
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { Storage } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function StorageClearButton() {
  async function handleClick() {
    await Storage.clearItems();
    console.log('Storage cleared');
  }

  return <Button onClick={handleClick}>初始化存储</Button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Storage } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function StorageClearButton() {
  async function handlePress() {
    await Storage.clearItems();
    console.log('Storage cleared');
  }

  return <Button onPress={handlePress}>初始化存储</Button>;
}
```

{% endtab %}
{% endtabs %}

***

### Web 标准存储与缓存行为

`localStorage`、IndexedDB、 `window.caches` 这类 Web 标准存储会根据 WebView 的 origin（URL）进行保存。

Toss 应用正式环境与 QR 码测试环境使用不同的 URL，因此存储在 Web 标准存储中的数据不会相互共享。

* Toss 应用正式版： `https://<appName>.apps.tossmini.com`
* QR 码测试： `https://<appName>.private-apps.tossmini.com`

| 环境                     | Web 标准存储是否共享 |
| ---------------------- | ------------ |
| QR 码测试 ↔ Toss 应用正式版    | 不共享          |
| QR 测试 — 版本 A ↔ 版本 B    | 共享           |
| Toss 应用正式版 — 旧版本 ↔ 新版本 | 共享           |

{% hint style="info" %}
**使用 IndexedDB 时请注意**

在 WebView 环境中使用 IndexedDB 时，在 iOS 上 **如果 7 天内没有交互，数据会自动删除**。如果需要本地缓存， `window.caches`建议使用（Cache API）。
{% endhint %}

***

### 常见问题

<details>

<summary>有存储容量限制吗？</summary>

应用包解压后仅可上传 100MB 以下的内容。

迷你应用可使用的存储容量（例如： `Storage`、Cache API 等）没有单独限制。

</details>

<details>

<summary>我想发布容量较大的游戏。应该如何实现？</summary>

建议只包含初始启动所需的最小资源来构建应用包，之后的游戏资源从独立 CDN 下载。

详细内容请参考部署指南。

</details>


---

# 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/file-storage/storage.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.