阅前提要

由于维护者精力有限，不会主动适配不常用或者自己不用的软件
提交 Issue 时请给出应用内截图、应用包名、必需的 Activity 适配信息和具体适配要求
Pull Request 前建议在本地进行验证，提交时确保已填写更新日志

部分软件可能无法生效

你可以在这里获取针对特定应用的一些经验，并分享你的经验

如何正确反馈问题？

当您在使用规则时，若遇到未能适配或适配失效的应用场景，欢迎随时向我们提供反馈。

为了帮助我们更高效地解决问题，我们建议您提供尽可能详细的信息。详细的反馈内容将有助于加速适配与修复的进程。请参考以下指引，确保您的反馈能够更快地得到处理。

须知

良好的反馈信息应该包含以下内容：

应用名称
应用包名
需要适配的对应页面的 Activity 信息
需要适配的对应页面的截图

应用包名的获取

我们建议您通过以下步骤获取应用包名：

系统桌面中，长按需要反馈的应用的图标
在弹出菜单中，点按对应的图标进入 应用信息 页面
点按此页面的右上角三点图标，在弹出的菜单中点击 应用详情
在此页面中，您可以看到 应用包名 一行内展示的包名信息，您可以通过点按包名将内容复制到剪贴板中

应用 Activity 的获取

我们建议您通过 MT管理器来获取应用 Activity：

启动 MT管理器
点按主页左上角的三横图标，呼出菜单
在菜单的 工具 列表中，找到并选择 Activity 记录
点按弹出的对话框右下角的 启动服务
跟随指引选项您的启动方式（一键启动/手动开启），我们推荐您在拥有 Root 权限的情况下选择 一键启动

此时您应该能看到屏幕左上角出现了一个记录当前页面 Activity 的悬浮窗，您可以逐步打开到需要反馈的应用的详情页，获取 Activity 信息

工作原理

本项目维护的规则文件用于 HyperNavBar 应用，通过替换系统内的导航栏沉浸规则配置文件来实现优化。

自定义规则位于仓库内的 rules/immerse_rules.json（社区规则源）。

应用需要同时订阅两个规则源：

官方规则源（backup/backup.json，发版时作为 official.json 发布）— 系统原始配置，作为基础规则
社区规则源（rules/immerse_rules.json，发版时作为 custom.json 发布）— 自定义优化规则

社区规则源只包含与官方规则源不同的自定义规则（与官方完全相同的活动规则会被去重移除），因此必须与官方规则源配合使用。应用合并时社区规则源优先，可覆盖官方规则源中的对应规则。

配置文件为 JSON 格式，支持灵活的沉浸式规则配置。

开始适配

配置文件基本结构

{
  "dataVersion": "251104",
  "modules": "HyperNavBar_config",
  "modifyApps": "modifyApps",
  "name": "规则名称（可选）",
  "NBIRules": {
    "应用包名": {
      "name": "应用名称（可选）",
      "enable": true,
      "activityRules": {
        "Activity名称": {
          "style": "沉浸样式（view / sf / color / floating / disabled 等）"
          //"color": "#RRGGBBAA",      // 仅 style=color 时需要，RGBA 序 hex
          //"dialogMode": 1,           // 对话框模式（默认 1）
          //"popupMode": 1,            // 弹窗模式（默认 1）
          //"appNavColorDisabled": 0,  // 禁用应用导航栏颜色（默认 0）
          //"viewRules": []            // 视图规则数组
        }
      }
    }
  }
}

新旧格式区分（modules 字段语义）

规则文件通过顶层 modules 字段区分新旧两种格式：

modules 值	含义
`HyperNavBar_config`	新版格式，使用 `style` 主参数（本文档描述的格式）
`navigation_bar_immersive_application_config_new`	旧版官方格式，使用 `mode` / `color` / `sf_sampling_mode` 等官方字段，应用读取时会自动转换为新格式

写入系统时 modules 强制为官方模块名（navigation_bar_immersive_application_config_new），系统端只识别官方模块名。社区规则文件应使用新版 HyperNavBar_config。

应用级别配置选项

字段名	类型	可选值	默认值	说明
name	string	任意字符串	-	应用显示名称（仅用于方便管理）
enable	boolean	`true`, `false`	`false`	基础启用标志
enable31	boolean	`true`, `false`	`false`	特殊启用标志
disableVersionCode	long	数字或 `null`	`null`	当应用版本号小于等于此值时禁用规则

启用逻辑说明：

// 最终启用状态 = enable OR enable31

只要有一个为 true 就启用，两个都为 false 才禁用

Activity 级别配置选项

Activity名称填写完整字符串，可以使用 "*" 作为通配符。
如 "*" 指代全部Activity，"com.tencent.mm.plugin.appbrand.ui.AppBrandUI*" 指代所有微信小程序Activity。

每个 Activity 规则通过 style 主参数指定沉浸样式，未配置时默认值为 disabled（禁用），需显式指定 style 才会启用沉浸。

style（沉浸样式）

style 值	名称	说明	对应官方字段
default	自动模式	由系统算法自动检测适配	mode=-1
view	视图取色模式	启用沉浸，使用视图采样取色	mode=1, color=1
sf	采样取色模式	启用沉浸，使用 SurfaceFlinger 屏幕采样取色	mode=1, sf_sampling_mode=1
color	自定义颜色模式	启用沉浸，使用 `color` 字段指定的颜色	mode=1, color=具体值
floating	悬浮模式	通过悬浮隐藏导航栏背景（完全沉浸，但会遮挡内容）	mode=2
disabled	禁用模式	明确禁用自动沉浸，保持应用原有样式（默认值）	mode=0

color（自定义颜色）

仅当 style 为 color 时使用；其他 style 下该字段会被忽略

类型	示例值	对应颜色	说明
RGBA 十六进制	`#000000FF`	黑色（不透明）	直接设置导航栏为指定颜色，RRGGBB 为颜色、AA 为透明度（RGBA 序）
	`#FFFFFFFF`	白色（不透明）	直接设置导航栏为指定颜色
RGB 十六进制	`#RRGGBB`	任意颜色	省略透明度时默认为不透明

构建时会自动将 16 进制颜色转换为系统使用的整数值格式

高级字段

以下字段均为可选，一般使用默认值即可。

dialogMode（对话框模式）

值	名称	说明
0	禁用模式	对话框窗口禁用沉浸适配
1	视图采样模式（默认）	对话框启用沉浸，使用视图采样取色
2	SF 采样模式	对话框启用沉浸，使用 SF 采样取色

popupMode（弹窗模式）

值	名称	说明
0	禁用模式	弹窗窗口禁用沉浸适配
1	视图采样模式（默认）	弹窗启用沉浸，使用视图采样取色
2	SF 采样模式	弹窗启用沉浸，使用 SF 采样取色

appNavColorDisabled（禁用应用导航栏颜色）

仅 style 为取色类模式（view / sf / color，对应官方 mode=1）时生效

值	名称	说明
0	不禁用（默认）	允许该应用的自动导航栏颜色适配
1	禁用	禁用该应用的自动导航栏颜色适配

viewRules（视图规则数组）

暂不清楚具体效果，不建议使用

字段名	类型	说明
viewName	string	需要特殊处理的视图名称
iD	string	需要特殊处理的视图 ID

优先级说明

1. style 展开映射

style 是面向使用者的简化参数，写入系统时会自动展开为官方字段：

style 值	展开后的官方字段
default	mode=-1
view	mode=1, color=1
sf	mode=1, sf_sampling_mode=1
color	mode=1, color=具体值
floating	mode=2
disabled	mode=0

2. 启用优先级

应用级别 enable/enable31 > Activity 级别 style > 具体规则

3. 颜色来源优先级（style 为取色类时）

color 字段指定（style=color）> SF采样（style=sf）> 视图采样（style=view）> 系统默认

4. 规则匹配优先级

具体 Activity 名称 > 具有通配符 "*" 的名称

5. 特殊情况处理

dialogMode 和 popupMode 仅对相应类型窗口生效
取色类模式下，SF 采样优先于视图采样

提交适配

准备工作

安装并测试应用的各种页面
确定需要适配的应用包名和Activity名称
选择合适的适配模式组合
如果需要取色，确定合适的颜色值

修改配置文件

在 rules/immerse_rules.json 中添加或修改规则
在 changelog.md 中添加更新说明

通过 merge.json 提交本地规则

如果你使用 HyperNavBar 在本地维护规则，可以将包含所有修改的完整规则文件放到 rules/merge.json 中，提交 PR 时发版流程会自动合并。

工作流程：

在 HyperNavBar 中完成规则适配和测试
导出完整的规则 JSON 文件，重命名为 merge.json
将 merge.json 放到 rules/ 目录下，提交 PR
发版时 CI 会自动将 merge.json 中的规则合并到 immerse_rules.json，完成后清空 merge.json

注意：merge.json 应为一份完整的、包含所有本地修改的规则文件（与 HyperNavBar 导出的格式一致）。

发版时会自动移除与官方规则源（backup/ 中的官方快照）重复的活动规则，社区规则源只保留自定义规则，请勿在 merge.json 中提交与官方完全相同的规则。

验证要求

在本地设备上测试所有适配页面的效果
确保不会造成界面异常或功能问题
测试对话框和弹窗场景
截图记录适配前后的对比

常见问题

为什么只订阅社区规则源后大量应用没有适配？

社区规则源（custom.json）只包含与官方规则源不同的自定义规则。请同时订阅官方规则源和社区规则源，并将社区规则源放在上方、官方规则源放在下方，这样社区规则才能生效并覆盖官方默认规则。

配置为什么不生效？

应用强制设置了导航栏样式（使用 appNavColorDisabled: 1 尝试）
Activity名称不正确
被系统云控覆盖
配置文件格式错误
应用版本号未超过 disableVersionCode

如何获取 Activity 名称？

可以使用以下方法：

开发者选项中的"显示布局边界"
ADB命令：adb shell dumpsys activity activities
第三方Activity检测工具：如MT管理器等
查看应用日志输出

enable 和 enable31有什么区别？

根据源代码，两者是OR关系：

只要有一个为true，该应用的沉浸功能就启用
实际使用时建议只使用enable

通配符 `*` 会覆盖具体Activity规则吗？

不会，具体Activity规则优先级高于通配符规则。系统会优先匹配具体的Activity名称，如果没有匹配到，才会使用通配符规则。

`color=1` 和其他颜色值有什么区别？

color: 1：触发自动视图采样，系统分析界面底部颜色
color: 其他整数值：直接使用该颜色值，不进行采样
不设置color字段：使用默认逻辑

SF 采样和视图采样有什么区别？

视图采样：分析应用视图树的颜色，精度高但性能开销大
SF采样：直接从屏幕像素采样，性能好但可能不够精确
复杂界面推荐使用SF采样（sf_sampling_mode: 1）

重要提示：

适配前请充分测试各种场景（正常界面、对话框、弹窗）
记录所有修改和测试结果
对于复杂的应用，建议分步骤适配
如果遇到无法解决的问题，可以先使用 style: "default" 让系统自动处理
提交PR时请确保配置格式正确，所有字段值有效

Uh oh!

FilesExpand file tree

document.md

Latest commit

History