用途:为 OneKey 项目提供跨平台开发模式,适用于编写平台特定代码、处理平台差异或按平台组织文件时参考。
主要能力:
- 平台扩展名约定:.native.ts 对应 React Native(iOS/Android),.web.ts 对应 Web,.desktop.ts 对应桌面(Electron),.ext.ts 对应浏览器扩展;打包器会按平台自动解析正确文件。
- 平台检测:要求始终使用 platformEnv,禁止直接检查(如 typeof window !== 'undefined' 或 process.env.REACT_APP_PLATFORM)。可用标志包括 isNative、isWeb、isDesktop、isExtension、isIOS、isAndroid、isWebEmbed。
- 文件结构:组件目录可含 index.ts(公共逻辑)、共享组件文件及各平台后缀文件。
- 示例:以存储接口 IStorage 演示 native 用 AsyncStorage、web 用 localStorage、desktop 用 ipcRenderer 分别实现。
使用方式:按平台后缀命名文件,公共逻辑抽到共享文件;检测平台时导入 platformEnv from '@onekeyhq/shared/src/platformEnv' 并使用对应标志。
适用场景:需要为扩展、移动端、桌面端、Web 分别实现或适配功能时。
限制与注意事项:扩展需关注 MV3/service worker 生命周期、权限、CSP 与后台脚本限制;移动端需注意 WebView 限制、原生模块、前后台状态与深链;桌面端需注意安全边界、IPC 通信与文件系统访问;Web 需注意 CORS、存储限制、XSS 防护与包体积。清单要求平台代码使用正确扩展名、使用 platformEnv、公共逻辑抽离并在所有目标平台测试。相关技能:/1k-coding-patterns、/1k-architecture。