react-native-debug-toolkit/README.zh-CN.md

A simple yet powerful debugging toolkit for React Native with a convenient floating UI for development

# React Native Debug Toolkit 使用文档

一个简单但功能强大的React Native调试工具包，提供便捷的开发期浮动界面。

## 安装

```bash
npm install react-native-debug-toolkit
# 或
yarn add react-native-debug-toolkit
```

### iOS 额外设置

该工具包使用FLEX和DoraemonKit提供iOS调试功能。请按以下步骤正确集成：

1. 确保项目中已安装CocoaPods
2. 在Podfile中添加以下依赖：

```ruby
pod 'FLEX', :configurations => ['Debug']   
pod 'DoraemonKit/Core', :git => 'https://github.com/superzcj/DoKit.git', :configurations => ['Debug'] #必选
```

3. 在`didFinishLaunchingWithOptions`方法中的AppDelegate.m文件中添加以下代码：

```objc
#ifdef DEBUG
#import <DoraemonKit/DoraemonManager.h>
#endif

  #ifdef DEBUG
  DoraemonManager *doKit = [DoraemonManager shareInstance];
  doKit.autoDock = false;
  [doKit install];
  [doKit hiddenDoraemon];
  #endif
```

4. 在iOS目录中运行pod install：

```bash
cd ios && pod install
```

### Android 额外设置

1. 在`android/settings.gradle`中添加以下内容：

```gradle
include ':react-native-debug-toolkit'
project(':react-native-debug-toolkit').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-debug-toolkit/android')
```

2. 在`android/app/build.gradle`中添加以下依赖：

```gradle
dependencies {
    // 其他依赖...
    
    debugImplementation 'io.github.didi.dokit:dokitx:3.7.1'
    releaseImplementation 'io.github.didi.dokit:dokitx-no-op:3.7.1'
    debugImplementation 'com.android.volley:volley:1.2.0'
    
    implementation project(':react-native-debug-toolkit')
}
```

3. 在`MainApplication.kt`中初始化DoKit：

```kotlin
import com.didichuxing.doraemonkit.DoKit 
import com.reactnative.debuglibs.RNDebugLibsPackage

// 在getPackages方法内
add(RNDebugLibsPackage())

 // 在onCreate方法内
if (BuildConfig.DEBUG) {
    DoKit.Builder(this)
        .build()
    DoKit.hide()
}
```

## 使用方法

将调试工具包添加到您的应用程序中非常简单，只需一行代码即可启用所有功能：

```javascript
// 在App.js或其他初始化文件中
import React, { useEffect } from 'react';
import { initializeDebugToolkit, isDebugMode } from 'react-native-debug-toolkit';

function App() {
  useEffect(() => {
    if (isDebugMode) {
      // 使用所有默认功能初始化
      initializeDebugToolkit();
      
      // 或选择特定的内置功能
      // initializeDebugToolkit(['network', 'console', 'zustand', 'navigation', 'thirdPartyLibs']);
    }
    
    return () => {
      // 自动清理
    };
  }, []);
  
  return <YourApp />;
}
```

就这么简单！现在您的应用程序将在开发模式下显示一个浮动的调试面板，让您可以访问所有调试功能。

## 内置功能

通过上面的一行代码初始化，您将自动获得以下所有调试功能：

- **网络监控**：跟踪和检查所有网络请求和响应
- **控制台日志**：在应用内查看所有控制台日志输出
- **Zustand状态**：监控Zustand状态管理（如果您的应用使用Zustand）
- **导航跟踪**：自动记录应用内的导航事件
- **第三方调试工具**：快速访问原生调试工具（iOS的FLEX，iOS和Android的DoraemonKit）

## 集成

### 高级Axios网络跟踪

对于使用Axios的项目，您可以启用更详细的网络请求跟踪：

```javascript
import axios from 'axios';
import { createNetworkFeature, isDebugMode } from 'react-native-debug-toolkit';

// 获取网络功能实例并设置Axios拦截器
if (isDebugMode) {
  const networkFeature = createNetworkFeature();
  networkFeature.setupAxiosInterceptors(axios);
  
  // 可选：排除敏感URL（如认证接口）
  networkFeature.addUrlToBlacklist('api.example.com/auth');
  networkFeature.addUrlToBlacklist(/password/i); // 支持正则表达式
}
```

### 监控Zustand状态（如果您使用Zustand）

如果您的应用使用Zustand进行状态管理，只需添加中间件即可跟踪所有状态变化：

```javascript
import { create } from 'zustand';
import { zustandLogMiddleware } from 'react-native-debug-toolkit';

// 只需添加zustandLogMiddleware来包装您的store
const useStore = create(
  zustandLogMiddleware(
    (set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 })),
      decrement: () => set((state) => ({ count: state.count - 1 })),
    })
  )
);
```

### 导航跟踪（React Navigation）

如果您使用React Navigation，添加导航跟踪只需一步：

```javascript
import React, { useRef } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { useNavigationLogger } from 'react-native-debug-toolkit';

function AppNavigator() {
  const navigationRef = useRef(null);
  
  // 添加这一行来启用导航日志
  useNavigationLogger(navigationRef);
  
  return (
    <NavigationContainer ref={navigationRef}>
      {/* 您的导航配置 */}
    </NavigationContainer>
  );
}
```

## 自定义配置

如果您不需要所有功能，可以选择性地启用特定功能：

```javascript
// 只启用网络和控制台日志功能
initializeDebugToolkit(['network', 'console']);

// 或者指定一组自定义功能
initializeDebugToolkit([
  'network',
  'console', 
  'zustand', 
  'navigation',
  'thirdPartyLibs'
]);
```

## 常见问题排除

### 调试面板不显示
- 确保您在开发模式下（`isDebugMode`为true）
- 检查是否正确调用了`initializeDebugToolkit()`

### iOS功能不工作
- 确认您已将FLEX和DoraemonKit添加到Podfile
- 在修改后重新运行`pod install`
- 确保您正在运行Debug构建版本

### 网络请求未被捕获
- 对于Axios，请确保调用了`setupAxiosInterceptors(axios)`
- 对于fetch请求，工具包会自动拦截，无需额外配置

### 应用性能问题
- 此调试工具包仅适用于开发阶段，请确保生产构建中未包含
- 如果开发模式下性能受影响，可以尝试只启用特定功能