该技能提供一套将 DevTools 旧式 SettingRegistration 迁移到新设置描述符架构的工作流。迁移的目标是把一个旧式注册拆分为两部分:非 UI 的 SettingDescriptor 和 UI 的 SettingUIDescriptor。
用途 用于指导开发者在 DevTools 前端代码中迁移设置定义。旧代码通过 Settings.instance().moduleSetting('setting-name') 以字符串标识获取设置,新架构要求定义并导出类型化的 SettingDescriptor,并在合适层级完成 UI 注册。
主要能力与分层规则 SettingDescriptor 必须放在使用该设置的最低架构层:若被 core/sdk 或 models/ 使用,则放在对应目录;若仅被 UI 组件或某个面板使用,则必须放在 ui/settings/FooSettings.ts(如 ConsoleSettings.ts),不得放在 panels/ 目录下。原因是 -meta.ts 文件需要导入描述符进行 UI 注册,而 -meta.ts 不能从 panels/ 导入,否则会破坏面板包的懒加载。 SettingDescriptor 也不得放在 -meta.ts 文件中,因为运行时代码需要直接导入描述符并调用 resolve。 SettingUIDescriptor 定义分类、标题、标签、选项、是否需重载等 UI 属性,必须注册在更高层的 -meta.ts 文件里(如 entrypoints/main/main-meta.ts、panels/settings/settings-meta.ts 或具体面板的 -meta.ts),且不得保留或新增在 core/ 或 models/ 的 -meta.ts 中。迁移的重要目标是完全消除 core/ 和 models/ 下的 -meta.ts 文件。
使用方式(迁移步骤)
- 在 -meta.ts 中搜索设置名,找到旧注册块,并搜索所有使用点,确定最低层。
- 在最低层创建或更新文件以定义并导出 SettingDescriptor,包含 name、type、defaultValue、storageType 等字段;条件设置可使用 ConditionalSettingDescriptor 并提供 isAvailable。
- 将 UI 注册移动到更高层 -meta.ts,使用 SettingsUI.SettingUIRegistration.register(descriptor, uiDescriptor),并从 ui/settings/settings.js 和描述符所在模块导入;删除 core/ 或 models/ -meta.ts 中的旧注册,若文件变空则删除并清理构建引用。
- 将调用点从 moduleSetting('name') 改为 resolve(descriptor),条件设置使用 maybeResolve。
- 新建 .ts 文件时更新 BUILD.gn 的 sources 并在模块入口导出;删除 -meta.ts 时同步移除 BUILD.gn 和 devtools_grd_files.gni 中的引用,并遵守 DevTools 导入规则。
- 运行 autoninja -C out/Default 验证 GN 构建,运行 ./dt lint 检查风格,运行相关单元测试。
适用场景 适用于 DevTools 前端中需要将旧式设置注册迁移到描述符架构的开发者,尤其是涉及 core/sdk、models/ 或面板 UI 设置的重构任务。文中包含 preserve-console-log(core/sdk 设置)和 network-messages(面板 UI 设置)两个具体迁移示例。
限制与注意事项 迁移必须严格遵守层级边界和导入规则;面板描述符不得放入 panels/;描述符不得放入 -meta.ts;UI 描述符不得留在 core/ 或 models/ 的 -meta.ts 中。缺失的收费、平台或运行环境信息暂未提供。