将 Cordova 项目转换为 PhoneGap 项目

2015-06-09

PhoneGap 是一个开源框架，用于使用 HTML5、JavaScript 和 CSS 快速创建跨平台的移动应用程序。 Adobe PhoneGap Build 是一种云服务，使你可快速创建移动应用程序并轻松地对其进行编译，而无需 SDK、编译器和硬件。本文介绍了如何将用 Visual Studio 创建的 Apache Cordova 项目转换为 PhoneGap 项目以及如何使用 PhoneGap Build 云服务。

Visual Studio 项目和 PhoneGap 项目之间的主要区别之一是配置文件 (config.xml) 中的应用程序定义。若要将 Visual Studio 项目更改为 PhoneGap 项目，需要执行以下任务：

从 Visual Studio 项目中生成 Cordova 项目
创建 PhoneGap 项目结构
更新 config.xml
上载到云生成
代码签名和配置应用

从 Visual Studio 项目中生成一个 Cordova 项目

我们将先看一个例子，关于用 Apache Cordova 的 Visual Studio 工具所创建的项目的项目结构。

Visual Studio 中的 Cordova 项目结构

若要成功创建，基于云的 PhoneGap Build 仅需要应用程序的 Web 资产，这些资产限于你的 HTML、CSS、图像、.js 文件等。如果上载了本机文件（.h、.m、.java 等），PhoneGap Build 将可能无法编译你的应用程序。获取应用程序的 Web 资产的最简单方法是生成 Visual Studio 项目，该项目随后会在 bld/Debug 文件夹中创建一个 Cordova CLI 项目，如下所示。 Cordova CLI 项目的 www 文件夹承载在你的应用程序中使用的所有 Web 资产，如下所示。

Cordova 项目的输出文件夹结构

一旦生成 www 文件夹后，即可创建 PhoneGap Build 项目。我们建议你先创建一个新文件夹（在 Visual Studio 项目位置之外）来承载 PhoneGap 项目，然后将 Cordova CLI 项目的 www 文件夹从 bld/debug 位置复制到新位置。

创建 PhoneGap 项目结构

构建 PhoneGap 项目时，请确保 config.xml 和 index.html 位于你的应用文件夹结构的顶层。或者，可根据需要构建你的应用程序。将 config.xml 从 bld/debug 文件夹复制到 PhoneGap Build 项目的 www 文件夹。另外，将你的本机资源从 Cordova CLI 项目（分别对应 bld\Debug\res\icons 和 bld\debug\res\screens）复制到 PhoneGap Build 项目的根目录。

复制完所有文件和文件夹后，PhoneGap Build 项目应像这样。

PhoneGap 项目结构

因为你的应用程序可能包含最终打包应用程序中不需要的文件或文件夹（例如未使用的初始屏幕、Bower 包、Grunt 项目、未编译的更少文件等），所以 PhoneGap Build 支持名为.pgbomit 的特殊文件。

.pgbomit 是你可创建和添加到文件夹以指示 PhoneGap Build 将该文件夹作为本机应用程序文件的来源排除的文件。（但是，你可使用此文件夹来存储 PhoneGap 生成过程到编辑步骤中所需的任何文件。）一个典型示例是，你可能想要将.pgbomit 放置在包含图标和初始屏幕的文件夹中。所以请将 .pgbomit 放置在 PhoneGap Build 项目的 www/res 文件夹中；由此，二进制应用包中将不包含 www/res 中的任何文件和文件夹，除了那些复制以及用于特定平台的图标和初始屏幕的文件和文件夹。下图显示了 www/res 文件夹中的 .pgbomit 文件。

pgbomit 文件的位置

由于在默认情况下 PhoneGap Build 不支持 Cordova CLI 项目的“合并项”文件夹，所以你需要将特定于平台的内容从 Cordova CLI 项目的“合并项”文件夹复制到 PhoneGap Build 项目的 www 文件夹中。

更新 Config.xml

PhoneGap Build 支持配置 XML 文件 config.xml，该文件与 Visual Studio 项目生成的文件截然不同。通过此配置文件，你可修改应用程序的标题、图标、初始屏幕和其他属性等。

首先删除 VS 命名空间，并将 PhoneGap 命名空间添加到 config.xml。结果如此处所示。

<widget xmlns:cdv="http://cordova.apache.org/ns/1.0"
  id="io.cordova.appb64ec64666e9432a9caf5f01009feb88"
  version="1.0.0.0"
  xmlns:gap="http://phonegap.com/ns/1.0"
  xmlns="http://www.w3.org/ns/widgets">
<name>SlidePuzzle</name>

图标

默认图标必须命名为 icon.png，并且必须驻留在应用程序文件夹的根目录中。除非你在 config.xml 中另外指定，否则每个平台都将在编译期间尝试使用默认 icon.png。

<icon src="icon.png" />

如果你想获取 Android 平台的特定图标，以下项显示了一个例子，关于如何基于先前创建的 PhoneGap Build 项目中的 res\icons\android 文件夹的内容更新 config.xml。

<icon gap:platform="android" gap:qualifier="ldpi"
    src="www/res/icons/android/icon-36-ldpi.png" />
<icon gap:platform="android" gap:qualifier="mdpi"
    src="www/res/icons/android/icon-48-mdpi.png" />
<icon gap:platform="android" gap:qualifier="hdpi"
    src="www/res/icons/android/icon-72-hdpi.png" />
<icon gap:platform="android" gap:qualifier="xhdpi"
    src="www/res/icons/android/icon-96-xhdpi.png" />

有关在 config.xml 中指定图标元素的详细信息，请阅读此文章。

初始屏幕

你可使 config.xml 中有零个或多个初始屏幕元素。和 <icon> 元素一样，初始屏幕元素也可以具有 src、gap:platform、宽度和高度属性。像图标文件一样，将初始屏幕文件保存为 PNG 图像。除非在 config.xml 中另外指定，否则每个平台都将在编译期间使用默认的 splash.png 文件。如果未提供 gap:platform 属性，则默认图像将复制到所有平台，增加每个应用程序包的大小。

默认初始屏幕必须命名为 splash.png，并且必须驻留在应用程序文件夹的根目录中。

<gap:splash src="splash.png" />

如果你想获取 Android 平台的特定初始屏幕，以下项显示了一个例子，关于如何基于 PhoneGap Build 项目中的 res\screens\android 文件夹的内容更新 config.xml。

<gap:splash gap:platform="android" gap:qualifier="port-ldpi" 
    src="www/res/screens/android/screen-ldpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-mdpi" 
    src="www/res/screens/android/screen-mdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-hdpi" 
    src="www/res/screens/android/screen-hdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="port-xhdpi" 
    src="www/res/screens/android/screen-xhdpi-portrait.png" />
<gap:splash gap:platform="android" gap:qualifier="land-ldpi" 
    src="www/res/screens/android/screen-ldpi-landscape.png" />
<gap:splash gap:platform="android" gap:qualifier="land-mdpi" 
    src="www/res/screens/android/screen-mdpi-landscape.png" />
<gap:splash gap:platform="android" gap:qualifier="land-hdpi" 
    src="www/res/screens/android/screen-hdpi-landscape.png" />
<gap:splash gap:platform="android" gap:qualifier="land-xhdpi" 
    src="www/res/screens/android/screen-xhdpi-landscape.png" />

有关在 config.xml 中指定初始屏幕元素的详细信息，请参阅此文章。

插件

为了扩展对 PhoneGap 本机应用程序容器所公开的本机平台功能的访问权限，PhoneGap Build 支持 PhoneGap 插件的白名单选定范围。有关受支持的插件列表，请参阅插件。如果你包含 Adobe 的白名单之外的任何插件，该生成将失败。若要将插件导入 PhoneGap Build 项目，需要将正确的 <gap:plugin> 元素添加到 config.xml 中。如果省略插件的版本属性，应用将始终使用最新版本的插件进行生成。

这是使用进行版本管理的插件的最简单方法。

<gap:plugin name="com.phonegap.plugins.example" version="2.2.1" />

因为 Visual Studio 将 <vs:plugin> 元素发送到已添加的每个插件的 config.xml 中，所以需要将这些元素将替换为 <gap:plugin> 元素。在我们使用的示例项目中，我们使用 config.xml 中的两个插件和两个相应的行。

<vs:plugin name="org.apache.cordova.device-motion" version="0.2.10" />
<vs:plugin name="org.apache.cordova.camera" version="0.3.2" />

在 PhoneGap Build 项目中，必须将这些行更改为：

<gap:plugin name="org.apache.cordova.device-motion" version="0.2.10" />
<gap:plugin name="org.apache.cordova.camera" version="0.3.2" />

有关修改插件的详细信息，请参阅此文章。

将你的项目上载到 PhoneGap

完成所需的所有修改后，就可以将你的应用程序上载到 PhoneGap 生成服务中。首先，为 PhoneGap 生成服务创建一个的帐户。然后，在 https://build.phonegap.com/apps 上登录到你的帐户，提交你的应用。你可以从 GIT 存储库提交你的应用程序，也可以上载一个本地 ZIP 文件。在此示例中，我们将上载一个包含 www 压缩文件夹的本地 ZIP 文件。上载 ZIP 后，你将看到你的应用已做好了进行生成的准备。

准备好进行生成时的 PhoneGap 项目