@plum-tech/xiaoying-sdk

小应移动端官方 Hybrid JS-SDK。为 Web 页面提供调用原生能力的桥接层，并在浏览器环境下自动提供兜底实现。

📦 安装

pnpm add @plum-tech/xiaoying-sdk

🧭 初始化

1. 在应用入口引入一次，SDK 会自动挂载全局 xy 对象并提供完整的 TypeScript 类型。

import '@plum-tech/xiaoying-sdk'

1. （可选）由原生注入运行时配置，供 SDK 读取宿主信息与运行模式：

<script>
  window.__XY_CONFIG__ = {
    appVersion: '4.8.0',
    platform: 'ios',      // ios | android | macos | windows
    env: 'production',    // development | production
    runtime: 'app'        // app: WebView；不注入时默认 browser
  };
</script>

🚀 API 速览

• 基础字段：xy.appVersion、xy.sdkVersion、xy.platform
• 能力检测：xy.can(schema)，schema 取值 request、uploadFile、downloadFile、pickImage、getClipboardData、setClipboardData、hasClipboardData、showToast、showModal、openUrl、setStorage、getStorage、removeStorage、clearStorage、onStorageChange
• 网络：request（支持 timeout）、uploadFile、downloadFile
• 媒体与剪贴板：pickImage、hasClipboardData、getClipboardData、setClipboardData
• UI：showToast、showModal
• 路由：openUrl（target 支持 internal | external）
• 存储：setStorage、getStorage、removeStorage、clearStorage、onStorageChange

💻 使用示例

网络与文件

// 受控请求，原生拦截或自动降级 fetch
const res = await xy.request({
  url: '/api/v1/user/info',
  method: 'GET',
  timeout: 10_000
});

// 上传文件
await xy.uploadFile({
  url: '/upload/avatar',
  method: 'POST',
  filePath: '/tmp/avatar.png',
  fileKey: 'file',
  formData: { userId: '123' }
});

// 下载文件，原生返回临时路径；浏览器返回 objectURL
const file = await xy.downloadFile({ url: 'https://example.com/report.pdf' });
console.log(file.filePath);

UI 能力

xy.showToast({ title: '操作成功', icon: 'success' });

const modalRes = await xy.showModal({
  title: '温馨提示',
  content: '确认要退出登录吗？',
  showCancel: true
});

媒体与剪贴板

const { filePaths } = await xy.pickImage({ count: 3 });

const hasUrl = await xy.hasClipboardData({ type: 'url' });
const clip = await xy.getClipboardData();
await xy.setClipboardData({ data: 'https://xiaoying.com' });

路由与存储

await xy.openUrl({ url: 'https://m.xiaoying.com/feature', target: 'external' });

await xy.setStorage({ key: 'token', data: 'xxx' });
const { data: token } = await xy.getStorage({ key: 'token' });
await xy.removeStorage({ key: 'token' });
await xy.clearStorage();

// 监听存储变更（原生可通过 window.__XY_DISPATCH__('storageChange', payload) 推送）
const off = xy.onStorageChange(({ key, newValue }) => {
  console.log('storage changed', key, newValue);
});
// off() 取消监听

🛠 开发指南

• 运行模式：runtime = 'app' 且存在 window.flutter_inappwebview 时走原生；否则自动切换浏览器兜底。
• 浏览器兜底策略：
  • request / uploadFile / downloadFile 使用 fetch（含 timeout，上传自动拼装 FormData）
  • showToast 采用 console.info + alert
  • storage 使用 localStorage；onStorageChange 监听浏览器的 storage 事件同步
• 调用前可通过 xy.can(schema) 判断能力是否可用，避免因宿主版本差异导致的报错。

🔧 原生接入要点

• 桥接入口：window.flutter_inappwebview.callHandler(method, args)，SDK 内部统一封装在 callNative 中。
• 运行配置：原生可注入 window.__XY_CONFIG__ 提供宿主版本、平台和运行模式信息。
• 存储同步：若要向 Web 通知存储变更，调用 window.__XY_DISPATCH__('storageChange', { key, oldValue, newValue })，SDK 会转发给 xy.onStorageChange 订阅者。