> 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 对象：** `存储`

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

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

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

**签名**

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

**属性**

* getItemtypeof getItem

  从本地存储中获取值的函数。
* setItemtypeof setItem

  将值保存到本地存储的函数。
* removeItemtypeof removeItem

  从本地存储中删除值的函数。
* clearItemstypeof 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) 下载代码，或扫描下方二维码亲自体验。

QR 码链接：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('存储已清除');
}
```

{% 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('存储已清除');
  }

  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('存储已清除');
  }

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

{% endtab %}
{% endtabs %}

***

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

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

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

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

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

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

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

***

### 常见问题

<details>

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

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

迷你应用可使用的存储容量（例如： `存储`、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.