用途:为 OneKey 项目提供跨平台开发规范,适用于编写平台特定代码、处理平台差异以及理解平台扩展机制。
主要能力:
- 平台扩展文件命名:.native.ts 用于 React Native(iOS/Android),.web.ts 用于 Web,.desktop.ts 用于桌面,.ext.ts 用于浏览器扩展。打包器会根据平台自动解析对应文件。
- 平台检测:使用 import platformEnv from '@onekeyhq/shared/src/platformEnv',通过 platformEnv.isNative、isWeb、isDesktop、isExtension 判断当前平台。
- 推荐的文件结构:组件目录下放置 index.ts(入口与公共逻辑)、共享组件文件,以及各平台专用文件。
使用方式:在需要区分平台时,优先使用 platformEnv 而非直接检查 window 或 process.env;平台特定实现放入对应扩展名文件,公共逻辑保持独立。
关键原则:UI 组件应在所有平台表现一致;平台特定代码隔离到独立文件;尽量减少平台特定代码;在所有目标平台测试。
平台注意事项:扩展需考虑 MV3/service worker 生命周期、权限与 CSP、后台脚本限制、跨域限制;移动端需考虑 WebView 限制、原生模块、前后台状态、深度链接;桌面(Electron)需考虑安全边界、IPC 通信、nodeIntegration 设置、文件系统访问;Web 需考虑 CORS、存储限制(localStorage、IndexedDB)、XSS 防护、包体积优化。
限制:资料未提供具体安装命令、版本要求或完整 API 列表。