邏輯層 API

@im/miniapp-sdk/logic，只能在雙執行緒的邏輯層（miniapp.config.ts 的 logic 入口）使用。執行環境見單執行緒與雙執行緒 → 邏輯層可以用什麼。

import { definePage, setData, getData, sdk, MiniAppError } from '@im/miniapp-sdk/logic';

definePage()

definePage<D extends Record<string, unknown>>(options: PageOptions<D>): void

interface PageOptions<D> {
  data: D;                                               // 初始資料
  onLoad?(launch: ImLaunch): unknown;                    // 啟動後呼叫一次
  onShow?(): unknown;                                    // 回到前景、保活接回
  onHide?(): unknown;                                    // 退到背景、關閉進入保活
  handlers?: Record<string, (payload: unknown) => unknown>; // 對應畫面層的 sdk.view.emit
}

• 整個邏輯層只能呼叫一次，第二次會拋錯。
• data 會立刻送給容器，成為畫面層的初始資料。邏輯層還沒啟動完成時，畫面層第一次拿到的快照可能是空物件 {}，初始資料隨後以更新送達（見 sdk.view.connect）。
• onLoad 收到的 launch 和畫面層 getLaunch() 的欄位相同（theme 為啟動時的值）。
• 回呼與 handler 可以是 async 函式；同步拋出的錯誤與 rejected Promise 都會上報給容器，不會讓邏輯層停止。

setData()

setData<D extends Record<string, unknown>>(diff: Partial<D>): void

• 淺層合併：只覆寫 diff 裡的頂層 key。要改巢狀物件裡的一個欄位，要給整個頂層物件的新值。
• 本地資料立即更新（緊接著的 getData() 就拿得到）；同一個 microtask 內的多次呼叫合併成一次送出。
• 值必須能 JSON 序列化。

setData({ status: 'loading' });
const list = await fetchList();
setData({ status: 'ready', list }); // 只送 status 與 list

getData()

getData<D extends Record<string, unknown>>(): D

目前完整資料的淺拷貝。

sdk

和畫面層相同介面的子集：

可用	不可用（只在畫面層）
sdk.auth、sdk.ui、sdk.system、sdk.http、sdk.storage、sdk.share、sdk.telemetry	sdk.ready、sdk.theme、sdk.navigate、sdk.view、sdk.on、getLaunch、inContainer

邏輯層的 sdk.ui.*、sdk.share.toChat 一樣需要小程序顯示在畫面上。

不在容器的邏輯層內執行時，所有 sdk.* 呼叫以 NOT_IN_CONTAINER 失敗。