deveco_hmigbot 0.1.0

package/skills/migrate-core/references/topics/i18n/references/dynamic-language-switch.md

@@ -0,0 +1,464 @@
+# 动态语言切换实现（V2）
+
+> ⚠ 本文样例中 `getContext(this)` 为已废弃写法：组件内一律改 `this.getUIContext().getHostContext()`；Ability 内用 `this.context`。
+
+
+> 完整的运行时语言切换代码模板，包括状态管理和 UI 刷新。**本项目锁 V2**：组件用 `@ComponentV2`，本地状态用 `@Local`，全局 locale / refreshKey 用 `@ObservedV2 LocaleModel + AppStorageV2.connect`。i18n API 与装饰器版本无关。
+>
+
+---
+
+## ⚠️ API 验证状态
+
+| API | 状态 | 说明 |
+|-----|------|------|
+| `i18n.System.setAppPreferredLanguage(lang)` | ✅ SDK 有声明 | `@ohos.i18n` System，同步、返回 void；设 `'default'` 跟随系统（冷启动生效） |
+| `i18n.System.getAppPreferredLanguage()` | ✅ SDK 有声明 | 同步返回 string（如 `zh-Hans`） |
+| V2 `@Local` / `AppStorageV2.connect` 触发 UI 刷新 | ✅ 已验证 | ArkTS V2 标准机制（API 12+） |
+| `onConfigurationUpdate(config)` | ✅ SDK 有声明 | UIAbility 唯一的配置变化回调；`config.language` 有值即语言变了 |
+
+
+---
+
+## 基本实现模式
+
+### 简单实现（单页面，V2）
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+import { common } from '@kit.AbilityKit'
+import { hilog } from '@kit.PerformanceAnalysisKit'
+
+const DOMAIN = 0x0001
+const TAG = 'I18nDemo'
+
+@Entry
+@ComponentV2
+struct LanguageSwitchDemo {
+  private context = getContext(this) as common.UIAbilityContext
+  @Local private currentLanguage: string = 'zh'
+  @Local private refreshKey: number = 0
+
+  aboutToAppear(): void {
+    this.loadCurrentLanguage()
+  }
+
+  async loadCurrentLanguage(): Promise<void> {
+    try {
+      this.currentLanguage = i18n.System.getAppPreferredLanguage() || 'zh'   // 同步返回当前生效语言
+      hilog.info(DOMAIN, TAG, `Current language: ${this.currentLanguage}`)
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `Failed to get language: ${e.message}`)
+    }
+  }
+
+  async switchLanguage(lang: string): Promise<void> {
+    try {
+      hilog.info(DOMAIN, TAG, `Switching to: ${lang}`)
+
+      i18n.System.setAppPreferredLanguage(lang)   // 同步；之后加载的资源按此语言取，已渲染页面靠 refreshKey 重建
+
+      this.currentLanguage = lang
+      this.refreshKey++
+
+      hilog.info(DOMAIN, TAG, `Language switched to: ${lang}`)
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `Failed to switch language: ${e.message}`)
+    }
+  }
+
+  build() {
+    Column({ space: 20 }) {
+      Text($r('app.string.app_name'))
+        .fontSize(24)
+        .fontWeight(FontWeight.Bold)
+
+      Text($r('app.string.welcome'))
+        .fontSize(16)
+
+      Text($r('app.string.settings_language'))
+        .fontSize(14)
+        .fontColor('#666666')
+
+      Row({ space: 12 }) {
+        Button('中文')
+          .onClick(() => this.switchLanguage('zh'))
+          .backgroundColor(this.currentLanguage === 'zh' ? '#007AFF' : '#CCCCCC')
+
+        Button('English')
+          .onClick(() => this.switchLanguage('en'))
+          .backgroundColor(this.currentLanguage === 'en' ? '#007AFF' : '#CCCCCC')
+
+        Button('日本語')
+          .onClick(() => this.switchLanguage('ja'))
+          .backgroundColor(this.currentLanguage === 'ja' ? '#007AFF' : '#CCCCCC')
+      }
+
+      Text(`Current: ${this.currentLanguage}`)
+        .fontSize(12)
+        .fontColor('#999999')
+    }
+    .width('100%')
+    .height('100%')
+    .justifyContent(FlexAlign.Center)
+    .id('lang_container_' + this.refreshKey)
+  }
+}
+```
+
+---
+
+## 完整实现（设置页面 + 全局状态，V2）
+
+### 1. 全局 LocaleModel（@ObservedV2 + AppStorageV2）
+
+V2 推荐**单一 `@ObservedV2` 类封装所有 locale 相关全局状态**，避免 V1 散落的 `@StorageLink('currentLanguage')` / `@StorageLink('languageRefreshKey')` 多 key 写法（拼写易错、无类型保护）。
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+// common/LocaleModel.ets
+import { common } from '@kit.AbilityKit'
+import { AppStorageV2 } from '@kit.ArkUI'
+import { hilog } from '@kit.PerformanceAnalysisKit'
+
+const DOMAIN = 0x0000
+const TAG = 'LocaleModel'
+
+@ObservedV2
+export class LocaleModel {
+  @Trace currentLanguage: string = 'zh'
+  @Trace refreshKey: number = 0
+
+  async init(context: common.UIAbilityContext): Promise<void> {
+    try {
+      this.currentLanguage = i18n.System.getAppPreferredLanguage() || 'zh'
+    } catch (e) {
+      this.currentLanguage = 'zh'
+    }
+  }
+
+  async setLanguage(context: common.UIAbilityContext, lang: string): Promise<void> {
+    try {
+      i18n.System.setAppPreferredLanguage(lang)   // 同步；之后加载的资源按此语言取，已渲染页面靠 refreshKey 重建
+      this.currentLanguage = lang
+      this.refreshKey++  // @Trace 字段变化 → 所有 connect 同 key 的组件自动刷新
+    } catch (e) {
+      hilog.error(DOMAIN, TAG, `Failed to set language: ${e.message}`)
+    }
+  }
+}
+
+// 全局单例（推荐在 EntryAbility.onCreate 中预热一次；任何位置 connect 同 key 都返回同一实例）
+export const localeStore = AppStorageV2.connect(
+  LocaleModel,
+  'locale',
+  () => new LocaleModel()
+)!
+```
+
+### 2. 设置页面（V2）
+
+```typescript
+// pages/SettingsPage.ets
+import { LocaleModel, localeStore } from '../common/LocaleModel'
+import { common } from '@kit.AbilityKit'
+
+@Entry
+@ComponentV2
+struct SettingsPage {
+  @Local locale: LocaleModel = AppStorageV2.connect(
+    LocaleModel,
+    'locale',
+    () => new LocaleModel()
+  )!
+
+  @Builder
+  LanguageItem(lang: string, label: string) {
+    Row() {
+      Text(label)
+        .fontSize(16)
+
+      if (this.locale.currentLanguage === lang) {
+        Text('✓')
+          .fontSize(16)
+          .fontColor('#007AFF')
+      }
+    }
+    .width('100%')
+    .padding(16)
+    .backgroundColor(this.locale.currentLanguage === lang ? '#F0F8FF' : '#FFFFFF')
+    .onClick(() => {
+      const context = getContext(this) as common.UIAbilityContext
+      this.locale.setLanguage(context, lang)
+    })
+  }
+
+  build() {
+    Column() {
+      Text($r('app.string.settings_title'))
+        .fontSize(20)
+        .fontWeight(FontWeight.Bold)
+        .padding(16)
+
+      List() {
+        ListItem() {
+          this.LanguageItem('zh', '简体中文')
+        }
+
+        ListItem() {
+          this.LanguageItem('zh-Hans', '简体中文 (简体)')
+        }
+
+        ListItem() {
+          this.LanguageItem('zh-Hant', '繁体中文 (繁体)')
+        }
+
+        ListItem() {
+          this.LanguageItem('en', 'English')
+        }
+
+        ListItem() {
+          this.LanguageItem('ja', '日本語')
+        }
+      }
+    }
+    .width('100%')
+    .height('100%')
+    .id('settings_' + this.locale.refreshKey)
+  }
+}
+```
+
+---
+
+## 语言切换后刷新页面的方法（V2）
+
+### 方法 1：@Local refreshKey + ID 变化
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+@Local private refreshKey: number = 0
+
+async switchLanguage(lang: string) {
+  await i18n.System.setAppPreferredLanguage([lang])
+  this.refreshKey++
+}
+
+build() {
+  Column() {
+    Text($r('app.string.hello'))
+  }
+  .id('page_' + this.refreshKey)  // ID 变化触发重建
+}
+```
+
+### 方法 2：router.replaceUrl 重新加载
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+import { router } from '@kit.ArkUI'
+
+async switchLanguage(lang: string) {
+  await i18n.System.setAppPreferredLanguage([lang])
+  router.replaceUrl({ url: 'pages/SettingsPage' })
+}
+```
+
+### 方法 3：Navigation 模式（V2）
+
+```typescript
+@Local private navPathStack: NavPathStack = new NavPathStack()
+@Local private refreshKey: number = 0
+
+build() {
+  Navigation(this.navPathStack) {
+    // 内容
+  }
+  .id('nav_' + this.refreshKey)
+}
+```
+
+### 方法 4：@Monitor 触发副作用（V2 新增）
+
+```typescript
+@ComponentV2
+struct PageWithMonitor {
+  @Local locale: LocaleModel = AppStorageV2.connect(
+    LocaleModel, 'locale', () => new LocaleModel()
+  )!
+
+  @Monitor('locale.currentLanguage')
+  onLanguageChange(monitor: IMonitor): void {
+    // currentLanguage 改变时执行副作用：埋点、缓存清理等
+    console.info('Language changed to:', this.locale.currentLanguage)
+  }
+
+  build() {
+    Text($r('app.string.hello'))
+      .id('page_' + this.locale.refreshKey)
+  }
+}
+```
+
+---
+
+## 获取支持的语言列表
+
+```typescript
+
+interface LanguageInfo {
+  language: string   // 如 'zh'
+  region?: string    // 如 'CN'
+  displayName: string // 如 '简体中文'
+}
+
+async function getSupportedLanguages(): Promise<LanguageInfo[]> {
+  // 这是一个示例，实际 API 可能不同
+  const supported = ['zh', 'zh-Hans', 'zh-Hant', 'en', 'ja', 'ko']
+  const displayNames: Record<string, string> = {
+    'zh': '中文',
+    'zh-Hans': '简体中文',
+    'zh-Hant': '繁体中文',
+    'en': 'English',
+    'ja': '日本語',
+    'ko': '한국어'
+  }
+
+  return supported.map(lang => ({
+    language: lang,
+    displayName: displayNames[lang] || lang
+  }))
+}
+```
+
+---
+
+## 监听系统语言变化（V2）
+
+### 在 UIAbility 中处理（写入 AppStorageV2）
+
+```typescript
+// EntryAbility.ets
+import { AbilityConstant, Configuration, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit'
+import { hilog } from '@kit.PerformanceAnalysisKit'
+import { AppStorageV2 } from '@kit.ArkUI'
+import { i18n } from '@kit.LocalizationKit'
+import { LocaleModel } from '../common/LocaleModel'
+
+export default class EntryAbility extends UIAbility {
+  // UIAbility 只有 onConfigurationUpdate 一个配置变化回调（没有单独的语言回调）：语言变了在这里刷新
+  onConfigurationUpdate(configuration: Configuration): void {
+    if (configuration.language === undefined) return
+    hilog.info(0x0000, 'EntryAbility', `Language changed to: ${configuration.language}`)
+    this.refreshLocale()
+  }
+
+  private refreshLocale(): void {
+    // 1. 拿到全局 LocaleModel（与组件 connect 同一实例）
+    const locale = AppStorageV2.connect(LocaleModel, 'locale', () => new LocaleModel())!
+    // 2. 重新获取当前语言（同步返回当前生效语言，如 'zh-Hans'）
+    locale.currentLanguage = i18n.System.getAppPreferredLanguage() || 'zh'
+    locale.refreshKey++   // 通知所有页面刷新
+  }
+}
+```
+
+---
+
+## 完整页面刷新机制（V2）
+
+```typescript
+import { i18n } from '@kit.LocalizationKit'
+// 确保语言切换后所有页面都刷新的完整 V2 模式
+
+// 1. 全局 LocaleModel
+@ObservedV2
+class LocaleModel {
+  @Trace currentLanguage: string = 'zh'
+  @Trace refreshKey: number = 0
+
+  async switchLanguage(context: common.UIAbilityContext, lang: string): Promise<void> {
+    // 1. 切换语言
+    i18n.System.setAppPreferredLanguage(lang)   // 同步；之后加载的资源按此语言取，已渲染页面靠 refreshKey 重建
+
+    // 2. 更新状态：所有 connect 'locale' 的组件 @Trace 字段变化即刷新
+    this.currentLanguage = lang
+    this.refreshKey++
+  }
+}
+
+// 2. 任意页面用 @Local + AppStorageV2.connect 引用单例
+@Entry
+@ComponentV2
+struct AnyPage {
+  @Local locale: LocaleModel = AppStorageV2.connect(
+    LocaleModel, 'locale', () => new LocaleModel()
+  )!
+
+  build() {
+    Column() {
+      Text($r('app.string.any_string'))
+        .fontSize(16)
+    }
+    .id('page_' + this.locale.refreshKey)
+  }
+}
+```
+
+---
+
+## 注意事项
+
+1. **语言代码大小写**：`zh-Hans` vs `zh-hans` — 必须完全匹配
+2. **切换后需要时间生效**：异步操作，避免连续快速切换
+3. **并非所有页面都需要重建**：只有持有 `LocaleModel`（`@Local locale = AppStorageV2.connect(LocaleModel, 'locale', ...)`）并在 `build()` 中读取 `locale.refreshKey` 的组件才会重建
+4. **性能考虑**：避免高频调用，建议在语言切换按钮上做防抖
+5. **V1/V2 不混用**：同一 struct 内不要混用 `@State` 和 `@Local`，会编译报错
+
+---
+
+## 持久化用户语言偏好（V2 推荐 PersistenceV2）
+
+V1 用 `PersistentStorage.persistProp('currentLanguage', 'zh')` + `@StorageLink`；V2 一站式：
+
+```typescript
+// common/LocaleModel.ets
+@ObservedV2
+export class LocaleModel {
+  @Trace currentLanguage: string = 'zh'
+  @Trace refreshKey: number = 0
+}
+
+// 在任意位置 connect（自动持久化到磁盘 + UI 响应式）
+@ComponentV2
+struct App {
+  @Local locale: LocaleModel = PersistenceV2.globalConnect({
+    type: LocaleModel,
+    key: 'app_locale',
+    defaultCreator: () => new LocaleModel()
+  })!
+
+  build() {
+    Column() {
+      Text(`当前: ${this.locale.currentLanguage}`)
+      Button('切换 EN').onClick(() => {
+        this.locale.currentLanguage = 'en'   // 自动落盘 + 触发所有引用刷新
+      })
+    }
+  }
+}
+```
+
+---
+
+## V1 → V2 迁移速查（仅本文涉及部分）
+
+| V1 | V2 | 备注 |
+|---|---|---|
+| `@Component` | `@ComponentV2` | struct 装饰器 |
+| `@State refreshKey: number = 0` | `@Local refreshKey: number = 0` | 必须初始化 |
+| `@StorageLink('currentLanguage') lang: string = 'zh'` | `@Local locale: LocaleModel = AppStorageV2.connect(LocaleModel, 'locale', () => new LocaleModel())!` 然后 `this.locale.currentLanguage` | 先抽 @ObservedV2 类 |
+| `AppStorage.setOrCreate('refreshKey', n+1)` | `localeStore.refreshKey++` | 直接改 @Trace 字段 |
+| `PersistentStorage.persistProp('lang', 'zh')` | `PersistenceV2.globalConnect({ type: LocaleModel, key, defaultCreator })` | V2 一站式 |
+| `@Watch('lang') onLangChange()` | `@Monitor('lang') onLangChange(m: IMonitor)` | 方法装饰器 + IMonitor |
+

package/skills/migrate-core/references/topics/i18n/references/language-codes.md

@@ -0,0 +1,104 @@
+# 语言代码对照表
+
+> HarmonyOS 支持的语言代码规范，包括 ISO 标准和使用示例
+
+---
+
+## 两种命名方案
+
+### 方案 1：仅使用语言代码（推荐用于简单应用）
+
+```
+resources/
+├── base/      # 默认资源（fallback）
+├── en/        # 英文
+├── zh/        # 中文
+├── ja/        # 日文
+└── ko/        # 韩文
+```
+
+**优点**：
+- 简单直观
+- 适配所有区域（en 匹配 en_US, en_GB, en_AU 等）
+
+**缺点**：
+- 无法区分 zh_CN（简体）和 zh_TW（繁体）
+
+---
+
+### 方案 2：使用语言+区域代码（推荐用于多区域应用）
+
+```
+resources/
+├── base/
+├── en_US/     # 美国英语
+├── en_GB/     # 英国英语
+├── zh_CN/     # 简体中文
+├── zh_TW/     # 繁体中文（台湾）
+├── zh_HK/     # 繁体中文（香港）
+└── ja/
+```
+
+**优点**：
+- 更精确的区域划分
+- 可以针对不同地区提供不同翻译
+
+**缺点**：
+- 目录较多
+- 需要维护更多资源文件
+
+---
+
+## 推荐实践
+
+| 场景 | 推荐方案 | 示例 |
+|------|---------|------|
+| 单一市场应用 | 方案 1 | 中国应用：`zh`, `en` |
+| 多区域应用 | 方案 2 | 国际化应用：`zh_CN`, `zh_TW`, `en_US`, `en_GB` |
+| 简单国际化 | 方案 1 | `en`, `zh`, `ja` |
+| 专业国际化 | 方案 2 | 所有主要语言+区域 |
+
+---
+
+## 语言代码对照表
+
+| 语言 | 语言代码 | 区域代码 | 完整代码 | 说明 |
+|------|---------|---------|---------|------|
+| 中文 | `zh` | - | `zh` | 通用中文 |
+| 简体中文 | `zh` | `CN` | `zh_CN` 或 `zh-Hans` | 中国大陆 |
+| 繁体中文 | `zh` | `TW` | `zh_TW` 或 `zh-Hant` | 台湾 |
+| 繁体中文 | `zh` | `HK` | `zh_HK` | 香港 |
+| 英文 | `en` | - | `en` | 通用英文 |
+| 美国英文 | `en` | `US` | `en_US` | 美国 |
+| 英国英文 | `en` | `GB` | `en_GB` | 英国 |
+| 日文 | `ja` | - | `ja` | 日本 |
+| 韩文 | `ko` | - | `ko` | 韩国 |
+
+---
+
+## API 12+ 格式注意
+
+HarmonyOS 支持两种格式：
+
+| 格式 | 示例 | 说明 |
+|------|------|------|
+| 下划线格式 | `zh_CN`, `en_US` | 传统格式 |
+| 连字符格式 | `zh-Hans`, `zh-Hant` | Unicode 格式，API 12+ 推荐 |
+
+---
+
+## 当前代码仓实践
+
+**代码仓使用**：`en_US/`（方案 2）
+
+```
+entry/src/main/resources/
+├── base/
+├── en_US/     # 美国英语
+└── dark/      # 深色模式
+```
+
+**分析**：
+- ✅ 使用了精确的区域划分
+- ⚠️ 只有英文翻译，缺少其他语言
+- 💡 建议：如需支持更多语言，可按相同模式添加

package/skills/migrate-core/references/topics/icon-sizing.md

@@ -0,0 +1,98 @@
+<!-- 原技能 arkts-icon-sizing，已吸收为 migrate-core 语料专题，不再单独注册 -->
+> 检测并修复 Android→HarmonyOS UI 迁移中，因丢失 `.width()/.height()` 而导致渲染尺寸错误或比例 失真的 ArkUI/HarmonyOS `Image` 组件。转换器保留了 `.objectFit()` 却丢掉了尺寸，使 `resources/base/media` 里的位图图标按**原始像素尺寸**渲染（通常大 3 倍，非方形的还会被拉伸）。当用户反馈图标/图片在鸿蒙页面 （主页、我的、弹窗、列表项——任何位置）上「太大 / 太小 / 被拉伸 / 被压扁 / 比例异常 / 图标变形 / 显示太大 / icons look off」，或要求「统一检查/修复各页图标比例」，或刚做完 a2h / ArkUI UI 迁移（大量 Android ImageView 用了 wrap_content）时触发。内置「审计→测量→修复」三步流水线：用源位图的像素尺寸
+
+# ArkUI 图标尺寸修复（Android→HarmonyOS 迁移修复）
+
+## 问题与成因
+
+在 Android 中，`android:layout_width/height="wrap_content"` 的 `ImageView` 会按 drawable 的**标称 dp**
+尺寸渲染。一张只放在 `*-xxhdpi`（3 倍密度）目录的位图，磁盘上可能是 `90×90 px`，显示为 `30×30 dp`。
+
+Android→HarmonyOS UI 转换器常常复刻了 `ImageView` 的 `.objectFit(...)`，却**丢掉了 `.width()/.height()`**
+（因为 `wrap_content` 没有固定数值可抄）。位图被原样拷进 HarmonyOS 的 `resources/base/media`——而**该目录无密度
+限定符**——于是 ArkUI 按 `Image` 的**字面像素尺寸（当成 vp）**渲染。那张 `90×90 px` 的图标现在显示为 `90×90 vp`，
+即**大了 3 倍**。更糟的是，非方形图标（`45×23` 的电池、`44×26` 的箭头）在没有显式尺寸时保持原始像素框，一旦
+某根轴被布局约束触碰，宽高比就明显失真——这就是用户看到的「比例异常 / 图标变形」。
+
+修复办法是把每个欠约束的 `Image` 还原成它的**标称 vp 尺寸**：
+
+```
+标称 vp = 源位图像素 ÷ 源密度倍数
+```
+
+宽和高**分别独立**相除，这正是还原正确宽高比的关键。已经带显式 `.width()/.height()` 的图标是正常的——**不要**
+碰它们，也**不要**用「把位图挪进带密度限定的目录」这种全局手段去修（那会把本来正确的图标缩小）。缺陷只针对
+**那一部分丢了尺寸的 `Image`**。
+
+## 何时使用
+
+- 用户反馈图标/图片在鸿蒙页面上过大、过小、被拉伸或被压扁——尤其刚做完 a2h / ArkUI UI 迁移之后。
+- 用户要求「统一检查/修复图标比例」。
+- 做迁移 QA，想横扫每个页面排查这一类缺陷。
+
+不属于本专题：文本截断、大字体布局溢出、深色模式图标变色、生成全新 UI。那些是不同的问题。
+
+## 检测 → 测量 → 修复（三步，全是确定性判断，手工或 grep 即可完成）
+
+> **先提交或暂存你的工作。** 修复会就地改源文件；干净的 git 状态让一次坏的运行可以秒回滚。
+
+### 1. 审计 — 找出每一个欠约束的 Image
+
+在 `*/src/main/ets` 下 grep 所有 `Image(` 调用，逐处看修饰链。被标记 = 修饰链**无 width 且无 height**（`NO-DIMS`）
+或**只有其中一个且无 `aspectRatio`**（`ONE-DIM-NO-ASPECT`）。`width('100%') + height('100%')` 视为有意的满铺，不标记。
+
+分两份清单：**静态**欠约束图标（`$r('app.media.xxx')`，可按下面公式直接修）与**动态源**图片
+（`Image(this.foo())`、三元、`@Builder` 参数——需手工解析，见第 4 步）。`ImageFit.Fill` 用法单列复核：
+`Fill` 会拉伸填满，通常是**可拉伸背景图形**（`shape_*_bg` 弹窗横幅）的有意为之，除非真有图标用了 `Fill`，否则放着别动。
+
+### 2. 测量 — 还原每个图标的正确 vp 尺寸
+
+对每个被标记的静态图标：取 HarmonyOS `resources/base/media` 里该文件（webp/png/jpg/svg）的像素尺寸
+（`sips -g pixelWidth -g pixelHeight <file>` / `file <file>` / SVG 读 `viewBox`），再到 **Android 源**里找同名资源所在的
+密度目录，按倍数表相除：ldpi .75，mdpi 1，hdpi 1.5，xhdpi 2，xxhdpi 3，xxxhdpi 4。多模块工程的共享资源在
+`base`/`common` 模块的 `res/`，一起查。找不到 Android 源时按工程主密度桶兜底（多数 app 只发 xxhdpi=3），并在结论里标注"假定 3×"。
+
+**落地前核对**：密度来源是真实目录（如 `mipmap-xxhdpi`），算出的 vp 尺寸对一个图标而言合理（小图标个/十位数，插图更大）。
+
+没有 raster 的项（动态引用、纯 SVG `<shape>` 转换或矢量图）不在本步——转第 4 步手工处理。
+
+### 3. 修复 — 插入尺寸
+
+逐处在 `Image(...)` 开头之后插入：
+- **NO-DIMS** → `.width(W)` `.height(H)`（还原的标称 vp；固定尺寸、真实比例）。
+- **ONE-DIM** → 仅 `.aspectRatio(W/H)`——保留有意的那一维（如满宽横幅的 `.width('100%')`），只修比例。
+
+动态图片只报告，绝不批量改。
+
+### 4. 手工解析动态源图片
+
+`Image(this.vipEditRes())` 或 `Image(cond ? $r('app.media.a') : $r('app.media.b'))` 读不出尺寸。对每一处：
+
+1. 读代码找出它能解析到的具体资源名（顺着方法/三元跟踪）。勾选类开关通常指向两张同尺寸资源。
+2. 按第 2 步量这些资源。
+3. 手工给 `Image(...)` 加 `.width(W).height(H)`（若已设一维则用 `.aspectRatio()`）。`@Builder tabItem(icon: Resource)`
+   会让所有调用方共享一个尺寸——在 Builder 的 `Image` 上设一次即可。
+
+### 5. 校验
+
+重跑第 1 步的 grep：静态被标记数应为 0。然后**编译工程**（`hvigorw assembleHap ...`）——插入的都是普通
+`.width(n)/.height(n)/.aspectRatio(n)`（vp 数值），编译通过即确认语法无误。只应剩下有意跳过的动态项（已手工修）和 `Fill` 背景。
+
+## 决策规则与边界
+
+- **密度是逐图的，不是全局的。** 每个图标按它在 Android 源里的真实密度目录算。
+  多数 app 只发一个桶（xxhdpi=3），但别假设——逐图核实目录。倍数表：ldpi .75，mdpi 1，hdpi 1.5，xhdpi 2，
+  xxhdpi 3，xxxhdpi 4。
+- **方形 SVG 不会失真。** 方形 viewBox 的 `<shape>`/矢量图按标称 vp 渲染、比例正确——它不会「比例错」，只可能
+  「尺寸错」。若这种 SVG 渲染得过大（如 `100×100` viewBox 显示成 100vp，而本意是小图标），查 **Android drawable 的
+  `android:width/height`** 取本意 dp 并显式设上。否则优先级低。
+- **`shape_*_bg` 上的 `ImageFit.Fill`** 是可拉伸横幅背景——放着别动。只在真图标的盒子比例 ≠ 图标比例时才管 `Fill`。
+- **别碰已带尺寸的图标。** 重点就是欠约束的那部分；全局改资源密度会破坏本来正确的图标。
+- **多模块 Android 工程**把共享资源放在 `base`/`common` 模块——每个 `*/src/main/res` 根都要查，密度才找得到。
+
+## 与其他专题的关系
+
+- 图片被裁切/容器溢出类问题方向相反（倾向去掉固定尺寸换 `%`/`aspectRatio`），不归本专题。
+- 资源/资产侧转换（res/ → resources/、SVG 坐标/格式修复）归 `scripts/convert/convert-resources.mjs`（规则见 `resources/`）；本专题修 `.ets` 消费侧。
+- UI 迁移对齐 / SymbolGlyph 图标体系见 `ui-alignment/README.md`。
+- 不确定某 API 是否存在/版本兼容时：grep 本机 SDK `.d.ts` 声明为准。