#Debug Panel

Sparkling Debug Panel 是 Sparkling debug 构建里的端内调试面板。你可以不用连接 桌面调试器，直接在应用里查看 Lynx JS 日志、Sparkling Method 调用和运行时 GlobalProps。

它和 Lynx 自带的 DevTool、长按 Debug Menu 是两套入口。Sparkling 的这个面板通过 屏幕左下角的 sparkling debugTag 打开。

#打开 Debug Panel

只有同时满足以下条件时，debugTag 才会出现：

• 应用运行在 debug 构建中。
• 已集成 sparkling-debug-tool。
• 宿主启用了 debug 入口：
  • Android：调用 SparklingDebugTool.init(...)，并设置 enableFloatingBall = true。
  • iOS：调用 SparklingDebugTool.setFloatingBallEnabled(true)。

Sparkling Go 和默认应用模板已经在 debug-only 的宿主代码里完成这部分接线。

打开方式：点击屏幕最左下角蓝色的 sparkling 标签。

Release 构建不会显示这个标签。Sparkling 也不再安装双指长按入口，因此这个点击入口 不会和 Lynx 自己的原生调试手势竞争。

#集成指南

#基于默认模板创建的应用

使用默认 Sparkling 模板创建的应用，默认就是 debug 包包含 Debug Panel，release 包 不包含 Debug Panel。

Android 上，模板通过远端 Maven 产物 debugImplementation("com.tiktok.sparkling:sparkling-debug-tool:<version>") 引入 debug tool，并把初始化代码放在 app/src/debug。debug source set 会调用：

SparklingDebugTool.init(
    application,
    SparklingDebugTool.Config(
        enableJsConsole = true,
        enableFloatingBall = true,
    ),
)

release source set 是 no-op，不会初始化 debug tool。

iOS 上，模板有两个 app target：

模板用 canImport(Sparkling_DebugTool) 包住所有 debug-tool 调用。debug pod 被链接时， 启动流程会调用 SparklingDebugTool.setup()，然后通过下面的调用启用左下角 debugTag：

SparklingDebugTool.setFloatingBallEnabled(true)

因此，模板创建出的 app 默认在 debug 包里有 Debug Panel；release 包不会带上这个 面板，也不会带上 DebugRouter 或 Lynx DevTool 相关依赖。

#自定义 Android 宿主

如果你把 Sparkling 接入已有 Android 应用，建议只在 debug 依赖中引入 debug tool：

dependencies {
    implementation("com.tiktok.sparkling:sparkling:<version>")
    debugImplementation("com.tiktok.sparkling:sparkling-debug-tool:<version>")
}

然后在 debug-only 的应用代码中初始化：

SparklingDebugTool.init(
    application,
    SparklingDebugTool.Config(
        enableJsConsole = true,
        enableFloatingBall = true,
    ),
)

enableFloatingBall = true 是让符合条件的 SparklingView 显示左下角 sparkling debugTag 的开关。

#自定义 iOS 宿主

如果你把 Sparkling 接入已有 iOS 应用，只在开发 target 或 debug configuration 中 链接 Sparkling-DebugTool。同时用条件编译保护调用，保证生产构建不依赖 debug-tool module：

#if canImport(Sparkling_DebugTool)
import Sparkling_DebugTool
#endif

#if canImport(Sparkling_DebugTool)
SparklingDebugTool.setup()
SparklingDebugTool.setFloatingBallEnabled(true)
#endif

setup() 会启用 Lynx debug flags 和 DebugRouter 集成；setFloatingBallEnabled(true) 会显示左下角 sparkling debugTag，并把默认点击行为接到 Debug Panel。

#Log

Log 页签展示当前 Lynx 页面产生的 JS console 输出。

你可以用它：

• 查看应用内的 console.log、console.warn、console.error 输出。
• 按日志级别筛选。
• 搜索日志内容。
• 清空当前日志缓存。
• 复制单条日志，方便贴到 issue 或 PR 评论里。

#Sparkling Method

Sparkling Method 页签记录 JS 到 native 的 method 调用。

你可以用它：

• 查看调用过哪些 Sparkling Method API。
• 检查每次调用的平台、namespace、结果码和耗时。
• 发现仍在运行或返回错误的调用。
• 点击某条记录展开请求参数和响应数据。
• 复制 method 记录，用于排查桥接问题。

#GlobalProps

GlobalProps 页签展示当前 live LynxView 的最新运行时快照。

你可以用它：

• 确认当前活跃的 container 和 template URL。
• 查看传入 Lynx 的 globalProps。
• 展开 queryItems，包括当前页面加载使用的 bundle 或 URL。
• 搜索 key 和 value。
• 在导航或运行时更新后刷新快照。
• 复制某个 key-value 行，方便报告环境相关问题。

#看不到 debugTag 时

按顺序检查：

1. 确认应用是 debug 构建。
2. 确认 native target 已包含 sparkling-debug-tool。
3. 确认宿主在 Android 调用了 SparklingDebugTool.init(...)，或在 iOS 调用了 SparklingDebugTool.setup() 和 setFloatingBallEnabled(true)。
4. Android 上，sparkling-debug-tool provider 还需要能被 Sparkling SDK 发现。 默认模板已经通过 debug source set 完成接线。