SAPUI5基础知识12 - 应用程序描述符（manifest.json）

1. 背景

在SAPUI5中，manifest.json是一个配置文件，它包含了应用程序的所有配置信息。这个文件是SAPUI5应用程序的核心，它定义了应用程序的元数据，包括应用程序的名称、描述、版本、模型、路由等信息。

manifest.json的主要功能和用途包括：

元数据：定义应用程序的基本信息，如名称、描述、版本等。
模型：定义应用程序的数据模型，包括服务URL、数据类型等。
路由：定义应用程序的路由信息，包括路由模式、路由路径等。
i18n：定义应用程序的国际化信息，包括语言、地区等。

将应用程序的配置信息抽取到manifest.json中，可以让应用程序编码与配置设置相互分离，这让应用程序更加具有灵活性。

所有SAP Fiori应用程序都是作为组件实现的，并带有一个描述符文件，这可以让这些应用程序方便地托管在SAP Fiori launchpad中。

2. 用法

一个完整的组件应包含两部分：组件控制器文件(component .js)和应用程序描述描述符文件(manifest.json)。

manifest.json与Component.js的关系是，Component.js是SAPUI5应用程序的入口点，它会读取manifest.json文件中的配置信息，然后根据这些信息初始化应用程序。

在SAPUI5的早期版本中，这些配置信息是直接写在Component.js文件中的，但是随着应用程序的复杂性增加，将这些配置信息抽取出来，放在一个单独的manifest.json文件中，可以使代码更加清晰，更易于管理。

SAP Fiori launchpad充当应用程序容器并实例化应用程序，而无需本地HTML文件作为引导。manifest.json描述符文件将被解析并将组件加载到当前HTML页面中。这种方式允许在同一个context中显示多个应用程序，而且每个应用都可以定义自身的设置（例如语言属性、支持的设备等）。与此同时，我们还可以使用描述符文件来加载额外的资源并实例化模型，就像我们的i18n资源包一样。

3. 练习

在上一篇博客练习的基础上，让我们封装mainfest.json文件。

3.1 创建/更新manifest.json文件

首先，让我们在webapp文件夹下，创建mainfest.json文件。

在这里插入图片描述

注意: 如果我们之前已经使用ui5 init命令初始化项目，manifest.json文件已经生成，因为使用SAPUI5工具运行应用程序是必要的。

manifest.json文件是一个json格式的配置对象，包含所有全局应用程序设置和参数。manifest文件被称为应用程序、组件和库的描述符，它存储在webapp文件夹中，并由SAPUI5读取以实例化组件。

下面是初始的mainfest.json文件的内容：

{
    "_version": "1.58.0",
    "sap.app": {
        "id": "zsapui5.test"
    }
}

让我们更新manifest.json文件内容如下：

{
    "_version": "1.58.0",
    "sap.app": {
      "id": "zsapui5.test",
      "i18n": "i18n/i18n.properties",
      "title": "{{appTitle}}",
      "description": "{{appDescription}}",
      "type": "application",
      "applicationVersion": {
        "version": "1.0.0"
      }
    },
    "sap.ui": {
      "technology": "UI5",
      "deviceTypes": {
          "desktop": true,
          "tablet": true,
          "phone": true
      }
    },
    "sap.ui5": {
      "dependencies": {
        "minUI5Version": "1.108.0",
        "libs": {
          "sap.ui.core": {},
          "sap.m": {}
        }
      },
      "models": {
        "i18n": {
          "type": "sap.ui.model.resource.ResourceModel",
          "settings": {
            "bundleName": "zsapui5.test.i18n.i18n",
            "supportedLocales": [""],
            "fallbackLocale": ""
          }
        }
      },
      "rootView": {
          "viewName": "zsapui5.test.view.App",
          "type": "XML",
          "id": "app"
      }
    }
  }

manifest.json文件中的命名空间定义了三个重要的部分:

sap.app: sap.app命名空间包含以下特定于应用程序的属性:
- id(必选):应用程序组件的命名空间。ID不能超过70个字符。必须唯一，必须与组件ID/命名空间对应。
- type:定义我们想要配置的内容; 这是一个应用程序。
- i18n:定义资源包文件的路径。
- title:应用的handlebars语法中的标题，从应用的资源包中引用。
- description:简短的描述文本, 应用程序在handlebars语法中做了什么，引用自应用程序的资源包。
- applicationVersion:应用程序的版本，以后可以方便地更新应用程序。
sap.ui: sap.ui命名空间提供了以下特定于ui的属性:
- technology:这个值指定了UI的技术;在我们的例子中，我们使用SAPUI5
- deviceTypes:告诉应用程序支持哪些设备: 桌面，平板，手机(默认为true)
sap.ui5: sap.ui5命名空间添加SAPUI5特定的配置参数，由SAPUI5自动处理。最重要的参数有:
- rootView:如果指定这个参数，组件将自动实例化视图，并将其用作该组件的root
- dependencies 依赖关系, 在这里我们声明应用程序中使用的UI库
- models：在描述符的本节中，我们可以定义模型，这些模型将在应用程序启动时由SAPUI5自动实例化。这里我们可以定义了本地资源包。我们将模型的名称“i18n”定义为键，并通过命名空间指定打包文件。与前面的步骤一样，包含翻译后文本的文件存储在i18n文件夹中，并命名为i18n.properties。我们只需在文件的路径前加上应用程序的命名空间。应用程序组件文件（Component.js）中的init方法中的手动实例化将在稍后的步骤中删除。supportedLocales和fallbackLocale属性被设置为空字符串，在我们的演示应用程序中只使用一个i18n，为了简单起见，我们希望阻止浏览器加载额外的i18n_*。

出于兼容性的考虑，根对象和每个部分都在内部属性_version下声明了描述符的版本号1.58.0。在描述符的未来版本中可能会添加或更改功能，版本号有助于通过读取描述符的工具识别应用程序设置。

资源包的属性在描述符中包含在两个大括号中。这不是SAPUI5数据绑定语法，而是handlebars语法中描述符中对资源包的变量引用。参考文本在本教程构建的应用程序中不可见，但可以通过SAP Fiori launchpad等应用程序容器读取。

3.2 更新index.html引导过程文件

项目的index.js文件用于创建组件加载器并加载应用程序的组件。这个自定义逻辑可以被一个叫做ComponentSupport的内置模块替换。我们可以直接在bootstrap中使用此模块，以消除自定义index.js文件的需求。

首先，需要增强index.html的主体部分。

在index.html的引导脚本中，启用ComponentSupport模块。然后，我们通过div标签在body中声明我们的组件(div标签将被用作组件的容器)。这将在onInit事件执行时实例化组件。

我们将使用这个div将配置参数传递给ComponentSupport模块。为了实现这个目标，我们需要给div标签添加data-*属性，包括必须添加的data-sap-ui-component属性，该属性将div标记为组件的父元素。

...
    data-sap-ui-onInit="module:sap/ui/core/ComponentSupport"
...
   <div data-sap-ui-component data-name="zsapui5.test" data-id="container" data-settings='{"id" : "test"}'>
...

在这里插入图片描述

改动后的代码如下：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>My SAPUI5 Test</title>
    <script
    id="sap-ui-bootstrap"
    src="https://sdk.openui5.org/resources/sap-ui-core.js"
    data-sap-ui-theme="sap_horizon"
    data-sap-ui-libs="sap.m"
    data-sap-ui-compatVersion="edge"
    data-sap-ui-async="true"
    data-sap-ui-onInit="module:sap/ui/core/ComponentSupport"
    data-sap-ui-resourceroots='{
        "zsapui5.test": "./"
    }'>
    </script>
</head>
<body class="sapUiBody" id="content"></body>
    <div data-sap-ui-component data-name="zsapui5.test" data-id="container" data-settings='{"id" : "test"}'></div>
</html>

3.3 删除index.js文件

现在，我们可以删除index.js文件了，因为我们通过启用ComponentSupport模块，已经完成了index.js中的任务。
在这里插入图片描述

3.4 更新i18n.properties文件

在资源包resource boundle中，为应用程序添加文本，并添加注释，从语义上分离资源包中的文本。
在这里插入图片描述

改动后的i18n.properties文件内容如下：

# App Descriptor
appTitle=Hello World
appDescription=A simple app that explains the most important concepts of SAPUI5

# Hello Panel
showHelloButtonText=Say Hello
helloMsg=Hello {0}

3.5 更新Component.js文件

在组件的元数据部分，我们现在用属性键manifest和值json替换rootView属性。这定义了对描述符的引用，该引用将在组件实例化时自动加载和解析。

我们现在可以完全删除包含资源包的模型实例化的代码行。这是SAPUI5借助描述符中的配置项自动完成的。我们还可以删除对sap/ui/model/resource/ResourceModel和相应的形式参数ResourceModel的依赖，因为我们不会在匿名回调函数中使用它。
在这里插入图片描述

在SAPUI5之前的版本中，应用程序的其他配置设置，如服务配置、根视图和路由配置，必须添加到Component.js文件的metadata部分。从SAPUI5 1.30版本开始，建议在manifest.json中定义这些设置。基于SAPUI5旧版本创建的应用程序仍然使用Component.js文件来完成此目的 ( 这种方式仍然支持，但不再推荐 )。

改动后的Component.js文件内容如下：

sap.ui.define([
    "sap/ui/core/UIComponent",
    "sap/ui/model/json/JSONModel"
], function (UIComponent,JSONModel) {
    "use strict";

    return UIComponent.extend("zsapui5.test.Component", {
        metadata: {
            "interfaces": ["sap.ui.core.IAsyncContentCreation"],
            "manifest": "json"
        },

        init() {
            //call  the init function of the parent
            UIComponent.prototype.init.apply(this, arguments);

            //set data model
            const oData = {
                recipient : {
                    name: "World"
                }
            };
            const oModel = new JSONModel(oData);
            this.setModel(oModel);
        }
    });
});