1k-cross-platform

跨平台开发

在 OneKey 中编写平台专属代码的模式。

平台扩展名

使用平台扩展名实现平台专属功能：

扩展名	平台
.native.ts	React Native（iOS/Android）
.web.ts	Web 平台
.desktop.ts	桌面端（Electron）
.ext.ts	浏览器扩展

平台检测

始终使用 platformEnv 检测平台：

// ✅ CORRECT
import platformEnv from '@onekeyhq/shared/src/platformEnv';

if (platformEnv.isNative) {
  // React Native specific code
}

if (platformEnv.isWeb) {
  // Web specific code
}

if (platformEnv.isDesktop) {
  // Desktop (Electron) specific code
}

if (platformEnv.isExtension) {
  // Browser extension specific code
}

// ❌ FORBIDDEN - Direct platform checks
if (typeof window !== 'undefined') { }
if (process.env.REACT_APP_PLATFORM === 'web') { }

可用的平台标志

platformEnv.isNative      // React Native (iOS or Android)
platformEnv.isWeb         // Web browser
platformEnv.isDesktop     // Electron desktop app
platformEnv.isExtension   // Browser extension
platformEnv.isIOS         // iOS specifically
platformEnv.isAndroid     // Android specifically
platformEnv.isWebEmbed    // Embedded web components

平台专属文件结构

MyComponent/
├── index.ts              # Main entry, common logic
├── MyComponent.tsx       # Shared component
├── MyComponent.native.tsx    # React Native specific
├── MyComponent.web.tsx       # Web specific
├── MyComponent.desktop.tsx   # Desktop specific
└── MyComponent.ext.tsx       # Extension specific

打包工具会根据平台自动解析正确的文件。

示例：平台专属存储

// storage.ts - shared interface
export interface IStorage {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
}

// storage.native.ts
import AsyncStorage from '@react-native-async-storage/async-storage';

export const storage: IStorage = {
  get: (key) => AsyncStorage.getItem(key),
  set: (key, value) => AsyncStorage.setItem(key, value),
};

// storage.web.ts
export const storage: IStorage = {
  get: async (key) => localStorage.getItem(key),
  set: async (key, value) => localStorage.setItem(key, value),
};

// storage.desktop.ts
import { ipcRenderer } from 'electron';

export const storage: IStorage = {
  get: (key) => ipcRenderer.invoke('storage:get', key),
  set: (key, value) => ipcRenderer.invoke('storage:set', key, value),
};

详细指南

如需了解全面的跨平台模式和平台注意事项，请参阅 cross-platform.md。

如需了解当前开发工具和最低平台版本，请参阅 platform-requirements.md。在依赖这些版本值之前，请对照所引用的仓库文件进行核实。

涵盖的主题：

• 平台扩展名和文件结构
• 使用 platformEnv 进行平台检测
• 平台专属导入
• 平台注意事项（扩展、移动端、桌面端、Web）
• 实际示例
• 跨平台检查清单

平台注意事项

扩展（Chrome、Firefox、Edge、Brave）

• MV3/服务工作线程生命周期、权限、CSP、后台脚本限制

移动端（iOS/Android）

• WebView 限制、原生模块、后台/前台状态、深度链接

桌面端（Electron）

• 安全边界、IPC 通信、文件系统访问

Web

• CORS 限制、存储限制、XSS 防护、包体积

检查清单

• 平台专属代码使用正确的文件扩展名
• 使用 platformEnv，而不是直接进行检测
• 将通用逻辑提取到共享文件中
• 在所有目标平台上进行测试

相关技能

• /1k-coding-patterns - 通用编码模式
• /1k-architecture - 项目结构和导入