react-native-kookit 0.1.1 → 0.1.4

package/ANDROID_SETUP.md

@@ -0,0 +1,188 @@
+# Android Setup Guide for react-native-kookit
+
+This guide will help you properly set up volume key interception on Android.
+
+## Why is this needed?
+
+Unlike iOS, Android requires manual implementation in your MainActivity to intercept volume key events. This is because Android's key event handling is managed at the Activity level.
+
+## Step-by-Step Setup
+
+### 1. Locate your MainActivity file
+
+Your MainActivity should be located at:
+
+- `android/app/src/main/java/[your/package/path]/MainActivity.kt` (Kotlin)
+- `android/app/src/main/java/[your/package/path]/MainActivity.java` (Java)
+
+### 2. Update your MainActivity
+
+Choose the appropriate implementation based on your language:
+
+#### Kotlin Implementation
+
+```kotlin
+package com.yourapp.yourpackage  // Replace with your actual package
+
+import android.os.Build
+import android.os.Bundle
+import android.view.KeyEvent
+
+import com.facebook.react.ReactActivity
+import com.facebook.react.ReactActivityDelegate
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
+
+import expo.modules.ReactActivityDelegateWrapper
+import expo.modules.kookit.VolumeKeyInterceptActivity
+import expo.modules.kookit.handleVolumeKeyEvent
+
+class MainActivity : ReactActivity(), VolumeKeyInterceptActivity {
+    private var volumeKeyListener: ((Int) -> Unit)? = null
+    private var isVolumeKeyInterceptEnabled = false
+
+    override fun getMainComponentName(): String = "main"
+
+    override fun createReactActivityDelegate(): ReactActivityDelegate {
+        return ReactActivityDelegateWrapper(
+              this,
+              BuildConfig.IS_NEW_ARCHITECTURE_ENABLED,
+              object : DefaultReactActivityDelegate(
+                  this,
+                  mainComponentName,
+                  fabricEnabled
+              ){})
+    }
+
+    // Volume key interception implementation - REQUIRED
+    override fun setVolumeKeyListener(listener: ((Int) -> Unit)?) {
+        volumeKeyListener = listener
+    }
+
+    override fun setVolumeKeyInterceptEnabled(enabled: Boolean) {
+        isVolumeKeyInterceptEnabled = enabled
+    }
+
+    override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+        if (isVolumeKeyInterceptEnabled && handleVolumeKeyEvent(event)) {
+            return true
+        }
+        return super.dispatchKeyEvent(event)
+    }
+}
+```
+
+#### Java Implementation
+
+```java
+package com.yourapp.yourpackage;  // Replace with your actual package
+
+import android.view.KeyEvent;
+
+import com.facebook.react.ReactActivity;
+import com.facebook.react.ReactActivityDelegate;
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint;
+import com.facebook.react.defaults.DefaultReactActivityDelegate;
+
+import expo.modules.ReactActivityDelegateWrapper;
+import expo.modules.kookit.VolumeKeyInterceptActivity;
+import expo.modules.kookit.VolumeKeyInterceptActivityKt;
+import kotlin.Unit;
+import kotlin.jvm.functions.Function1;
+
+public class MainActivity extends ReactActivity implements VolumeKeyInterceptActivity {
+    private Function1<Integer, Unit> volumeKeyListener;
+    private boolean isVolumeKeyInterceptEnabled = false;
+
+    @Override
+    protected String getMainComponentName() {
+        return "main";
+    }
+
+    @Override
+    protected ReactActivityDelegate createReactActivityDelegate() {
+        return new ReactActivityDelegateWrapper(
+            this,
+            BuildConfig.IS_NEW_ARCHITECTURE_ENABLED,
+            new DefaultReactActivityDelegate(this, getMainComponentName(), DefaultNewArchitectureEntryPoint.getFabricEnabled())
+        );
+    }
+
+    // Volume key interception implementation - REQUIRED
+    @Override
+    public void setVolumeKeyListener(Function1<Integer, Unit> listener) {
+        this.volumeKeyListener = listener;
+    }
+
+    @Override
+    public void setVolumeKeyInterceptEnabled(boolean enabled) {
+        this.isVolumeKeyInterceptEnabled = enabled;
+    }
+
+    @Override
+    public boolean dispatchKeyEvent(KeyEvent event) {
+        if (isVolumeKeyInterceptEnabled && VolumeKeyInterceptActivityKt.handleVolumeKeyEvent(this, event)) {
+            return true;
+        }
+        return super.dispatchKeyEvent(event);
+    }
+}
+```
+
+## Key Points
+
+1. **Package Name**: Make sure to replace `com.yourapp.yourpackage` with your actual package name
+2. **Interface Implementation**: Your MainActivity MUST implement `VolumeKeyInterceptActivity`
+3. **Required Methods**: You must implement all three methods:
+   - `setVolumeKeyListener`
+   - `setVolumeKeyInterceptEnabled`
+   - `dispatchKeyEvent` (override)
+4. **Import Statements**: Make sure all import statements are correct
+
+## Common Issues
+
+### "Unresolved reference" errors
+
+Make sure you have these imports:
+
+```kotlin
+import expo.modules.kookit.VolumeKeyInterceptActivity
+import expo.modules.kookit.handleVolumeKeyEvent
+```
+
+### Volume keys not working
+
+1. Check that your MainActivity implements `VolumeKeyInterceptActivity`
+2. Verify that `dispatchKeyEvent` is properly overridden
+3. Make sure you're calling `enableVolumeKeyInterception()` from JavaScript
+
+### Build errors
+
+1. Clean and rebuild your project: `cd android && ./gradlew clean && cd .. && npx react-native run-android`
+2. Make sure your package name in MainActivity matches your app's package structure
+
+## Testing
+
+After setup, test with this JavaScript code:
+
+```javascript
+import ReactNativeKookit from "react-native-kookit";
+
+// Add listener
+const subscription = ReactNativeKookit.addListener(
+  "onVolumeButtonPressed",
+  (event) => {
+    console.log("Volume button pressed:", event.key);
+  }
+);
+
+// Enable interception
+ReactNativeKookit.enableVolumeKeyInterception();
+
+// Test by pressing volume up/down buttons
+// You should see logs in Metro console
+
+// Clean up when done
+subscription.remove();
+ReactNativeKookit.disableVolumeKeyInterception();
+```

package/EXPO_PLUGIN_README.md

@@ -0,0 +1,136 @@
+# React Native Kookit - Expo Plugin
+
+这个插件可以自动修改您的 MainActivity 以支持音量键拦截功能，无需手动编写代码。
+
+## 自动安装（推荐）
+
+### 1. 安装模块
+
+```bash
+npm install react-native-kookit
+# 或
+yarn add react-native-kookit
+```
+
+### 2. 配置 Expo 插件
+
+在您的 `app.json` 或 `app.config.js` 中添加插件：
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-kookit"]
+  }
+}
+```
+
+### 3. 预构建项目
+
+```bash
+npx expo prebuild --clean
+```
+
+### 4. 构建和运行
+
+```bash
+npx expo run:android
+```
+
+就这样！插件会自动修改您的 MainActivity 以支持音量键拦截。
+
+## 使用方法
+
+```javascript
+import ReactNativeKookit from "react-native-kookit";
+
+// 添加监听器
+const subscription = ReactNativeKookit.addListener(
+  "onVolumeButtonPressed",
+  (event) => {
+    console.log("Volume button pressed:", event.key); // "up" 或 "down"
+  }
+);
+
+// 启用音量键拦截
+ReactNativeKookit.enableVolumeKeyInterception();
+
+// 测试：按音量键，应该在控制台看到日志
+
+// 清理
+subscription.remove();
+ReactNativeKookit.disableVolumeKeyInterception();
+```
+
+## 插件做了什么
+
+插件会自动：
+
+1. **添加必要的导入语句**：
+   - `import android.view.KeyEvent`
+   - `import expo.modules.kookit.VolumeKeyInterceptActivity`
+   - `import expo.modules.kookit.handleVolumeKeyEvent`
+
+2. **修改类声明**：
+
+   ```kotlin
+   class MainActivity : ReactActivity(), VolumeKeyInterceptActivity
+   ```
+
+3. **添加必要的属性和方法**：
+
+   ```kotlin
+   private var volumeKeyListener: ((Int) -> Unit)? = null
+   private var isVolumeKeyInterceptEnabled = false
+
+   override fun setVolumeKeyListener(listener: ((Int) -> Unit)?) {
+       volumeKeyListener = listener
+   }
+
+   override fun setVolumeKeyInterceptEnabled(enabled: Boolean) {
+       isVolumeKeyInterceptEnabled = enabled
+   }
+
+   override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+       if (isVolumeKeyInterceptEnabled && handleVolumeKeyEvent(event)) {
+           return true
+       }
+       return super.dispatchKeyEvent(event)
+   }
+   ```
+
+## 兼容性
+
+- ✅ Expo SDK 49+
+- ✅ React Native 0.70+
+- ✅ 支持 Kotlin 和 Java MainActivity
+- ✅ 支持新架构（Fabric）
+
+## 手动安装（如果不使用 Expo）
+
+如果您不使用 Expo，请参考 [ANDROID_SETUP.md](./ANDROID_SETUP.md) 手动修改 MainActivity。
+
+## 故障排除
+
+### 插件未生效
+
+1. 确保运行了 `npx expo prebuild --clean`
+2. 检查 `android/app/src/main/java/.../MainActivity.kt` 是否包含了修改
+3. 清理并重新构建：`cd android && ./gradlew clean && cd .. && npx expo run:android`
+
+### 构建错误
+
+1. 确保您的 MainActivity 文件格式正确
+2. 检查是否有语法错误
+3. 如果插件修改失败，可以手动按照 ANDROID_SETUP.md 进行修改
+
+## 开发插件
+
+如果您需要修改插件，可以：
+
+```bash
+cd plugin
+npm install
+npm run build
+```
+
+然后重新运行 `npx expo prebuild --clean`。

package/README.md

@@ -1,6 +1,6 @@
 # react-native-kookit
 
-My new module
+A React Native module for intercepting volume button presses on both iOS and Android platforms.
 
 # API documentation
 
@@ -23,13 +23,229 @@ npm install react-native-kookit
 
 ### Configure for Android
 
+#### Step 1: Update MainActivity
+
+Your `MainActivity.kt` (or `MainActivity.java`) needs to implement the `VolumeKeyInterceptActivity` interface and override the `dispatchKeyEvent` method.
+
+**For Kotlin (MainActivity.kt):**
+
+```kotlin
+package com.yourapp.yourpackage
+
+import android.os.Build
+import android.os.Bundle
+import android.view.KeyEvent
+
+import com.facebook.react.ReactActivity
+import com.facebook.react.ReactActivityDelegate
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
+import com.facebook.react.defaults.DefaultReactActivityDelegate
+
+import expo.modules.ReactActivityDelegateWrapper
+import expo.modules.kookit.VolumeKeyInterceptActivity
+import expo.modules.kookit.handleVolumeKeyEvent
+
+class MainActivity : ReactActivity(), VolumeKeyInterceptActivity {
+    private var volumeKeyListener: ((Int) -> Unit)? = null
+    private var isVolumeKeyInterceptEnabled = false
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        // Set the theme to AppTheme BEFORE onCreate to support
+        // coloring the background, status bar, and navigation bar.
+        // This is required for expo-splash-screen.
+        setTheme(R.style.AppTheme);
+        super.onCreate(null)
+    }
+
+    /**
+     * Returns the name of the main component registered from JavaScript.
+     */
+    override fun getMainComponentName(): String = "main"
+
+    /**
+     * Returns the instance of the [ReactActivityDelegate].
+     */
+    override fun createReactActivityDelegate(): ReactActivityDelegate {
+        return ReactActivityDelegateWrapper(
+              this,
+              BuildConfig.IS_NEW_ARCHITECTURE_ENABLED,
+              object : DefaultReactActivityDelegate(
+                  this,
+                  mainComponentName,
+                  fabricEnabled
+              ){})
+    }
+
+    /**
+      * Align the back button behavior with Android S
+      */
+    override fun invokeDefaultOnBackPressed() {
+        if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.R) {
+            if (!moveTaskToBack(false)) {
+                super.invokeDefaultOnBackPressed()
+            }
+            return
+        }
+        super.invokeDefaultOnBackPressed()
+    }
+
+    // Volume key interception implementation
+    override fun setVolumeKeyListener(listener: ((Int) -> Unit)?) {
+        volumeKeyListener = listener
+    }
+
+    override fun setVolumeKeyInterceptEnabled(enabled: Boolean) {
+        isVolumeKeyInterceptEnabled = enabled
+    }
+
+    override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+        if (isVolumeKeyInterceptEnabled && handleVolumeKeyEvent(event)) {
+            return true
+        }
+        return super.dispatchKeyEvent(event)
+    }
+}
+```
 
-
+**For Java (MainActivity.java):**
+
+```java
+package com.yourapp.yourpackage;
+
+import android.os.Build;
+import android.os.Bundle;
+import android.view.KeyEvent;
+
+import com.facebook.react.ReactActivity;
+import com.facebook.react.ReactActivityDelegate;
+import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint;
+import com.facebook.react.defaults.DefaultReactActivityDelegate;
+
+import expo.modules.ReactActivityDelegateWrapper;
+import expo.modules.kookit.VolumeKeyInterceptActivity;
+import expo.modules.kookit.VolumeKeyInterceptActivityKt;
+import kotlin.Unit;
+import kotlin.jvm.functions.Function1;
+
+public class MainActivity extends ReactActivity implements VolumeKeyInterceptActivity {
+    private Function1<Integer, Unit> volumeKeyListener;
+    private boolean isVolumeKeyInterceptEnabled = false;
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        setTheme(R.style.AppTheme);
+        super.onCreate(null);
+    }
+
+    @Override
+    protected String getMainComponentName() {
+        return "main";
+    }
+
+    @Override
+    protected ReactActivityDelegate createReactActivityDelegate() {
+        return new ReactActivityDelegateWrapper(
+            this,
+            BuildConfig.IS_NEW_ARCHITECTURE_ENABLED,
+            new DefaultReactActivityDelegate(this, getMainComponentName(), DefaultNewArchitectureEntryPoint.getFabricEnabled())
+        );
+    }
+
+    @Override
+    public void invokeDefaultOnBackPressed() {
+        if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.R) {
+            if (!moveTaskToBack(false)) {
+                super.invokeDefaultOnBackPressed();
+            }
+            return;
+        }
+        super.invokeDefaultOnBackPressed();
+    }
+
+    @Override
+    public void setVolumeKeyListener(Function1<Integer, Unit> listener) {
+        this.volumeKeyListener = listener;
+    }
+
+    @Override
+    public void setVolumeKeyInterceptEnabled(boolean enabled) {
+        this.isVolumeKeyInterceptEnabled = enabled;
+    }
+
+    @Override
+    public boolean dispatchKeyEvent(KeyEvent event) {
+        if (isVolumeKeyInterceptEnabled && VolumeKeyInterceptActivityKt.handleVolumeKeyEvent(this, event)) {
+            return true;
+        }
+        return super.dispatchKeyEvent(event);
+    }
+}
+```
 
 ### Configure for iOS
 
 Run `npx pod-install` after installing the npm package.
 
+## Usage
+
+```typescript
+import ReactNativeKookit from "react-native-kookit";
+
+// Add event listener for volume button presses
+ReactNativeKookit.addListener("onVolumeButtonPressed", (event) => {
+  console.log("Volume button pressed:", event.key); // 'up' or 'down'
+});
+
+// Enable volume key interception
+ReactNativeKookit.enableVolumeKeyInterception();
+
+// Later, when you want to disable it
+ReactNativeKookit.disableVolumeKeyInterception();
+
+// Don't forget to remove listeners when component unmounts
+const subscription = ReactNativeKookit.addListener(
+  "onVolumeButtonPressed",
+  handler
+);
+// Later: subscription.remove();
+```
+
+## API
+
+### Methods
+
+- `enableVolumeKeyInterception()` - Enable volume button interception
+- `disableVolumeKeyInterception()` - Disable volume button interception
+- `hello()` - Returns a greeting string (for testing)
+- `setValueAsync(value: string)` - Test async function
+
+### Events
+
+- `onVolumeButtonPressed` - Fired when volume button is pressed
+  - `event.key` - Either 'up' or 'down'
+
+### Constants
+
+- `PI` - The value of π (for testing)
+
+## Troubleshooting
+
+### Android
+
+If volume key interception is not working on Android:
+
+1. Make sure your `MainActivity` implements `VolumeKeyInterceptActivity` interface
+2. Make sure you override `dispatchKeyEvent` method correctly
+3. Ensure you're calling `handleVolumeKeyEvent` in the `dispatchKeyEvent` method
+
+### iOS
+
+Volume key interception should work automatically on iOS after installation.
+
+## Example
+
+See the `example` directory for a complete working example.
+
 # Contributing
 
-Contributions are very welcome! Please refer to guidelines described in the [contributing guide]( https://github.com/expo/expo#contributing).
+Contributions are very welcome! Please refer to guidelines described in the [contributing guide](https://github.com/expo/expo#contributing).

package/README_NEW.md

@@ -0,0 +1,143 @@
+# React Native Kookit - 零配置音量键拦截
+
+🎉 **现在支持零配置安装！** 使用 Expo 插件自动处理所有原生代码修改。
+
+## 快速开始
+
+### 方法一：自动安装（推荐 - Expo 项目）
+
+```bash
+# 1. 安装
+npm install react-native-kookit
+
+# 2. 添加到 app.json
+{
+  "expo": {
+    "plugins": ["react-native-kookit"]
+  }
+}
+
+# 3. 预构建
+npx expo prebuild --clean
+
+# 4. 运行
+npx expo run:android
+```
+
+### 方法二：手动安装（React Native CLI 项目）
+
+如果不使用 Expo，请按照 [ANDROID_SETUP.md](./ANDROID_SETUP.md) 手动修改 MainActivity。
+
+## 使用示例
+
+```javascript
+import React, { useEffect } from "react";
+import { View, Text, Alert } from "react-native";
+import ReactNativeKookit from "react-native-kookit";
+
+export default function App() {
+  useEffect(() => {
+    // 添加音量键监听器
+    const subscription = ReactNativeKookit.addListener(
+      "onVolumeButtonPressed",
+      (event) => {
+        Alert.alert(
+          "音量键按下",
+          `按下了${event.key === "up" ? "音量+" : "音量-"}键`,
+          [{ text: "确定" }]
+        );
+      }
+    );
+
+    // 启用音量键拦截
+    ReactNativeKookit.enableVolumeKeyInterception();
+
+    // 清理函数
+    return () => {
+      subscription.remove();
+      ReactNativeKookit.disableVolumeKeyInterception();
+    };
+  }, []);
+
+  return (
+    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+      <Text style={{ fontSize: 18, textAlign: "center", margin: 20 }}>
+        音量键拦截已启用{"\n"}
+        请按音量键测试功能
+      </Text>
+    </View>
+  );
+}
+```
+
+## API 文档
+
+### `enableVolumeKeyInterception()`
+
+启用音量键拦截功能。
+
+### `disableVolumeKeyInterception()`
+
+禁用音量键拦截功能。
+
+### `addListener(eventName, callback)`
+
+添加事件监听器。
+
+**参数：**
+
+- `eventName`: `'onVolumeButtonPressed'`
+- `callback`: `(event: {key: 'up' | 'down'}) => void`
+
+**返回：** 订阅对象，调用 `.remove()` 方法可取消监听。
+
+## 功能特性
+
+- ✅ **零配置**：Expo 插件自动修改原生代码
+- ✅ **跨平台**：支持 iOS 和 Android
+- ✅ **高性能**：原生实现，无性能损耗
+- ✅ **类型安全**：完整 TypeScript 支持
+- ✅ **兼容性强**：支持新架构和旧架构
+
+## 支持的平台
+
+- iOS 9.0+
+- Android API 21+
+- Expo SDK 49+
+- React Native 0.70+
+
+## 常见问题
+
+### Q: 为什么需要 `npx expo prebuild --clean`？
+
+A: 插件需要修改原生 Android 代码，prebuild 会应用所有插件修改。
+
+### Q: 遇到 "Plugin is an unexpected type: undefined" 错误怎么办？
+
+A:
+
+1. 确保已正确安装：`npm install react-native-kookit`
+2. 清理重装：`rm -rf node_modules && npm install`
+3. 重新预构建：`npx expo prebuild --clean`
+
+详细故障排除请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+
+### Q: 音量键无响应怎么办？
+
+A:
+
+1. 确认已调用 `enableVolumeKeyInterception()`
+2. 检查是否正确添加了事件监听器
+3. 在 Android 上确认 MainActivity 已被正确修改
+
+### Q: 支持 React Native CLI 项目吗？
+
+A: 支持，但需要手动修改 MainActivity，请参考 [ANDROID_SETUP.md](./ANDROID_SETUP.md)。
+
+### Q: 会影响系统音量调节吗？
+
+A: 当启用拦截时，会阻止系统音量调节。禁用拦截后恢复正常。
+
+## License
+
+MIT © [troyeguo](https://github.com/troyeguo)