存储

使用存储

SDK 对象： 存储

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

AsyncStorage无法使用

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

签名

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 在仓库中 with-storage 下载代码，或扫描下方二维码亲自体验。

QR 码链接：intoss://with-storage

保存值

SDK 函数： setItem

setItem 该函数会将字符串数据保存到本地存储中。应用退出后再次运行时，如果需要保留数据，就使用它。

签名

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

参数

• key · 必填 · string

  请输入要保存的项目键。
• value · 必填 · string

  请输入要保存的项目值。

返回值

• Promise<void>

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

示例

my-key中保存项目

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

React

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>
    </>
  );
}

React Native

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>
    </>
  );
}

获取值

SDK 函数： getItem

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

签名

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

参数

• key · 必填 · string

  请输入要获取的项目键。

返回值

• Promise<string | null>

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

示例

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

js

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

const KEY = 'my-key';

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

React

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>;
}

React Native

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>;
}

删除值

SDK 函数： removeItem

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

签名

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

参数

• key · 必填 · string

  请输入要删除的项目键。

返回值

• Promise<void>

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

示例

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

js

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

const KEY = 'my-key';

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

React

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>;
}

React Native

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>;
}

初始化存储

SDK 函数： clearItems

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

签名

declare function clearItems(): Promise<void>;

返回值

• Promise<void>

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

示例

初始化存储

js

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

async function handleClearItems() {
  await Storage.clearItems();
  console.log('存储已清除');
}

React

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>;
}

React Native

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>;
}

---

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 正式 — 旧版本 ↔ 新版本	共享

使用 IndexedDB 时请注意

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

---

常见问题

有存储容量限制吗？

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

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

我想发布体量较大的游戏，该如何实现？

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

详细内容请参考发布指南。