fix-manifest-json

修复 manifest.json

此技能用于修复 UI5 linter 检测到、但无法自动修复的 manifest.json 问题，因为修复可能需要了解应用的依赖项和结构。

处理的 Linter 规则

规则 ID	消息模式	此技能的操作
no-outdated-manifest-version	manifest.json 必须升级为 Version 2	将 _version 更新为 "2.0.0"
no-legacy-ui5-version-in-manifest	使用 UI5 版本 1.136.0 或更高版本	将 minUI5Version 更新为 "1.136.0"
no-deprecated-library	使用了已弃用的库 '...'	从依赖项/库中移除
no-deprecated-component	使用了已弃用的组件 '...'	从依赖项/组件中移除
no-deprecated-api	使用了已弃用的视图类型 '...'	改为 "XML"
no-deprecated-api	使用了已弃用的属性 'sap.ui5/resources/js'	如果为空，则移除
no-deprecated-api	使用了已弃用的类 '...'（模型类型）	标记为需手动升级
no-removed-manifest-property	属性 '...' 已在 Manifest Version 2 中移除	移除该属性

使用时机

当你看到类似以下内容的 linter 输出时，应用此技能：

manifest.json:2:3 error manifest.json must be modernized to Version 2  no-outdated-manifest-version
manifest.json:15:5 error Use UI5 version 1.136.0 or higher in manifest.json  no-legacy-ui5-version-in-manifest
manifest.json:20:7 error Use of deprecated library 'sap.ui.commons'  no-deprecated-library
manifest.json:25:7 error Use of deprecated view type 'JSON'  no-deprecated-api
manifest.json:30:9 error Property '/sap.ui5/rootView/async' has been removed in Manifest Version 2  no-removed-manifest-property

修复策略

1. no-outdated-manifest-version - 将 _version 更新为 2.0.0

重要：只更新根级别的 _version 为 "2.0.0"。不要更改 sap.app、sap.ui、sap.ui5 等内部的嵌套 _version 属性——这些属性应保持当前值（例如 "1.1.0"、"1.2.0"）。

// Before
{
  "_version": "1.12.0",
  "sap.app": {
    "_version": "1.1.0",
    ...
  },
  "sap.ui5": {
    "_version": "1.2.0",
    ...
  }
}

// After — only root _version changed
{
  "_version": "2.0.0",
  "sap.app": {
    "_version": "1.1.0",
    ...
  },
  "sap.ui5": {
    "_version": "1.2.0",
    ...
  }
}

更新为 2.0.0 后，还必须应用以下连带变更：

• 移除 async 属性（参见第 6 节）
• 重命名路由配置属性（参见第 8 节）
• 在路由配置或 targets 中添加 type: "View"（参见第 8 节）

2. no-legacy-ui5-version-in-manifest - 更新 minUI5Version

// Before
"dependencies": {
  "minUI5Version": "1.120.0",
  ...
}

// After
"dependencies": {
  "minUI5Version": "1.136.0",
  ...
}

如果 minUI5Version 是数组，则将所有低于 1.136.0 的条目更新为该版本。

3. no-deprecated-library - 移除已弃用的库

从 sap.ui5/dependencies/libs 中移除以下已弃用的库：

• sap.ui.commons - 改用 sap.m
• sap.ui.ux3 - 改用 sap.m 和 sap.f
• sap.makit - 改用 sap.viz
• sap.me - 改用 sap.m
• sap.ca.ui - 改用标准控件
• sap.landvisz - 已弃用
• sap.ui.vtm - 已弃用
• sap.sac.grid - 自 1.112 起已弃用，1.114 起已移除
• sap.ui.suite - 自 1.108 起已弃用
• sap.zen.commons - 自 1.89 起已弃用
• sap.zen.crosstab - 自 1.89 起已弃用
• sap.zen.dsh - 自 1.89 起已弃用

// Before
"libs": {
  "sap.m": {},
  "sap.ui.commons": {},
  "sap.ui.layout": {}
}

// After
"libs": {
  "sap.m": {},
  "sap.ui.layout": {}
}

4. no-deprecated-component - 移除已弃用的组件

从 sap.ui5/dependencies/components 中移除已弃用的组件。

5. no-deprecated-api - 修复视图类型

将已弃用的视图类型改为 "XML"（对于以 JS 为主的视图，可改为 "Typed"）：

• JSON → XML
• HTML → XML
• JS → XML（对于复杂的 JS 逻辑，也可考虑使用 Typed 视图）
• Template → XML

适用于：

• sap.ui5/rootView/type
• sap.ui5/routing/config/viewType
• sap.ui5/routing/targets/*/viewType

// Before
"rootView": {
  "viewName": "my.app.view.Main",
  "type": "JSON"
}

// After
"rootView": {
  "viewName": "my.app.view.Main",
  "type": "XML"
}

重要：更改视图类型时，还必须将实际视图文件转换为 XML 格式。请标记此项以便人工审核。

6. no-removed-manifest-property - 移除异步属性（Manifest v2）

在 Manifest 版本 2.0.0 及更高版本中，根视图和路由配置的 async 标志会隐式设为 true，因此必须从且仅从以下两个位置移除：

• sap.ui5/rootView/async
• sap.ui5/routing/config/async

// Before (v2)
"rootView": {
  "viewName": "my.app.view.Main",
  "type": "XML",
  "async": true
}

// After (v2)
"rootView": {
  "viewName": "my.app.view.Main",
  "type": "XML"
}

范围警告——请勿从其他任何位置移除 async。 隐式异步行为仅适用于 rootView 和 routing.config。以下位置也可能合理地出现 async（必须保留）：

• sap.ui5/models/*/settings/async（例如，OData/JSON 模型的异步加载标志）
• 包含 async 的 sap.app/dataSources/* 设置
• sap.ui5/extends、sap.ui5/componentUsages 或第三方命名空间下的任何自定义配置
• 路由定义中除顶层 routing.config.async 之外的任何 async

no-removed-manifest-property 这条 lint 规则只会针对上述两个路径触发。请遵循 lint 指向的位置——只移除它标记的确切属性。

7. no-deprecated-api - 移除 sap.ui5/resources/js

如果数组为空，请移除整个 js 属性（如果 resources 也因此变为空，则一并移除）。

// Before
"resources": {
  "js": []
}

// After
// (resources section removed if empty)

如果数组不为空，则需要手动将其现代化为正确的模块依赖项。

8. 路由配置——重命名 Manifest 版本 2 的属性

将 _version 更新为 "2.0.0" 时，也必须重命名路由配置属性。以 view 为前缀的属性名在版本 2 中已弃用。

属性重命名规则：

旧属性（v1.x）	新属性（v2.0.0）	位置
viewPath	path	routing.config
viewName	name	routing.config 和 routing.targets.*
viewId	id	routing.targets.*
viewLevel	level	routing.targets.*
viewType	viewType	不变——保持原样

新增必需属性：

属性	值	位置
type	"View"	routing.config（适用于所有 targets）或每个单独的 routing.targets.* 条目

更新前（v1.x）：

"routing": {
    "config": {
        "routerClass": "sap.m.routing.Router",
        "viewType": "XML",
        "viewPath": "my.app.view",
        "controlId": "app",
        "controlAggregation": "pages",
        "async": true
    },
    "routes": [
        {
            "name": "main",
            "pattern": "",
            "target": "main"
        }
    ],
    "targets": {
        "main": {
            "viewName": "Main",
            "viewId": "main",
            "viewLevel": 1
        },
        "detail": {
            "viewName": "Detail",
            "viewId": "detail",
            "viewLevel": 2
        }
    }
}

更新后（v2.0.0）：

"routing": {
    "config": {
        "routerClass": "sap.m.routing.Router",
        "viewType": "XML",
        "path": "my.app.view",
        "controlId": "app",
        "controlAggregation": "pages",
        "type": "View"
    },
    "routes": [
        {
            "name": "main",
            "pattern": "",
            "target": "main"
        }
    ],
    "targets": {
        "main": {
            "name": "Main",
            "id": "main",
            "level": 1
        },
        "detail": {
            "name": "Detail",
            "id": "detail",
            "level": 2
        }
    }
}

变更摘要：

• 将 config 中的 viewPath 改为 path
• 将每个 target 中的 viewName 改为 name
• 将每个 target 中的 viewId 改为 id
• 将每个 target 中的 viewLevel 改为 level
• viewType 保持为 viewType（不变）
• 仅从 routing.config 移除 async（v2 中隐式为 true）。请勿改动模型、dataSources 或其他无关配置中的 async——参见第 6 节的范围警告。
• 在 config 中添加 type: "View"（如果混合使用视图和组件，也可以在每个单独的 target 中添加 "type": "View"）

何时在 config 中添加 type，何时在每个 target 中添加：

• 在 config 中设置 type（最常见）：所有 targets 都是视图
• 在每个 target 中设置 type：路由 targets 混合使用（部分为视图，部分为组件）

实施步骤

1. 读取并解析 manifest.json 文件
2. 对每条 lint 错误（根据规则 ID 和消息识别）：
   • no-outdated-manifest-version：将根 _version 更新为 "2.0.0"（保持嵌套的 _version 值不变）
   • no-legacy-ui5-version-in-manifest：将 minUI5Version 更新为 "1.136.0"
   • no-deprecated-library：从依赖项中移除该库
   • no-deprecated-component：从依赖项中移除该组件
   • no-deprecated-api（视图类型）：改为 "XML"
   • no-deprecated-api（resources/js）：如果为空则移除
   • no-removed-manifest-property：移除该属性
3. 如果 _version 已更新为 2.0.0，还需应用路由现代化：
   • 在路由 config 和 targets 中，将 viewPath → path、viewName → name、viewId → id、viewLevel → level
   • 在 routing.config 中添加 type: "View"（或在每个 target 中添加）
   • 仅从 sap.ui5/rootView 和 sap.ui5/routing/config 移除 async。请勿从模型设置、dataSources 或任何其他路径移除 async——这些位置应保留其 async 标志。
4. 保留 JSON 格式（缩进）
5. 写入更新后的文件

示例修复

给定的 linter 输出：

manifest.json:2:3 error manifest.json must be modernized to Version 2  no-outdated-manifest-version
manifest.json:15:5 error Use UI5 version 1.136.0 or higher in manifest.json  no-legacy-ui5-version-in-manifest
manifest.json:20:7 error Use of deprecated library 'sap.ui.commons'  no-deprecated-library
manifest.json:35:9 error Property '/sap.ui5/rootView/async' has been removed in Manifest Version 2  no-removed-manifest-property
manifest.json:40:9 error Property '/sap.ui5/routing/config/async' has been removed in Manifest Version 2  no-removed-manifest-property

转换为：

// Before
{
  "_version": "1.12.0",
  "sap.app": {
    "_version": "1.1.0",
    ...
  },
  "sap.ui5": {
    "_version": "1.2.0",
    "dependencies": {
      "minUI5Version": "1.84.0",
      "libs": {
        "sap.m": {},
        "sap.ui.commons": {},
        "sap.ui.layout": {}
      }
    },
    "rootView": {
      "viewName": "my.app.view.Main",
      "type": "XML",
      "async": true
    },
    "routing": {
      "config": {
        "routerClass": "sap.m.routing.Router",
        "viewType": "XML",
        "viewPath": "my.app.view",
        "controlId": "app",
        "controlAggregation": "pages",
        "async": true
      },
      "routes": [
        { "name": "main", "pattern": "", "target": "main" }
      ],
      "targets": {
        "main": {
          "viewName": "Main",
          "viewId": "main",
          "viewLevel": 1
        }
      }
    }
  }
}

// After
{
  "_version": "2.0.0",
  "sap.app": {
    "_version": "1.1.0",
    ...
  },
  "sap.ui5": {
    "_version": "1.2.0",
    "dependencies": {
      "minUI5Version": "1.136.0",
      "libs": {
        "sap.m": {},
        "sap.ui.layout": {}
      }
    },
    "rootView": {
      "viewName": "my.app.view.Main",
      "type": "XML"
    },
    "routing": {
      "config": {
        "routerClass": "sap.m.routing.Router",
        "viewType": "XML",
        "path": "my.app.view",
        "controlId": "app",
        "controlAggregation": "pages",
        "type": "View"
      },
      "routes": [
        { "name": "main", "pattern": "", "target": "main" }
      ],
      "targets": {
        "main": {
          "name": "Main",
          "id": "main",
          "level": 1
        }
      }
    }
  }
}

注意事项

• 仅将根级 _version 更新为 2.0.0——切勿更改 sap.app、sap.ui、sap.ui5 等内部的嵌套 _version 属性。
• 将 _version 更新为 2.0.0 时，始终在同一轮操作中应用路由属性重命名并添加 type: "View"
• 将视图类型从 JSON/HTML/JS 更改为 XML 需要转换实际视图文件——请将此标记为后续任务
• 移除已弃用的库时，检查代码库中是否有来自这些库、需要现代化处理的导入
• 更新 minUI5Version 意味着应用无法在较旧版本的 UI5 上运行——这是为了兼容现代 UI5 而有意为之
• 将 _version 更新为 2.0.0 后，如果存在 synchronizationMode 和其他特定于 v1 的属性，也应将其移除
• Manifest v2 的严格性：Manifest v2.0.0 启用了更严格的错误处理——视图/片段中的语法错误现在会抛出错误，而不再静默失败
• sap.ui/supportedThemes 会在 manifest v2 中导致错误——如果存在，请将其移除
• Manifest v2 不会强制要求 IAsyncContentCreation——必须通过 fix-component-async 技能在 Component.js 中显式添加（此技能不处理此项）
• Typed View 替代方案：更改已弃用的视图类型（JS、JSON、HTML）时，默认替换为 XML；但对于包含大量 JS 的复杂视图，可考虑使用 Typed 视图作为替代方案

相关技能

• fix-component-async：更新 manifest.json 后，Component.js 需要实现 IAsyncContentCreation 接口——请交由该技能确定正确的放置位置
• fix-bootstrap-params：对于 HTML 启动代码中引用的已弃用库（data-sap-ui-libs），请使用 fix-bootstrap-params，而不是此技能