迁移现有的 Cordova 和混合应用程序

概述

要迁移使用 IBM MobileFirst Foundation V6.2.0 或更高版本创建的现有 Cordova 或混合应用程序，必须创建 Cordova 项目以使用当前版本中的插件。 然后，替换 V8.0 中停用或不包含的客户端 API。 迁移辅助工具可帮助您执行此任务。

跳至：

• 使用 V8.0 开发的 Cordova 应用程序与使用 V7.1 及更低版本开发的 Cordova 应用程序的比较
• 将现有混合或跨平台应用程序迁移到 IBM Mobile Foundation 8.0 支持的 Cordova 应用程序
• 为 iOS Cordova 迁移加密
• 迁移“直接更新”
• 升级 WebView
• 已移除的组件

使用 V8.0 开发的 Cordova 应用程序与使用 V7.1 及更低版本开发的 Cordova 应用程序的比较

将使用 MobileFirst V8.0 开发的 Cordova 应用程序与使用 IBM MobileFirst Platform Foundation V7.1 开发的 Cordova 和混合应用程序进行比较。

将现有混合或跨平台应用程序迁移到 Mobile Foundation 8.0 支持的 Cordova 应用程序

您可以将使用 IBM MobileFirst Platform Foundation V6.2 或更高版本开发的现有混合或跨平台 (Cordova) 应用程序迁移到 Mobile Foundation V8.0 支持的 Cordova 应用程序。

跳转到相关部分

• 使用迁移辅助工具启动 Cordova 应用程序迁移
• 完成 MobileFirst 混合应用程序的迁移
• 完成 MobileFirst Cordova 应用程序的迁移

使用迁移辅助工具启动 Cordova 应用程序迁移

迁移辅助工具可帮助您准备通过 MobileFirst 的更低版本创建的跨平台应用程序进行迁移，方法是识别不再有效的 API 并将项目复制到 V8.0 支持的 Cordova 应用程序。

使用迁移辅助工具之前，务必了解以下信息：

• 您必须拥有现有的 IBM MobileFirst Platform Foundation 混合应用程序或者使用 mfp cordova create 命令创建的 Cordova 应用程序。
• 您必须具有因特网访问权。
• 您必须已安装 node.js V4.0.0 或更高版本。
• 您必须已安装 Cordova 命令行界面 (CLI)，并且安装对目标平台使用 Cordova CLI 所需的任何必备软件。 有关更多信息，请参阅 Apache Cordova Web 站点中的 The Command-Line Interface。
• 查看并了解迁移过程的限制。 有关更多信息，请参阅从先前发行版迁移应用程序。

针对使用较早版本的 IBM MobileFirst Platform Foundation 命令创建的跨平台应用程序或使用 IBM MobileFirst Platform Foundation 命令创建的 Cordova 应用程序，在未进行一些更改的情况下在 V8.0 中不受支持。 迁移辅助工具可通过以下功能简化此过程：

• 扫描现有混合应用程序或使用 IBM MobileFirst Platform Foundation 应用程序开发的 Cordova 应用程序中的 JavaScript 和 HTML 文件，识别 V8.0 中不推荐使用、不再支持或修改的 API。
• 将初始混合应用程序或使用 IBM MobileFirst Platform Foundation 应用程序开发的 Cordova 应用程序的结构、脚本和配置文件复制到 V8.0 中支持的 Cordova 结构。

迁移辅助工具不会修改或移动应用程序的任何开发人员代码或注释。 您必须在运行此工具之后通过完成 MobileFirst 混合应用程序的迁移或完成 MobileFirst Cordova 应用程序的迁移来继续迁移过程。

1. 安装迁移辅助工具。
   • 切换至下载 .tgz 文件的目录。
   • 通过输入以下命令，使用 NPM 安装该工具：

   npm install -g tgz_filename
   

   有关 mfpmigrate-cli npm 包的详细信息，请单击此处。

2. 通过输入以下命令来扫描和复制 IBM MobileFirst Platform Foundation 应用程序：

   mfpmigrate client --in source_directory --out destination_directory --projectName new-project-directory
   

   • source_directory
     您正在迁移的项目的当前位置。 在混合应用程序中，这应当指向应用程序的 application 文件夹。
   • destination_directory
     与 V8.0 兼容的新 Cordova 结构所输出的目录的可选名称。 此目录是 new-project-directory 文件夹的父目录。 如果未指定，那么将在运行命令的目录中创建此文件夹。
   • new-project-directory 项目新内容所在的文件夹的可选名称。 此文件夹位于 destination_directory 文件夹中，包含 Cordova 应用程序的所有信息。如果未指定此选项，那么缺省名称为 app_name-app_id-version。
     与 client 命令一起使用时，迁移辅助工具会完成以下操作：
     • 识别现有 IBM MobileFirst Platform Foundation 应用程序中在 V8.0 中已移除、不推荐使用或更改的 API。
     • 根据初始应用程序的结构创建 Cordova 结构。
     • 视情况复制或添加以下项：
       • Android 操作系统
       • iPhone 和 iPad 操作系统
       • Windows 操作系统
       • Cordova-mfp-plugin
       • Cordova-plugin-mfp-jsonstore 插件（如果在旧项目上安装了 JSONStore 功能部件）。
       • Cordova-plugin-mfp-fips 插件（如果在旧项目上安装了 FIPS 功能部件）。
       • Cordova-plugin-mfp-push 插件（如果在旧项目上安装了推送通知功能部件）。
       • 混合证书（如果在旧项目上启用了证书锁定）。
       • 应用程序、脚本和 XML 文件
     • 完成该命令后，在缺省浏览器中打开生成的信息文件。

     要点：迁移辅助工具不会将开发人员代码或注释文本复制到新结构。

3. 在新 Cordova 应用程序中解决 API 问题。
   • 查看 api-report.html 文件，该文件在 destination_directory 目录中创建，并且在完成该命令时将在缺省浏览器中打开。 此文件中每个表行标识应用程序中使用的、与 V8.0 不兼容的一个不推荐使用、更改或移除的 API。 此文件还指定已移除 API 的替换项（如果可用）。

   文件路径	行号	API	行内容	API 更改的类别	描述和操作项
   c:\local\Cordova\www\js\index.js	15	WL.Client.getAppProperty	document.getElementById('app_version') textContent = WL.Client.getAppProperty("APP_VERSION");	不受支持	已从 8.0 移除。 使用 Cordova 插件以获取应用程序版本。 无替换 API。

   • 解决 api-report.html 文件中确定的 API 问题。
4. 将开发人员代码从初始应用程序结构手动复制到新 Cordova 结构中的正确位置。 根据源 IBM MobileFirst Platform Foundation 应用程序的类型，复制以下目录中的内容：
   • IBM MobileFirst Platform Foundation 混合应用
     将源应用程序的 common 目录内容复制到新 Cordova 应用程序中的 www 目录。
   • 使用 IBM MobileFirst Platform Foundation 应用程序开发的 Cordova 应用程序 将源应用程序的 www 目录内容复制到新 Cordova 应用程序中的 www 目录。
5. 针对新应用程序使用 scan 命令运行迁移辅助工具，以确认 API 更改是否完成。

   • 输入以下命令以运行扫描：

     mfpmigrate scan --in source_directory --out destination_directory --type hybrid
     

     • source_directory
       要扫描的文件的当前位置。 在 IBM MobileFirst Platform Foundation 混合应用程序中，此位置为应用程序的 common 目录。在 Mobile Foundation V8.0 Cordova 跨平台应用程序中，此位置为 www 目录。
     • destination_directory
       扫描结果的输出目录。
     • scan_type
       要扫描的项目的类型。

   • 解决 api-report.html 文件中确定的任何剩余 API 问题。

6. 重复步骤 6 以针对新的 Cordova 应用程序运行扫描工具，直到解决所有问题。

完成 MobileFirst 混合应用程序的迁移

使用迁移辅助工具后，必须手动修改代码的某些部分以完成迁移过程。

• 必须已对现有混合应用程序运行 mfpmigrate 迁移辅助工具。 有关更多信息，请参阅使用迁移辅助工具启动 Cordova 应用程序迁移。
• 您必须已安装 Cordova 命令行界面 (CLI)，并且安装对目标平台使用 Cordova CLI 所需的任何必备软件（如果需要安装任何其他 Cordova 插件）。 （请参阅步骤 6）。 有关更多信息，请参阅 Apache Cordova Web 站点上的命令行界面。
• 如果需要下载 JQuery 的新版本（步骤 1c），或者如果需要安装任何其他 Cordova 插件（步骤 6），那么必须具有因特网访问权。
• 如果需要安装其他 Cordova 插件（步骤 6），那么必须已安装 node.js V4.0.0 或更高版本。

完成本任务中的步骤，以完成将 MobileFirst 混合应用程序从 IBM MobileFirst Platform Foundation 7.1 迁移到包含 Mobile Foundation 8.0 支持的 Cordova 应用程序。

完成迁移后，应用程序可以使用独立于 IBM MobileFirst Platform Foundation 获取的 Cordova 平台和插件，并使用首选 Cordova 开发工具继续开发应用程序。

1. 更新 www/index.html 文件。

   • 将以下 CSS 代码添加到 index.html 文件头中已有的 CSS 代码之前。

     <link rel="stylesheet" href="worklight/worklight.css">
     <link rel="stylesheet" href="css/main.css">
     

     注：worklight.css 文件将 body 属性设置为 relative。如果这影响应用程序的样式，请在您自己的 CSS 代码中为 position 声明其他值。 例如：

     body {
           position: absolute;
     }
     

   • 将 Cordova JavaScript 添加到文件头中的 CSS 定义之后。

     <script type="text/javascript" src="cordova.js"></script>
     

   • 移除以下代码行（如果存在）。

     <script>window.$ = window.jQuery = WLJQ;</script>
     

     您可以下载自己的 JQuery 版本，并按以下代码行中所示将其装入。

     <script src="lib/jquery.min.js"></script>
     

     不必将可选的 jQuery 新增项移至 lib 文件夹。 可以将此新增项移至所需的任何位置，但必须在 index.html 文件中正确引用此项。

2. 将 www/js/InitOptions.js 文件更新为自动调用 WL.Client.init。

   • 从 InitOptions.js 中移除以下代码

     函数 WL.Client.init 使用全局变量 wlInitOptions 自动进行调用。

     if (window.addEventListener) {
           window.addEventListener('load', function() { WL.Client.init(wlInitOptions); }, false);
     } else if (window.attachEvent) {
           window.attachEvent('onload',  function() { WL.Client.init(wlInitOptions); });
     }
     

3. 可选：将 www/InitOptions.js 更新为手动调用 WL.Client.init。
   • 编辑 config.xml 文件并将 <mfp:clientCustomInit> 元素的 enabled 属性设置为 true。

   • 如果使用的是 MobileFirst 混合缺省模板，请将以下代码：

     if (window.addEventListener) {
           window.addEventListener('load', function() { WL.Client.init(wlInitOptions); }, false);
     } else if (window.attachEvent) {
           window.attachEvent('onload',  function() { WL.Client.init(wlInitOptions); });
     }
     

     替换为以下代码：

     if (document.addEventListener) {
           document.addEventListener('mfpready', function() { WL.Client.init(wlInitOptions); }, false);
     } else if (window.attachEvent) {
           document.attachEvent('mfpready',  function() { WL.Client.init(wlInitOptions); });
     }
     

4. 可选：如果您具有特定于混合环境的逻辑（例如在 app/iphone/js/main.js 中），请复制函数 wlEnvInit() 并将其附加在 www/main.js 的结尾。

   // This wlEnvInit method is invoked automatically by MobileFirst runtime after successful initialization.
   function wlEnvInit() {
        wlCommonInit();
        if (cordova.platformId === "ios") {
            // Environment initialization code goes here for ios
        } else if (cordova.platformId === "android") {
            // Environment initialization code goes here for android
        }
   }
   

5. 可选：如果原始应用程序使用 FIPS 功能部件，请将 JQuery 事件侦听器更改为侦听 WL/FIPS/READY 事件的 JavaScript 事件侦听器。 有关 FIPS 的更多信息，请参阅 FIPS 140-2 支持。
6. 可选：如果原始应用程序使用迁移辅助工具没有替换或提供的任何第三方 Cordova 插件，请使用 cordova plugin add 命令将这些插件手动添加到 Cordova 应用程序。 有关此工具替换了哪些插件的信息，请参阅使用迁移辅助工具启动 Cordova 应用程序迁移。

完成 MobileFirst Cordova 应用程序的迁移

使用迁移辅助工具后，必须手动修改代码的某些部分以完成迁移过程。

• 必须已对现有 Cordova 应用程序运行 mfpmigrate 迁移辅助工具。 有关更多信息，请参阅使用迁移辅助工具启动 Cordova 应用程序迁移。
• 您必须已安装 Cordova 命令行界面 (CLI)，并且安装对目标平台使用 Cordova CLI 所需的任何必备软件。 有 关更多信息，请参阅 Apache Cordova Web 站点上的命令行界面。
• 您必须具有因特网访问权。
• 您必须已安装 node.js V4.0.0 或更高版本。

通过 mfp cordova create 创建的 Cordova 应用程序使用 IBM MobileFirst Platform Foundation 先前版本随附的 Cordova 平台和插件版本。 完成迁移后，已迁移的应用程序可以使用独立于 Mobile Foundation 获取的 Cordova 平台和插件。 这是 IBM MobileFirs Foundation V8.0 提供的唯一一种 Cordova 应用程序支持。

要进行迁移，请运行迁移辅助工具，然后对应用程序进行其他修改。

1. 通过所选的 Cordova 开发工具，添加除用于启用原始应用程序中包含的 MobileFirst 功能部件的 Cordova 插件以外的任何 Cordova 插件。 例如，通过 Cordova CLI，要添加插件 cordova-plugin-file 和 cordova-plugin-file-transfer，请输入：

   cordova plugin add cordova-plugin-file cordova-plugin-file-transfer
   

   注：mfpmigrate 迁移辅助工具已针对 MobileFirst 功能部件添加 Cordova 插件，因此您不必添加这些插件。 有关这些插件的更多信息，请参阅 MobileFirst 的 Cordova 插件。

2. 可选：如果原始应用程序使用 FIPS 功能部件，请将 JQuery 事件侦听器更改为侦听 WL/FIPS/READY 事件的 JavaScript 事件侦听器。 有关 FIPS 的更多信息，请参阅 FIPS 140-2 支持。
3. 可选：如果原始应用程序使用迁移辅助工具没有替换或提供的任何第三方 Cordova 插件，请使用 cordova plugin add 命令将这些插件手动添加到 Cordova 应用程序。 有关此工具替换了哪些插件的信息，请参阅使用迁移辅助工具启动 Cordova 应用程序迁移。
4. 可选：（仅适用于包含 iOS 平台且使用 OpenSSL 的应用程序。） 将 cordova-plugin-mfp-encrypt-utils 插件添加到应用程序。cordova-plugin-mfp-encrypt-utils 插件为使用 iOS 平台的 Cordova 应用程序提供用于加密的 iOS OpenSSL 框架。

您现在具有可以通过首选 Cordova 工具继续开发的 Cordova 应用程序，但其中还包含 MobileFirst 功能。

为 iOS Cordova 迁移加密

如果 iOS 混合应用程序或 Cordova 应用程序已使用 OpenSSL 加密，那么可能需要将应用程序迁移到新的 V8.0.0 本机加密。 如果要继续使用 OpenSSL，那么必须添加额外的 Cordova 插件。

有关用于迁移的 iOS Cordova 加密选项的更多信息，请参阅在 Cordova 应用程序中启用 OpenSSL 主题中的迁移选项部分。

迁移“直接更新”

首次访问受保护资源后会触发“直接更新”。 在 V8.0 中，已更改了用于部署新 Web 资源的过程。

与先前版本不同，在 V8.0 中，如果应用程序不访问安全的 MobileFirst 资源，那么客户机应用程序不会接收更新，即使在服务器上有可用更新也如此。 资源可能不受保护，例如，因为 OAuth 已由注释 @OAuth(security=false) 或由配置禁用。 您可以通过以下其中一种方式绕过此风险：

• 显式获取访问令牌。 请参阅 WLAuthorizationManager 类中的 obtainAccessToken API。
• 调用其他受保护资源。 请参阅 WLResourceRequest 类。

要使用“直接更新”：从 V8.0 开始，不再将 .wlapp 文件上载到 MobileFirst Server。 而是上载较小的 Web 资源归档（.zip 文件）。 该归档文件不再包含在先前版本中广泛使用的 Web 预览文件或外表。 已停用这些功能。 该归档仅包含发送到客户机的 Web 资源以及“直接更新”验证的校验和。

有关更多信息，请参阅“直接更新”文档。

升级 WebView

IBM MobileFirs Foundation V8.0 Cordova SDK (JavaScript) 引入了许多需要调整代码的更改。

手动迁移过程涉及几个阶段：

• 创建新的 Cordova 项目
• 将必需的 Web 资源元素替换为先前版本中的代码
• 对 JavaScript 代码进行必需的更改以符合 SDK 更改

在 V8.0 中移除了许多 MobileFirst API 元素。 在支持 JavaScript 自动更正的 IDE 中，已移除的元素明确标记为不存在。

下表列出了需要移除的 API 元素，并附带有关如何替换功能的建议。 许多已移除的元素是可以替换为 Cordova 插件或 HTML 5 元素的 UI 元素。 某些方法已更改。

停用的 JavaScript UI 元素

其他停用的 JavaScript 元素

不推荐使用的 JavaScript API

已移除的组件

MobileFirst Platform Foundation Studio 7.1 创建的 Cordova 项目包含许多支持格局功能的资源。 但是，在 V8.0 中仅支持纯 Cordova，并且 MobileFirst API 不再支持这些功能。

外表

MobileFirst 应用程序外表提供了用于优化 UI 以适应不同设备和格式的方法，并且在 V8.0 中不再受支持。
要替换此类型的功能，建议采用由 Cordova 和 HTML 5 提供的响应式 Web 设计方法。

Shell

Shell 允许开发供应用程序使用并在其之间共享的功能集。 通过此方式，具有更多本机环境经验的开发人员可以提供核心功能集。 这些 shell 捆绑到内部应用程序中，并且供涉及业务逻辑或 UI 开发的开发人员使用。

如果先前混合应用程序使用 shell 和内部应用程序，那么建议采用 Cordova 设计模式，并将 shell 组件作为可以跨应用程序共享的 Cordova 插件进行实施。 开发人员可能会找到方法来复用部分 shell 代码并将其迁移到 Cordova 插件。

例如，如果客户具有跨所有应用程序通用的一组 Web 资源（JavaScript、css 文件、图形、html），那么可以创建用于将这些资源复制到应用程序的 www 文件夹中的 Cordova 插件。

假设这些资源位于 src/www/acme/ 文件夹中：

• src/www/acme/js/acme.js
• src/www/acme/css/acme.css
• src/www/acme/img/acme-logo.png
• src/www/acme/html/banner.html
• src/www/acme/html/footer.html
• plugin.xml

plugin.xml 文件包含 <asset> 标记，此标记包含用于复制资源的源和目标：

<?xml version="1.0" encoding="UTF-8"?>
<plugin
     xmlns="http://apache.org/cordova/ns/plugins/1.0"     
     xmlns:rim="http://www.blackberry.com/ns/widgets"
     xmlns:android="http://schemas.android.com/apk/res/android"
     id="cordova-plugin-acme"
     version="1.0.1">
<name>ACME Company Shell Component</name>
<description>ACME Company Shell Component</description>
<license>MIT</license>
<keywords>cordova,acme,shell,components</keywords>
<issue>https://www.acme.com/support</issue>
<asset src="src/www/acme" target="www/acme"/>
</plugin>

将 plugin.xml 添加到 Cordova config.xml 文件后，asset src 中所列的资源在编译期间会复制到 asset 目标中。
然后，在其 index.html 文件中或其应用程序内的任何位置，可以复用这些资源。

<link rel="stylesheet" type="text/css" href="acme/css/acme.css">
<script type="text/javascript" src="acme/js/acme.js"></script>
<div id="banner"></div>
<div id="app"></div>
<div id="footer"></div>
<script type="text/javascript">
    $("#banner").load("acme/html/banner.html");
    $("#footer").load("acme/html/footer.html");
</script>

“设置”页面

设置页面是 MobileFirst 混合应用程序中提供的 UI，开发人员可以通过该页面在运行时更改服务器 URL 以进行测试。 开发人员现在可以使用现有 MobileFirst 客户机 API 在运行时更改服务器 URL。 有关更多信息，请参阅 WL.App.setServerUrl。

缩小

MobileFirst Studio 7.1 提供了 OOTB 方法，通过在编译前移除所有不必要的字符来减少 JavaScript 代码量。 可以通过向项目中添加 Cordova 挂钩来替换这一已移除的功能。

许多挂钩可用于缩小 JavaScript 和 CSS 文件。 这些挂钩可放在应用程序的 config.xml 文件的 before_prepare 事件中。

以下是一些建议挂钩：

• https://www.npmjs.com/package/uglify-js
• https://www.npmjs.com/package/clean-css

通过使用 <hook> 元素，这些挂钩在插件文件中或在应用程序的 config.xml 文件中定义。
在此示例中，通过使用 before_prepare 挂钩事件，在 Cordova prepares 将文件复制到各平台的 www/ 文件夹之前运行脚本以执行缩小代码操作：

<hook type="before_prepare" src="scripts/uglify.js" />