Usage / 使用指南
Integration Methods / 集成方式
1. One-Line Integration (Recommended) / 一行代码集成（推荐）
void main() {
ZeroInspectorKit.runAppWithInspector(const MyApp());
}This method:
- Auto-initializes inspector / 自动初始化检查器
- Captures
print()via Zone / 通过 Zone 捕获 print() - Displays floating button via Overlay / 通过 Overlay 显示悬浮按钮
- Auto-injects route observer / 自动注入路由观察者
2. Two-Line Integration / 两行代码集成
void main() {
ZeroInspectorKit.init();
runApp(ZeroInspectorKit.wrapApp(const MyApp()));
}Inspector Panel / 检查器面板
The inspector panel contains 10 tabs (as of v1.12.0):
检查器面板包含 10 个标签页（v1.12.0 起）：
| Tab | Icon | Feature |
|---|---|---|
| Network | 🌐 | HTTP request viewing + interceptor rules / 网络请求查看 + 拦截修改 |
| Logs | 📝 | Log viewing with level filter / 日志查看 |
| Errors | 🚨 | Aggregated & deduped crash viewing / 去重聚合的异常查看 |
| Database | 💾 | Database and table inspection / 数据库查看 |
| Memory | 📊 | Memory trend, Dart Heap, Native memory, leak detection / 内存趋势、Dart Heap、Native 内存、泄漏检测 |
| FPS | 🎯 | Real-time FPS, jank rate, trend chart, plus main-thread blocking watchdog / 实时 FPS、卡顿率、趋势图，以及主线程阻塞看门狗 |
| Routes | 🧭 | Route navigation tracking / 路由追踪 |
| Timeline | 🧵 | Unified session timeline: network / logs / errors / routes / alerts merged into one stream, with ±N-second focus / 统一会话时间线：网络/日志/异常/路由/告警按时间归并，支持 ±N 秒聚焦 |
| Widgets | 🔍 | Widget tree snapshot for the current route / 当前路由的 Widget 树快照 |
| Alerts | 🔔 | Rule-based alerts with unread badge / 基于规则的告警与未读角标 |
The Memory and FPS monitors are off by default to avoid performance overhead. Toggle the switch at the top of each panel to start collecting data.
Memory 与 FPS 监控默认关闭以避免性能开销。在各自面板顶部打开开关才会开始采集数据。
One-Click Bug Report / 一键 Bug 报告
Tap the bug icon in the inspector panel header to generate and share a bug report in one tap — ideal for QA to attach environment context when filing issues.
点击检查器面板头部的虫子图标，即可一键生成并分享一份 Bug 报告——非常适合 QA 在提 issue 时附上环境上下文。
The shared text snapshot includes / 分享的文本快照包含：
- Device / 设备: real model (e.g.
Pixel 8 Pro/iPhone (iPhone16,1)), OS & version, locale, Dart runtime, CPU cores. - Memory / 内存: current heap usage and whether Native memory is supported.
- Recent logs / 最近日志: the latest captured log entries.
- Recent network / 最近网络: the latest captured requests.
Sensitive headers are masked the same way as in the Network tab. No data leaves the device except through the share target you choose.
敏感请求头会与网络标签页一样被遮蔽。除你选择的分享目标外，数据不会离开设备。
Requires no extra setup — it works as soon as the inspector is running. / 无需额外配置——检查器运行后即可使用。
Floating Button / 悬浮按钮
- The floating button appears after 1 second delay / 悬浮按钮延迟 1 秒出现
- Drag to move it along the screen edge / 拖动 可沿屏幕边缘移动
- Tap (when fully visible) to open/close the inspector panel / 点击（完全可见时）打开/关闭检查器面板
- Button auto-snaps to the nearest screen edge / 按钮自动吸附到最近的屏幕边缘
- Breathing animation when idle / 空闲时有呼吸动画
Edge Docking (since v1.2.0) / 边缘吸附（v1.2.0 起）
When released near a screen edge, the button auto-docks and tucks into the edge, leaving only a 24px peek visible:
拖动松手后，按钮会自动吸附到最近边缘并”收入”边缘，仅露出 24px 小弧边：
| State | Behavior / 行为 |
|---|---|
| Docked (tucked in) | Only 24px peek visible; icon becomes a directional chevron (left dock → ➡, right dock → ⬅) hinting at tap-to-pull-out / 仅露出 24px；图标变为方向箭头提示可点击拉出 |
| Tap docked peek | Smoothly pulls out to fully visible (panel NOT opened, avoids accidental open) / 平滑拉出到完全可见（不打开面板，避免误触） |
| Tap fully visible | Opens the inspector panel / 打开检查器面板 |
This design avoids conflicts with system back gestures (Android/iOS edge swipe to go back) when pulling out from the docked state.
此设计避免了从吸附态拖出时与系统返回手势（Android/iOS 边缘右滑退出）的冲突。
Search / 搜索
The main viewers support fuzzy search:
各查看器均支持模糊搜索：
| Viewer | Search Scope |
|---|---|
| Network | URL, HTTP method / URL、请求方法 |
| Logs | Message, tag / 消息、标签 |
| Errors | Exception type, message / 异常类型、消息 |
| Database (global) | Database name, table name / 数据库名、表名 |
| Database (in-database) | Table name, all column data / 表名、所有列数据 |
Manual Logging (Optional) / 手动记录日志（可选）
The inspector auto-captures print() output. You can also use manual log methods for precise level control:
检查器会自动捕获 print() 输出。也可以使用手动日志方法进行精确级别控制：
Quick shorthand (recommended) / 简化写法（推荐）:
InspectorLog.v('Verbose log / 详细日志');
InspectorLog.d('Debug log / 调试日志');
InspectorLog.i('Info log / 信息日志');
InspectorLog.w('Warning log / 警告日志');
InspectorLog.e('Error log / 错误日志');Full form / 完整写法:
InspectorLogInterceptor.instance.verbose('Verbose log / 详细日志');
InspectorLogInterceptor.instance.debug('Debug log / 调试日志');
InspectorLogInterceptor.instance.info('Info log / 信息日志');
InspectorLogInterceptor.instance.warning('Warning log / 警告日志');
InspectorLogInterceptor.instance.error('Error log / 错误日志');Third-Party Log Integration / 第三方日志库集成
No configuration needed! The plugin automatically captures logs from third-party logging libraries (e.g., logger, flutter_logger) that use print() or debugPrint().
无需配置！ 插件会自动捕获所有使用 print() 的第三方日志库的日志。
These logs are categorized as INFO level.
这些日志统一归类为 INFO 级别。
Bidirectional Sync (Optional) / 双向同步（可选）
To sync inspector-captured logs to your third-party logger:
将检查器捕获的日志同步到第三方日志库：
InspectorLogInterceptor.instance.onLogCaptured = (entry) {
yourLogger.log(entry.message);
};Feature Pages / 功能详情
- Network Inspector — Network request details + interceptor rules / 网络检查器详情 + 拦截修改
- Log Viewer — Log viewing details / 日志查看器详情
- Errors — Aggregated error viewing / 异常聚合查看
- Database Viewer — Database inspection details / 数据库查看器详情
- Route Tracker — Route tracking details / 路由追踪详情
- Memory Viewer — Memory monitoring & leak detection / 内存监控与泄漏检测
- FPS Viewer — FPS monitoring & jank detection / FPS 监控与卡顿检测
Session Persistence / 会话持久化
Logs, network requests, and aggregated errors are asynchronously flushed to a local SQLite ring buffer. On the next launch, logs and aggregated errors replay into their tabs; network requests stay archived on disk for later export. Data therefore survives app restarts even if the inspector panel was never opened. Tap the storage icon in the panel header to open the Persisted data manager: view row counts per category, export the full session archive, or clear the disk. See Configuration (PersistenceService section) for the API and tuning parameters.
日志、网络请求与聚合异常会被异步写入本地 SQLite 环形缓冲。下次启动时，日志与聚合异常会回放入各自标签页；网络请求保留在磁盘存档，供之后导出。因此即使从未打开过检查器面板，数据也能跨重启保留。点击面板头部的存储图标可打开 Persisted data 管理弹层：查看各类别行数、导出完整会话存档或清空磁盘。API 与调参详见 Configuration（PersistenceService 一节）。