web-to-app 配置模板：将 WebViewConfig 通用配置存为命名快照并跨应用一键套用

web-to-app 配置模板将 WebViewConfig 通用配置存为命名快照并跨应用一键套用在 web-to-appWebToApp中每个应用都拥有一份独立的通用配置WebViewConfig涵盖浏览器行为、界面、网络、隐私、工具栏等设置。当你为一套浏览器环境反复调参后往往不希望为每个新应用重新配置一遍——配置模板Config Templates功能正是为此设计把整套通用配置保存为命名快照之后任何应用一键套用。读完本文你将理解模板的快照边界、UI 操作路径、底层存储实现ConfigTemplateStore.kt、Agent 工具接口以及测试对该机制的验证。模板是什么WebViewConfig 的完整快照模板是通用配置WebViewConfig的完整快照——即编辑通用配置编辑器里的全部设置JavaScript 开关、DOM Storage、缓存、User-Agent、桌面模式、缩放、刷新、全屏行为、下载、浏览器工具栏各按钮、状态栏样式、长按菜单等。这一点可以从WebViewConfig的数据类定义得到印证它定义在 WebApp.kt 中是一个带大量默认值的data class字段从javaScriptEnabled、domStorageEnabled一直延伸到状态栏、方向、注入脚本injectScripts等模板保存的就是这个对象的完整拷贝而非个别字段的差异。套用模板是整体替换而不是局部合并目标应用的WebViewConfig会被快照整体覆盖结果与保存时完全一致不会出现新旧值混杂。Agent 工具的描述字符串中也明确写了这一点Applying a template ... replacing its whole WebViewConfig with the template snapshot (a template is a full snapshot, never a partial merge). —— ConfigTemplateTools.kt边界说明应用类型相关设置入口文件、端口、依赖和 APK 导出设置不属于模板。模板快照的载体是一个专门的轻量数据类data class ConfigTemplate( val name: String, val createdAt: Long, val webViewConfig: WebViewConfig )—— 定义于 ConfigTemplateStore.kt每条模板由名称、创建时间戳和完整配置三部分组成。使用方法保存、套用与管理入口位于编辑通用配置编辑器顶栏的配置模板按钮书库图标Icons.Outlined.LibraryAddCheck。该按钮的 Composable 实现是 ConfigTemplateMenuButton.kt它被挂载在通用配置编辑器的固定顶栏中而非滚动配置列表内因为它作用于整份配置。保存为模板点击顶栏按钮后下拉菜单第一项为保存为模板输入模板名称长度1–40 字符输入框实时显示n/40计数超过 40 字符无法继续输入若名称与已有模板重名忽略大小写输入框下方会显示覆盖提示保存即覆盖旧快照保存成功后编辑器以 Snackbar 提示已保存。对应源码中保存对话框直接调用ConfigTemplateStore.save(context, trimmed, config)见 ConfigTemplateMenuButton.kt。套用模板两种入口下拉菜单已保存的模板按名称不区分大小写排序直接列在菜单中点击即把当前应用的通用配置整体替换为该快照并提示已套用 xxx管理对话框点击卡片中的模板名同样触发套用。从源码结构看套用的 UI 实现是回调onApplyConfig(template.webViewConfig)ConfigTemplateMenuButton.kt将快照作为新配置装载回编辑器改动与手动编辑一样落在编辑器里确认无误后照常保存即可。管理模板下拉菜单底部的管理模板打开一个对话框以卡片列表展示所有模板名称 x 天前式相对创建时间每张卡片提供点击卡片套用该模板重命名弹出输入框同样受 40 字符上限约束若新名与另一个已存在模板重名忽略大小写重命名会被拒绝并显示错误提示删除红色删除图标点击即移除。存储实现config_templates.json模板保存在本地app 存储目录context.filesDir中的config_templates.json应用升级不会丢失。实现上有一个值得注意的设计决策——它刻意没有做成 Room 实体而是 schema-free 的纯 JSON 文件。源码注释解释了原因随着WebViewConfig持续演进字段不断增加用 Gson 直接序列化整个列表可以免去数据库迁移成本见 ConfigTemplateStore.kt 的类注释。关键行为均可在 ConfigTemplateStore.kt 中逐一对照行为规则名称校验去除首尾空白后空名或超过MAX_NAME_LENGTH 40字符直接返回false拒绝同名覆盖save按忽略大小写匹配过滤后追加新快照即同名再次保存会覆盖旧值查找/删除/重命名全部按trim()ignoreCase匹配未命中时返回false而不抛异常重命名冲突新名若与其他模板重名忽略大小写rename返回false列表排序按名称小写排序返回容错降级文件不存在或 JSON 损坏时list通过runCatching { ... }.getOrDefault(emptyList())降级为空列表而不是崩溃写入采用整文件覆盖private fun write(context: Context, templates: ListConfigTemplate): Boolean runCatching { storeFile(context).writeText(Converters.gson.toJson(templates)) true }.getOrDefault(false)测试验证ConfigTemplateStoreTest单元测试 ConfigTemplateStoreTest.kt 基于 Robolectricsdk 33对上述每一条规则都有对应断言可作为行为契约参考保存后列出与读取保存WebViewConfig(zoomEnabled false, toolbarShowConsole false)后get能按忽略大小写的名称如my setup匹配My Setup取回且两个字段值与快照一致测试同名忽略大小写覆盖先存BasezoomEnabled true再存BASEzoomEnabled false列表只剩一条且值是新值测试非法名称拒绝纯空白名与 41 字符名均保存失败测试删除/重命名的忽略大小写与未命中报告删除不存在的模板返回false重命名到已存在名称被拒绝测试损坏文件降级向config_templates.json写入{not json后list返回空列表而非抛出异常测试。Agent 工具程序化管理模板应用内 Agent 也可以管理模板四个内置工具定义在 ConfigTemplateTools.kt 中由 ToolRegistryFactory.kt 注册工具参数只读行为ListConfigTemplates无是返回所有模板的名称与创建时间yyyy-MM-dd HH:mm格式SaveConfigTemplatename1–40 字符、appId否以指定应用的当前WebViewConfig保存为命名快照同名忽略大小写覆盖ApplyConfigTemplatename、appId否用快照整体替换目标应用的WebViewConfigapp.copy(webViewConfig template.webViewConfig)后写回数据库DeleteConfigTemplatename否按名称删除模板不存在时报错与 UI 入口不同Agent 工具以appId定位目标应用可先用ListApps/GetApp查询且保存时直接读取数据库中该应用的webViewConfig字段做快照。小结配置模板的机制可以归纳为三条快照语义模板 WebViewConfig完整拷贝套用即整体替换不合并、不含类型相关设置与 APK 导出设置轻量存储单文件config_templates.jsonGson 序列化schema-free 设计让WebViewConfig新增字段时无需数据迁移损坏时降级为空列表双入口一致编辑器顶栏 UIConfigTemplateMenuButton.kt与 Agent 工具ConfigTemplateTools.kt都收敛到同一份 ConfigTemplateStore 实现名称规则1–40 字符、忽略大小写、重名覆盖在两个入口保持一致并由单元测试完整约束。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考