小程序開發文件

啟動與事件 ​

畫面層專用（@im/miniapp-sdk）。

sdk.ready() ​

ts
sdk.ready(): Promise<void>

首屏可互動時呼叫，容器隨即淡出骨架並記錄啟動耗時。

  • 重複呼叫只會送出一次；失敗後可以再呼叫。
  • 頁面載入完 8 秒內沒呼叫，容器會自動移除骨架。
  • 詳見生命週期 → 骨架。
ts
await nextTick(); // 等 Vue 把首屏畫出來
sdk.ready().catch(() => {});

getLaunch() ​

ts
getLaunch(): ImLaunch | null

容器在頁面載入前注入的啟動資訊；不在容器內時為 null。同步可用，不需要等待。

ts
interface ImLaunch {
  v: 1;
  appId: string;                 // 小程序 id
  version: string;               // 目前執行的版本
  platform: 'ios' | 'android';
  containerVersion: string;      // 容器版本，例如 '1.2.0'
  theme: 'light' | 'dark';       // 啟動時的深淺色
  safeArea: { top: number; bottom: number }; // 啟動時的安全區（px）
  locale: string;                // App 語言，例如 'zh'、'en'
  path?: string;                 // 起始頁（分享卡片帶的），沒有時為 '/'
}
  • theme、safeArea 是啟動當下的值；之後的變化看 sdk.theme.onChange 或直接用 CSS 變數。
  • locale 只在啟動時給；使用者換了 App 語言，保活的實例不會被接回，下次開啟會拿到新的值。

inContainer() ​

ts
inContainer(): boolean

是否在容器內（有原生通道）。在瀏覽器預覽時為 false，此時所有 SDK 呼叫都會以 NOT_IN_CONTAINER 失敗。

sdk.on() ​

ts
sdk.on(event: 'app.pause' | 'app.resume', callback: () => void): () => void

訂閱前景、背景事件，回傳取消訂閱的函式。

事件時機
app.pauseApp 退到背景；小程序被關閉、進入保活
app.resumeApp 回到前景；保活的小程序被重新打開
ts
const off = sdk.on('app.pause', () => {
  void sdk.storage.set('draft', draft.value);
});
// 不再需要時
off();

第一次啟動不會收到 app.resume。