快速入门

目标读者：Mini-App 开发者
SDK 入口：import woo from 'mini-sdk'
运行模型：多 WebView 栈（每个页面独立 WebView 实例）
协议版本：v1 | 更新：2026-04-01

安装 SDK

在模板项目中，mini-sdk 已通过 Vite alias 自动注入，无需手动安装：

// 直接 import 即可
import woo from 'mini-sdk'

如需在自定义项目中使用，请联系 IDE 团队获取内部包地址。

多 WebView 运行模型

Native 为每个页面创建独立的 WebView 实例，页面切换通过压栈/弹栈实现：

导航前                导航后（A → B）
┌──────────┐          ┌──────────┐  ← 当前显示（独立 JS 上下文）
│ WebView A│          │ WebView B│
│ Page A   │          ├──────────┤
└──────────┘          │ WebView A│  ← 后台保活（状态完整保留）
                      └──────────┘

这意味着：

• 每个 WebView 有独立 JS 上下文：模块级变量（如路由回调注册表）不跨页面共享
• 后台页面保活：WebView A 在 B 打开期间保持存活，onBack 回调也不会丢失
• 无需 <keep-alive>：每个页面天然独立，不存在 SPA 的组件复用问题

第一个 API 调用

import woo from 'mini-sdk'

// 显示一条 Toast
await woo.showToast('你好，Mini-SDK！')

// 发起网络请求
const res = await woo.get('https://api.example.com/user')
console.log(res.data)

// 读取本地存储
const { data: token } = await woo.getStorage({ key: 'token' })

调用风格

所有 woo.* 函数同时支持 Promise 和 回调 两种风格：

Promise（推荐）

try {
  const result = await woo.getDeviceInfo()
  console.log(result.model)
} catch (err) {
  console.error(err.code, err.message)
}

回调风格

woo.getDeviceInfo({
  success(res) {
    console.log(res.model)
  },
  fail(err) {
    console.error(err.code, err.message)
  },
  complete() {
    console.log('请求完成')
  },
})

环境检测

import { isSimulator, isNative, detectEnv } from 'mini-sdk'

console.log(detectEnv())   // 'simulator' | 'ios' | 'android' | 'unknown'
console.log(isSimulator()) // true / false
console.log(isNative())    // true / false

下一步

• 📖 阅读 Bridge 工作原理 了解通信机制
• 🔌 查看 Network API 开始发起请求
• 💡 浏览 完整示例 了解实际用法