@jincheng_1995/react-native-device-info-plus 1.0.0

package/.kiro/steering/rn-plugin-development.md

@@ -0,0 +1,456 @@
+---
+inclusion: always
+---
+
+# React Native 插件开发指南
+
+本文档提供 React Native 原生模块/插件开发的完整指南，适用于新架构（Turbo Modules）。
+
+## 项目结构
+
+```
+react-native-xxx-plugin/
+├── src/                          # TypeScript 源代码
+│   ├── index.tsx                 # 主入口，导出 API
+│   └── NativeXxx.ts             # Turbo Module 接口定义
+├── ios/                          # iOS 原生实现
+│   ├── Xxx.h                    # Objective-C 头文件
+│   ├── Xxx.mm                   # Objective-C++ 实现
+│   └── Xxx.podspec              # CocoaPods 配置
+├── android/                      # Android 原生实现
+│   ├── build.gradle             # Gradle 构建配置
+│   └── src/main/
+│       ├── AndroidManifest.xml  # 权限声明
+│       └── java/com/xxx/
+│           ├── XxxModule.kt     # 主模块实现
+│           └── XxxPackage.kt    # 模块注册
+├── lib/                          # 编译输出目录
+├── example/                      # 示例应用
+├── package.json                  # npm 配置
+├── tsconfig.json                 # TypeScript 配置
+└── tsconfig.build.json          # 构建配置
+```
+
+## 开发步骤
+
+### 1. TypeScript 接口定义
+
+在 `src/NativeXxx.ts` 中定义 Turbo Module 接口：
+
+```typescript
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // 同步方法
+  methodName(param: string): void;
+  
+  // 异步方法（返回 Promise）
+  asyncMethod(param: number): Promise<string>;
+  
+  // 复杂类型
+  getInfo(): Promise<InfoObject>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('ModuleName');
+```
+
+### 2. TypeScript 实现层
+
+在 `src/index.tsx` 中封装原生模块：
+
+```typescript
+import { NativeEventEmitter } from 'react-native';
+import NativeXxx from './NativeXxx';
+
+class XxxModule {
+  async asyncMethod(param: number): Promise<string> {
+    return NativeXxx.asyncMethod(param);
+  }
+  
+  methodName(param: string): void {
+    NativeXxx.methodName(param);
+  }
+}
+
+export default new XxxModule();
+```
+
+### 3. iOS 原生实现
+
+#### 头文件 (Xxx.h)
+
+```objective-c
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+#ifdef RCT_NEW_ARCH_ENABLED
+#import "RNXxxSpec.h"
+@interface Xxx : RCTEventEmitter <NativeXxxSpec>
+#else
+@interface Xxx : RCTEventEmitter <RCTBridgeModule>
+#endif
+
+@end
+```
+
+#### 实现文件 (Xxx.mm)
+
+```objective-c
+#import "Xxx.h"
+
+@implementation Xxx
+
+RCT_EXPORT_MODULE()
+
+// 同步方法
+RCT_EXPORT_METHOD(methodName:(NSString *)param) {
+    // 实现代码
+}
+
+// 异步方法
+RCT_EXPORT_METHOD(asyncMethod:(double)param
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    // 实现代码
+    resolve(@"result");
+}
+
+// 新架构支持
+#ifdef RCT_NEW_ARCH_ENABLED
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+    return std::make_shared<facebook::react::NativeXxxSpecJSI>(params);
+}
+#endif
+
+@end
+```
+
+#### CocoaPods 配置 (Xxx.podspec)
+
+```ruby
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "../package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "Xxx"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :git => package["repository"], :tag => "#{s.version}" }
+  s.source_files = "*.{h,m,mm}"
+  
+  if ENV['RCT_NEW_ARCH_ENABLED'] == '1' then
+    s.compiler_flags = "-DRCT_NEW_ARCH_ENABLED=1"
+    s.pod_target_xcconfig = {
+      "HEADER_SEARCH_PATHS" => "\"$(PODS_ROOT)/boost\"",
+      "CLANG_CXX_LANGUAGE_STANDARD" => "c++17"
+    }
+    s.dependency "React-Codegen"
+    s.dependency "RCT-Folly"
+    s.dependency "RCTRequired"
+    s.dependency "RCTTypeSafety"
+    s.dependency "ReactCommon/turbomodule/core"
+  end
+  
+  s.dependency "React-Core"
+end
+```
+
+### 4. Android 原生实现
+
+#### 模块实现 (XxxModule.kt)
+
+```kotlin
+package com.xxx
+
+import com.facebook.react.bridge.*
+
+class XxxModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String {
+        return "Xxx"
+    }
+
+    @ReactMethod
+    fun methodName(param: String) {
+        // 实现代码
+    }
+
+    @ReactMethod
+    fun asyncMethod(param: Double, promise: Promise) {
+        try {
+            val result = "result"
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("ERROR", "Error message", e)
+        }
+    }
+}
+```
+
+#### 包注册 (XxxPackage.kt)
+
+```kotlin
+package com.xxx
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class XxxPackage : ReactPackage {
+    override fun createNativeModules(
+        reactContext: ReactApplicationContext
+    ): List<NativeModule> {
+        return listOf(XxxModule(reactContext))
+    }
+
+    override fun createViewManagers(
+        reactContext: ReactApplicationContext
+    ): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}
+```
+
+#### Gradle 配置 (build.gradle)
+
+```gradle
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath "com.android.tools.build:gradle:7.4.2"
+  }
+}
+
+apply plugin: "com.android.library"
+
+def isNewArchitectureEnabled() {
+  return project.hasProperty("newArchEnabled") && 
+         project.newArchEnabled == "true"
+}
+
+android {
+  compileSdkVersion 33
+  defaultConfig {
+    minSdkVersion 21
+    targetSdkVersion 33
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-native:+"
+}
+```
+
+### 5. package.json 配置
+
+```json
+{
+  "name": "react-native-xxx",
+  "version": "1.0.0",
+  "description": "描述",
+  "main": "lib/commonjs/index",
+  "module": "lib/module/index",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index",
+  "source": "src/index",
+  "scripts": {
+    "typescript": "tsc --noEmit",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "prepare": "bob build"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.73.0",
+    "react": "18.2.0",
+    "react-native": "0.73.0",
+    "react-native-builder-bob": "^0.23.0",
+    "typescript": "^5.3.0"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      ["typescript", { "project": "tsconfig.build.json" }]
+    ]
+  },
+  "codegenConfig": {
+    "name": "RNXxxSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.xxx"
+    }
+  }
+}
+```
+
+## 常用功能实现
+
+### 事件发送（原生 → JS）
+
+#### iOS
+```objective-c
+@interface Xxx : RCTEventEmitter
+@end
+
+@implementation Xxx
+
+- (NSArray<NSString *> *)supportedEvents {
+    return @[@"onEvent"];
+}
+
+- (void)sendEvent {
+    [self sendEventWithName:@"onEvent" body:@{@"data": @"value"}];
+}
+
+@end
+```
+
+#### Android
+```kotlin
+private fun sendEvent(eventName: String, params: WritableMap) {
+    reactApplicationContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit(eventName, params)
+}
+```
+
+#### TypeScript
+```typescript
+const eventEmitter = new NativeEventEmitter(NativeModules.Xxx);
+const subscription = eventEmitter.addListener('onEvent', (data) => {
+  console.log(data);
+});
+
+// 取消监听
+subscription.remove();
+```
+
+### 权限处理
+
+#### iOS (Info.plist)
+```xml
+<key>NSCameraUsageDescription</key>
+<string>需要访问相机</string>
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>需要访问位置</string>
+```
+
+#### Android (AndroidManifest.xml)
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+### 线程处理
+
+#### iOS - 主线程执行
+```objective-c
+dispatch_async(dispatch_get_main_queue(), ^{
+    // UI 操作
+});
+```
+
+#### Android - 主线程执行
+```kotlin
+currentActivity?.runOnUiThread {
+    // UI 操作
+}
+```
+
+## 调试技巧
+
+### iOS 调试
+```bash
+# 查看日志
+npx react-native log-ios
+
+# 清理构建
+cd ios && rm -rf Pods && pod install
+```
+
+### Android 调试
+```bash
+# 查看日志
+npx react-native log-android
+
+# 清理构建
+cd android && ./gradlew clean
+```
+
+### TypeScript 类型检查
+```bash
+npm run typescript
+```
+
+## 常见问题
+
+### 1. 模块未找到
+- iOS: 确保运行了 `pod install`
+- Android: 检查 `MainApplication` 中是否注册了包
+- 重新构建: `npm run prepare`
+
+### 2. 类型错误
+- 确保 `tsconfig.json` 中 `types` 包含 `"react-native"`
+- 运行 `npm install` 安装类型定义
+
+### 3. 新架构不工作
+- 确保 RN 版本 >= 0.68
+- iOS: 在 Podfile 中设置 `ENV['RCT_NEW_ARCH_ENABLED'] = '1'`
+- Android: 在 gradle.properties 中设置 `newArchEnabled=true`
+
+## 发布流程
+
+```bash
+# 1. 构建
+npm run prepare
+
+# 2. 测试
+npm run typescript
+npm run lint
+
+# 3. 更新版本
+npm version patch  # 或 minor, major
+
+# 4. 发布
+npm publish
+```
+
+## 最佳实践
+
+1. **类型安全**: 始终使用 TypeScript 定义接口
+2. **错误处理**: Promise 方法要正确处理 reject
+3. **内存管理**: 及时清理监听器和定时器
+4. **权限检查**: 使用敏感功能前检查权限
+5. **文档完善**: 提供清晰的 README 和示例代码
+6. **版本兼容**: 明确支持的 RN 版本范围
+
+## 参考资源
+
+- [React Native 新架构文档](https://reactnative.dev/docs/the-new-architecture/landing-page)
+- [Turbo Modules 指南](https://reactnative.dev/docs/the-new-architecture/pillars-turbomodules)
+- [iOS 开发文档](https://developer.apple.com/documentation/)
+- [Android 开发文档](https://developer.android.com/docs)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.