API 總覽
匯入
ts
// 畫面層（WebView）
import { sdk, getLaunch, inContainer, MiniAppError } from '@im/miniapp-sdk';
// 邏輯層（runtime: 'dual'）
import { sdk, definePage, setData, getData, MiniAppError } from '@im/miniapp-sdk/logic';型別都從同一個入口匯出（import type { Session, ImLaunch } from '@im/miniapp-sdk'）。
能力一覽
| API | 畫面層 | 邏輯層 | 最低容器版本 |
|---|---|---|---|
sdk.ready()、getLaunch()、inContainer()、sdk.on() | ✓ | — | 1.0.0 |
sdk.auth.getSession() | ✓ | ✓ | 1.0.0（refresh 1.2.0） |
sdk.ui.* | ✓ | ✓ | 1.0.0 |
sdk.theme.* | ✓ | — | 1.0.0 |
sdk.navigate.* | ✓ | — | 1.0.0 |
sdk.system.* | ✓ | ✓ | 1.0.0 |
sdk.http.fetch() | ✓ | ✓ | 1.0.0 |
sdk.storage.* | ✓ | ✓ | 1.1.0 |
sdk.share.toChat() | ✓ | ✓ | 1.1.0 |
sdk.telemetry.report() | ✓ | ✓ | 1.1.0 |
sdk.view.* | ✓ | — | 1.1.0 |
definePage、setData、getData | — | ✓ | 1.1.0 |
需要畫面的呼叫只在小程序顯示時有效。保活期間：ui.toast、ui.dialog、ui.actionSheet、share.toChat 會以 INTERNAL 失敗；ui.setTitle、ui.loading、navigate.close 不會報錯，但沒有效果。
錯誤處理
所有非同步 API 失敗時都以 MiniAppError reject：
ts
class MiniAppError extends Error {
readonly code: string; // 見下表
}| code | 意思 |
|---|---|
NOT_IN_CONTAINER | 不在容器內（瀏覽器預覽）。由 SDK 產生，不會送到容器 |
NOT_ALLOWED | 方法不存在、權限沒宣告、或此執行層不能呼叫 |
PERMISSION_DENIED | 使用者拒絕授權 |
DOMAIN_BLOCKED | 網址不在 domains |
INVALID_PARAMS | 參數不合法 |
RATE_LIMITED | 呼叫太頻繁，或同類操作已在進行中 |
QUOTA_EXCEEDED | 儲存空間已滿 |
NETWORK | 網路錯誤 |
TIMEOUT | 逾時 |
INTERNAL | 容器內部錯誤 |
各錯誤的常見原因見除錯與常見問題。
呼叫的行為
- 合併送出：同一個 microtask 內的呼叫合併成一批送給容器（一批最多 64 個、1 MB，SDK 自動分批）。單一呼叫的參數超過 1 MB 會直接以
INVALID_PARAMS失敗。 - 逾時：預設 30 秒沒有回應就以
TIMEOUT失敗（SDK 端計時）。等使用者操作的呼叫（ui.dialog、ui.actionSheet、share.toChat）不設逾時。http.fetch以timeoutMs為準，SDK 另外以max(30 秒, timeoutMs + 5 秒)保底。 - 頻率：每個小程序平均每秒最多 50 次呼叫，瞬間最多 100 次，超過以
RATE_LIMITED失敗。 - 結果送達：容器約每一幀把結果與事件送回一次；App 在背景時最多延遲 100 ms。
- 重新載入：頁面重新載入後，舊頁面還沒完成的呼叫結果會被丟棄。
事件
| 事件 | 時機 | 訂閱方式 |
|---|---|---|
app.pause | App 退到背景、小程序被關閉（進入保活） | sdk.on('app.pause', cb) |
app.resume | App 回到前景、保活的小程序被打開 | sdk.on('app.resume', cb) |
theme.change | 主題（深淺色、主題色、增強對比）、系統字級、安全區變更 | sdk.theme.onChange(cb) |
容器在你的程式第一次呼叫 SDK 之前不會送事件（先排隊）。