配置和实例化组件

学习目标

  • 实现并使用组件

组件

组件是 SAPUI5 应用中使用的独立且可复用的部分。它们有助于封装应用中紧密相关的部分。这使应用的结构及其代码更易于理解和维护。

SAPUI5 提供以下两种类型的组件：

  • 无界面组件（类：sap.ui.core.Component） 无界面组件没有用户界面，在不需要 UI 元素时用于编码，例如用于从后端系统提供数据的服务。

  • UI 组件（类：sap.ui.core.UIComponent） UI 组件扩展了无界面组件，并为组件添加了渲染功能。它们代表 UI 上的一个屏幕区域或元素及其相应的设置和元数据。本课程将介绍此组件类型。

component.js：提供组件方法的组件控制器。manifest.json：用于存储与组件关联的元数据的描述符。

组件有一个组件控制器（*Component.js*）和一个描述符（*manifest.json*）。只有组件控制器是必需的，但建议同时使用描述符文件。描述符随后包含组件元数据，并且还表达组件依赖关系和配置（见下文）。

组件的所有必需资源和可选资源都组织在一个唯一的命名空间中。组件的命名空间等于组件名称。

组件的可选资源例如包括 CSS、js 或 i18n 文件、视图和控制器。

图 Structure of a Component 给出了组件文件夹结构的示例。

描述符

描述符为存储与组件关联的元数据提供了一个集中的、机器可读且易于访问的位置。

描述符的数据以 JSON 格式存储在 *manifest.json* 文件中。

*manifest.json* 文件的存在必须在 *Component.js* 文件中定义的元数据中声明（见下文）。在组件元数据中进行声明会使组件加载 *manifest.json* 文件并读取与 SAPUI5 相关的条目。

manifest.json 文件的截图，如文中所述。

描述符的内容使用命名空间进行结构化，其中包括 sap.app、sap.ui 和 sap.ui5 命名空间（参见图 Structure of the Descriptor）：

  • 该 sap.app 命名空间提供应用特定的属性。

  • 该 sap.ui 命名空间提供 UI 特定的属性。

  • 该 sap.ui5 命名空间提供 SAPUI5 特定的属性。

每个新的 SAPUI5 版本都意味着一个新的描述符版本。此描述符格式版本由描述符根级别必需的 _version 属性的值描述（参见图 Structure of the Descriptor）。该属性的值如何与 SAPUI5 版本以及描述符版本精确对应，可在文档中找到。

sap.app 代码的截图，如下文所述。

图 sap.app Namespace 显示了 sap.app 命名空间中的一些属性。所有属性的完整清单可在文档中找到。

id 属性是必需属性，必须以点号记法提供，并指定项目的唯一 ID。它必须与相应 *Component.js* 文件中提供的命名空间匹配。

如果组件控制器是在那里创建的，例如通过

UIComponent.extend("sap.training.exc.Component", { . . . });

则 id 属性必须具有值 sap.training.exc。

项目的标题和描述使用 sap.app 命名空间的 title 和 description 属性进行维护。要使属性值依赖于语言，请在双花括号中指定键值：{{key}}

指定的键维护在扩展名为 .properties 的文件中。然后可以使用 i18n 属性指定指向此文件的 URL。该 URL 相对于 *manifest.json* 文件进行解释。所维护的文本如何以其他语言提供，将在课程后面讨论。

在描述符中为标题和描述引用的文本，例如可以被 SAP Fiori launchpad 读取。

sap.ui5 代码的截图，如下文所述。

图 sap.ui5 Namespace 显示了 sap.ui5 命名空间中的一些属性。

dependencies 属性包含对库和组件的外部依赖关系，这些库和组件在组件的初始化阶段由 SAPUI5 核心加载。此处引用的所有内容都可以直接在组件的代码中使用。

libs 属性包含 SAPUI5 核心应为组件加载以供使用的库。在该示例中，初始会加载 sap.ui.core 和 sap.m 库等。

minUI5Version 属性指定组件所需的最低 SAPUI5 版本。由于 SAPUI5 目前不强制使用正确的版本，minUI5Version 仅用于提供信息。如果不满足最低 SAPUI5 版本条件，控制台日志中会发出警告。

rootView 属性指定要打开的根视图。该属性的值可以是 XML 视图的视图名称字符串，也可以是包含 viewName（视图名称）和 type（视图类型）、id、async 以及 sap.ui.core.mvc.View 其他属性的视图配置对象。

在所示的示例中，模块名称为 sap.training.exc.view.App 的 XML 视图被设置为组件的根视图。它通过模块系统异步加载，并且具有 id App。这意味着当组件被实例化并嵌入 UI 时，App 视图会自动显示为初始视图。

使用组件

要渲染 UI 组件，必须将它们包装在 sap/ui/core/ComponentContainer 中。不能使用 placeAt 方法将 UI 组件直接放置在页面中。

组件容器将应用与嵌套组件分隔开。它是一个 SAPUI5 控件，可以嵌套在 SAPUI5 控件树中的任何位置。

要加载和创建 UI 组件，可以使用以下选项：

  • 在创建容器之前，使用 create 方法（属于 sap.ui.core.Component ）异步创建新的组件实例。然后可以将单独创建的组件实例传递给 sap.ui.core.ComponentContainer 的构造函数。

  • 在创建容器时，使用 sap.ui.core.ComponentContainer 的构造函数异步创建新的组件实例（参见以下示例）。

组件实例代码的截图，如下文所述。

在图 Creating a Component Instance 中，组件实例与组件容器一起被实例化。因此，进行实例化的模块依赖于 sap/ui/core/ComponentContainer。ComponentContainer 的构造函数接收一个设置对象，其中包含以下属性：

  • id 此属性用于传递要创建的组件容器实例的 Id。

  • name name 属性包含要实例化的组件的名称。

  • manifest 通过 manifest: true 使用所谓的 "manifest first" 功能。这允许 SAPUI5 在组件控制器之前加载和评估 *manifest.json* 描述符。建议这样做，因为它可以提高初始加载的性能。加载过程可以由此并行化并优化。描述符加载后，组件工厂可以在组件预加载的同时并行加载依赖项（SAPUI5 库和其他依赖组件）。

  • async async: true 用于指定组件应异步创建。

  • settings 设置对象在组件实例创建时传递给该组件实例。在该示例中，它用于设置组件实例 Id。

创建组件容器后，会在其上调用 placeAt 方法，以将其添加到 UI 区域。

将应用封装为组件

业务场景

在本练习中，您将把上一个练习中的应用重建为一个 SAPUI5 组件。所需的应用描述符（*manifest.json* 文件）和组件控制器（*Component.js* 文件）已包含在项目中。为实现封装，您将在这些文件中进行一些调整。最后，您将实例化组件并将其嵌入 HTML 页面。*Template:*Git Repository: https://github.com/SAP-samples/sapui5-development-learning-journey.git, Branch: **sol/5_controllers***Model solution:*Git Repository: https://github.com/SAP-samples/sapui5-development-learning-journey.git, Branch: sol/6_components

任务 1：调整应用描述符

步骤

  1. 在编辑器中打开 *webapp* 文件夹中的 *manifest.json* 文件。

  2. 将 sap.app 命名空间中的 id 属性设置为值 sap.training.exc，以指定项目的 ID。

  3. 按如下方式修改 *manifest.json* 文件第 4 行的内容：

"id": "",

  1. 将 sap.ui5 命名空间中的 rootView 属性设置为值 sap.training.exc.view.App，以将项目中的 App 视图指定为要打开的根视图。

  2. 按如下方式修改 *manifest.json* 文件第 102 行的内容：

"viewName": "",

任务 2：维护组件的标题和描述

步骤

  1. 在编辑器中打开 *webapp/i18n* 文件夹中的 *i18n.properties* 文件。

  2. 在此处添加以下行，以维护组件的语言相关标题以及语言相关描述：

# App Descriptor
appTitle=Exercise Application
appDescription=A simple app that demonstrates important concepts of SAPUI5

注意

该 appTitle 和 appDescription 键在 manifest.json 文件（属性 sap.app/title 和 sap.app/description）中用于设置组件的标题和描述。

结果

*i18n.properties* 文件现在应如下所示：

i18n.properties 文件，如前面的文本所述。

任务 3：调整引导脚本

步骤

  1. 在编辑器中打开 *webapp* 文件夹中的 *index.html* 页面。

  2. 删除引导脚本中的以下属性：

data-sap-ui-libs="sap.m"

注意

组件所需的因而需要由 SAPUI5 加载的库在组件的应用描述符中指定（属性 sap.ui5/dependencies）。该 sap.m 库列在那里，因此不再需要由引导脚本加载。

结果

引导脚本现在应如下所示：

HTML 文件中 script 标签的截图。

任务 4：编辑组件控制器

步骤

  1. 在编辑器中打开 *webapp* 文件夹中的 *Component.js* 文件。

  2. 将以下代码添加到组件控制器实现中，以确保加载并使用应用描述符 *manifest.json*：

metadata: {
manifest: "json"
},
init: function () {
// call the base component's init function
UIComponent.prototype.init.apply(this, arguments);
}

注意

该 init() 方法在组件实例化时由框架调用。稍后，您将在此方法中为组件实现必要的初始化。必须对基类的 init() 函数进行超类调用，即在重写的 init() 方法中。

结果

*Component.js* 文件现在应如下所示：

Component.js 文件，突出显示 metadata 代码。

任务 5：实例化组件

步骤

  1. 确保 *index.js* 模块已在编辑器中打开。

  2. 删除 *index.js* 模块中实例化 XML 视图并将其放置在 HTML 页面上的代码。

  3. 删除以下行：

XMLView.create({
id: "App",
viewName: "sap.training.exc.view.App"
}).then(function (oView) {
oView.placeAt("content");
});

注意

您将在下一步中实例化组件并将其放置在 HTML 页面上，而不是使用 XML 视图。组件实例随后将把 App 视图显示为根视图。

结果

该 index.js 模块现在应如下所示： 生成的 index.js 文件。 3. 现在按如下方式修改 *index.js* 模块的实现，以实例化组件并将其放置在 HTML 页面上：

sap.ui.define(["sap/ui/core/ComponentContainer"], function (ComponentContainer) {
"use strict";
var oContainer = new ComponentContainer({
id: "container",
name: "sap.training.exc",
manifest: true,
async: true,
settings: {
id: "sap.training.exc"
}
});
oContainer.placeAt("content");
});

注意

请注意已更改的依赖数组和工厂函数的参数。index.js 现在依赖于 sap/ui/core/ComponentContainer 而不是 sap/ui/core/mvc/XMLView。

结果

该 index.js 文件应按如下方式实现： 生成的 index.js 文件， 4. 通过从 SAP Business Application Studio 启动应用来测试运行您的应用。

  1. 右键单击 sapui5-development-learning-journey 项目中的任意子文件夹，然后从出现的上下文菜单中选择 Preview Application。

  2. 在出现的对话框中选择名为 start-noflp 的 npm 脚本。

  3. 在打开的应用中，检查组件是否以 App 视图作为根视图显示。