본문으로 건너뛰기

Storage.getItem

키에 해당하는 문자열 값을 비동기로 읽어 옵니다. 키가 없으면 null입니다 — 빈 문자열('')과 구분됩니다.

비공식 문서

이 페이지는 커뮤니티가 작성한 설명입니다. SDK의 동작은 상위의 @apps-in-toss/web-framework 배포본을 기준으로 합니다.

시그니처​

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

declare const Storage: {
  getItem(key: string): Promise<string | null>;
  // ...overview 참고
};

파라미터​

이름타입필수설명
keystring✓읽어 올 키. 같은 미니앱이 setItem으로 쓴 키와 정확히 일치해야 합니다.

반환값​

  • Promise<string | null> — 키에 저장된 문자열, 또는 키가 존재하지 않으면 null.
null ≠ 빈 문자열

null은 키가 한 번도 저장된 적이 없거나 removeItem/clearItems로 삭제된 상태를 의미합니다. 빈 문자열('')은 호출부가 명시적으로 빈 값을 저장한 결과이며 두 경우는 별개입니다. 분기할 때는 value === null로 정확히 비교하세요 (!value는 ''까지 묶어 버립니다).

권한​

권한이 필요하지 않습니다 — Storage 네임스페이스는 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제​

최소 예제​

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

const lastSeen = await Storage.getItem('user.lastSeenScreen');
console.log(lastSeen ?? 'home'); // 첫 방문이면 기본값 'home'

실전 예제 — 직렬화된 객체를 안전하게 복원​

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

interface UserPrefs {
  theme: 'light' | 'dark';
  language: string;
}

const DEFAULT_PREFS: UserPrefs = { theme: 'light', language: 'ko' };

async function loadPrefs(): Promise<UserPrefs> {
  const raw = await Storage.getItem('user.prefs');
  if (raw === null) return DEFAULT_PREFS;
  try {
    const parsed = JSON.parse(raw) as Partial<UserPrefs>;
    // 옛 버전이 일부 필드만 썼을 수 있으니 기본값으로 채웁니다.
    return { ...DEFAULT_PREFS, ...parsed };
  } catch {
    // 형식이 깨졌거나 옛 스키마. 기본값으로 폴백.
    return DEFAULT_PREFS;
  }
}

직접 실행해 보기​

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

sdk-example에서 실행해 보기

관련 API​

관련 가이드​

  • Guides — 권한 처리 패턴 — 다른 네임스페이스의 권한 흐름 (참고용; Storage는 권한이 필요하지 않습니다).
  • (작성 예정) Recipes — "사용자 설정 저장 패턴 (직렬화·마이그레이션·기본값)"

외부 참조​