@xiao-ying/miniapp-sdk

小应移动端官方 Hybrid JS-SDK。Web 页面在 WebView 内直连原生能力；浏览器运行时由 @xiao-ying/miniapp-sdk-browser 提供。

特性

• 桥接核心：App WebView 内直连原生能力
• 浏览器实现拆包：浏览器运行时由独立包提供
• TypeScript 类型完整：全量类型导出，默认挂载全局 xy
• 常用能力覆盖：网络、文件、媒体、剪贴板、UI、路由、存储、分享与鉴权

安装

App WebView 环境：

pnpm add @xiao-ying/miniapp-sdk

浏览器环境（需要额外安装浏览器包）：

pnpm add @xiao-ying/miniapp-sdk @xiao-ying/miniapp-sdk-browser

快速开始

在入口处引入一次，SDK 会自动挂载全局 xy：

import '@xiao-ying/miniapp-sdk'

浏览器运行时需要额外引入浏览器包：

import '@xiao-ying/miniapp-sdk'
import '@xiao-ying/miniapp-sdk-browser'

const res = await xy.request({
  url: '/api/user/info',
  method: 'GET'
})

const unsubscribe = xy.onStorageChange(({ key, newValue }) => {
  console.log('storage changed', key, newValue)
})

const unsubscribeError = xy.onError((info) => {
  console.warn('sdk error', info.method, info.code, info.message)
})

unsubscribe()
unsubscribeError()

运行时配置（可选）

宿主可在页面注入 window.__XY_CONFIG__，用于标识运行模式与宿主信息。以下为常见字段示例（字段类型以 XYNativeConfig 为准）：

<script>
  window.__XY_CONFIG__ = {
    appVersion: '26.3.0',
    engineVersion: '1.9.0',
    platform: 'android',      // ios | android | macos | windows | linux | web
    runtime: 'app',           // app: WebView
    sessionId: '...',
    viewMode: 'fullScreen',   // fullScreen | sheet
    env: {
      school: 'demo-school',
      campus: 'main',
      devMode: true
    },
    mediaQuery: {
      statusBarHeight: 24,
      safeAreaInsets: { top: 24, bottom: 0, left: 0, right: 0 },
      size: { width: 390, height: 844 },
      devicePixelRatio: 3
    },
    brightness: 'light',      // light | dark
    intent: {},
    path: '/',
    isForeground: true,
    manifest: {
      id: 'example',
      name: '小应小程序示例',
      description: '小应官方示例小应小程序',
      iconUrl: 'https://example.com/icon.png',
      channel: 'dev',
      initialPath: '/',
      entryPrefix: '/app/#',
      host: 'example.com',
      protocol: 'https',
      minEngineVersion: '1.9.0',
      permissions: ['network', 'storage'],
      config: {
        showBackButton: true,
        showTitle: true,
        showMenuButton: true,
        useHostSafeArea: false
      }
    }
  }
</script>

运行模式与兼容

• runtime = 'app' 且原生桥接可用时走原生能力。
• 浏览器运行时需引入 @xiao-ying/miniapp-sdk-browser，是否启用由入口导入方式决定。
• 调用前可通过 xy.supports('>=1.9.0') 判断宿主 engine 版本是否满足要求。

API 总览

• 环境与会话：appVersion、engineVersion、sdkVersion、platform、env、sessionId、manifest、runtime、viewMode、mediaQuery、brightness、intent、parentMiniApp、isForeground
• 能力检测：supports
• 网络：request、uploadFile、downloadFile
• WebSocket：ws
• 媒体与工具：pickImage、compressImage、cropImage、pickFile、pickDate、pickTime、scanCode
• 剪贴板：hasClipboardData、getClipboardData、setClipboardData
• UI：showToast、showModal、openMenu、vibrate
• 路由：openUrl、openFile、openMiniApp、exit
• 生命周期：onForeground、onBackground、onStorageChange、onBrightnessChange
• 存储：setStorage、getStorage、removeStorage、clearStorage
• 分享与聊天：setShareHandler、share、chat
• Cookie：getCookies、setCookie、removeCookie、clearCookies
• 鉴权：getAuthState、onAuthStateChange、signIn
• 错误订阅：onError（统一监听参数校验/运行时错误）

相关包

• @xiao-ying/miniapp-request：axios 风格请求封装（request/upload/download 统一管理）
• @xiao-ying/miniapp-hooks：React hooks 封装（brightness/storage 等响应式）
• @xiao-ying/miniapp-cloud-kit：Cloud KV / Snapshot 核心 API
• @xiao-ying/miniapp-cloud-hooks：Cloud KV / Snapshot 的 SWR hooks
• @xiao-ying/miniapp-proxy：开发态跨域代理（配合浏览器运行时）
• @xiao-ying/miniapp-sdk-browser：浏览器运行时实现

文档

• 入门与示例：docs/guide/getting-started.md
• API 能力：docs/guide/api.md
• 文档总览：docs/index.md