升级 Android
本指南介绍如何修改 Android 项目以从旧版本的 Cordova 升级。大多数这些说明适用于使用旧版命令行工具(早于 cordova
CLI 实用程序)创建的项目。有关如何更新 CLI 版本的信息,请参阅 命令行界面。
升级到 10.x.x
升级到 10.X.X 的最佳方法是简单地从项目中删除 Android 平台,并使用新版本重新添加它。例如,
cordova platform remove android
cordova platform add [email protected]
如果您使用上述方法,请注意您对 android 平台文件夹所做的任何更改都将丢失(不建议编辑此文件夹的内容)。
重大更改
版本 10.0.0 引入了一个重大更改,即应用程序中 URL 的加载方式。以前版本通过文件协议加载应用程序的 Web 文件(如 index.html
)。这意味着应用程序从 URL file:///android_asset/www/index.html
开始。加载 file:///
URL 被认为是不安全的,并且 Android 已弃用支持。Cordova Android 10.0.0 现在使用名为 WebViewAssetLoader
的 Android API 通过 HTTP(S) 方案 (https://localhost
) 加载 Web 内容(默认情况下)。因此,应用程序现在从 URL https://localhost/
开始,而不是 file:///android_asset/www/index.html
。由于这是一个新的来源,您可能会遇到数据丢失,并且需要迁移您的 Web 数据(LocalStorage、IndexedDB 等)。
您可以使用 config.xml
首选项 <preference name="AndroidInsecureFileModeEnabled" value="true" />
选择退出新的 WebViewAssetLoader 并切换回文件 URL。
升级到 7.X.X
升级到 7.X.X 的最佳方法是简单地从项目中删除 Android 平台,并使用新版本重新添加它。例如,
cordova platform remove android
cordova platform add [email protected]
如果您使用上述方法,请注意您对 android 平台文件夹所做的任何更改都将丢失(不建议编辑此文件夹的内容)。
不幸的是,由于文件结构的更新,非 CLI 项目将不得不手动更新,或者必须创建一个新的 Cordova 项目,并将文件传输到新项目。这是由于迁移到 Android Studio 造成的。
升级到 6.X.X
升级到 6.X.X 的最佳方法是简单地从项目中删除 Android 平台,并使用新版本重新添加它。例如,
cordova platform remove android
cordova platform add [email protected]
如果您使用上述方法,请注意您对 android 平台文件夹所做的任何更改都将丢失(不建议编辑此文件夹的内容)。
或者,您可以尝试使用平台更新脚本。对于非 CLI 项目,请运行
bin/update path/to/project
升级到 5.X.X
升级到 5.X.X 的最佳方法是简单地从项目中删除 Android 平台,并使用新版本重新添加它。例如,
cordova platform remove android
cordova platform add [email protected]
如果您使用上述方法,请注意您对 android 平台文件夹所做的任何更改都将丢失(不建议编辑此文件夹的内容)。
或者,您可以尝试使用平台更新脚本。对于非 CLI 项目,请运行
bin/update path/to/project
对于 CLI 项目
-
更新
cordova
CLI 版本。请参阅 命令行界面。 -
在现有项目中运行
cordova platform update [email protected]
。
升级 Android Marshmallow 的插件
版本 5.0.0 添加了对 Android API 级别 23(Marshmallow)的支持。Android Marshmallow 引入了一种新的权限模型,您可能需要更新一些已安装的插件以确保它们与更新的手机兼容。旧版本的插件如果不能正确处理权限,会导致您的应用程序意外崩溃。请注意,这不会影响所有插件,而只会影响那些访问被认为是危险的 Android 权限的插件(请参阅 危险权限表)。
以下核心插件受此更改的影响,必须升级才能与 cordova-android 5.0.0+ 一起使用
插件 | 最低兼容版本 |
---|---|
cordova-plugin-camera | 2.0.0 |
cordova-plugin-contacts | 2.0.0 |
cordova-plugin-file | 4.0.0 |
cordova-plugin-geolocation | 2.0.0 |
cordova-plugin-media | 2.0.0 |
对于非核心插件,您可以通过检查插件的 plugin.xml
文件来验证插件是否请求 危险权限。如果插件使用 Android 权限,您将在 plugin.xml
中看到声明它们的条目。例如
<uses-permission android:name="android.permission.PERMISSION_NAME" />
其中 PERMISSION_NAME
被替换为 Android 权限的名称。plugin.xml
文件可以在 Cordova 项目的插件文件夹中找到(例如 plugins/example-plugin/plugin.xml
)。请咨询使用危险权限的任何插件的文档,以确定需要采取哪些步骤来确保 cordova-android 5.0.0+ 兼容性。
升级到 4.0.0
要利用 4.0.0 中的重大更改,需要执行特定的升级步骤。首先,需要执行以下常见的升级步骤。
对于非 CLI 项目,请运行
bin/update path/to/project
对于 CLI 项目
-
更新
cordova
CLI 版本。请参阅 命令行界面。 -
在现有项目中运行
cordova platform update [email protected]
。
升级白名单
所有白名单功能现在通过插件实现。如果没有插件,升级到 4.0.0 后,您的应用程序将不再受白名单保护。Cordova 有两个白名单插件,它们提供不同级别的保护。
cordova-plugin-whitelist
插件(推荐)- 强烈推荐使用此插件,因为它比以前版本的白名单更安全,并且可配置性更高
- 有关所需配置更改的详细信息,请参阅 cordova-plugin-whitelist
- 运行:
cordova plugin add cordova-plugin-crosswalk-webview
cordova-plugin-legacy-whitelist
插件- 此插件提供与以前版本相同的白名单行为。请参阅 cordova-plugin-legacy-whitelist
- 不需要进行任何配置更改,但它提供的保护不如推荐的插件
- 运行:
cordova plugin add cordova-plugin-legacy-whitelist
使用 Crosswalk WebView
默认情况下,您的应用程序将继续使用设备提供的系统 WebView。如果您希望使用 Crosswalk WebView,只需添加 Crosswalk 插件
cordova plugin add cordova-plugin-crosswalk-webview
添加插件后,您的应用程序将获得正确安装和配置的 Crosswalk WebView。
升级到启动画面插件
如果您的应用程序使用启动画面,该功能已移至插件。启动画面的配置选项保持不变。唯一需要的升级步骤是添加插件
cordova plugin add cordova-plugin-splashscreen
从 3.6.0 升级到 3.7.1
对于非 CLI 项目,请运行
bin/update path/to/project
对于 CLI 项目
-
更新
cordova
CLI 版本。请参阅 命令行界面。 -
在现有项目中运行
cordova platform update android
。
从 3.2.0 升级到 3.3.0
按照 3.2.0
的相同说明操作。
从 3.3.0 开始,Cordova 运行时现在被编译为 Android 库,而不是 Jar。这对于命令行使用应该没有影响,但 IDE 用户需要将新添加的 MyProject-CordovaLib
项目导入其工作区。
从 3.1.0 升级到 3.2.0
对于使用 cordova CLI 创建的项目
-
更新
cordova
CLI 版本。请参阅 命令行界面。 -
运行
cordova platform update android
对于未使用 cordova CLI 创建的项目,请运行
bin/update <project_path>
警告:在 Android 4.4 - Android 4.4.3 上,创建类型为“file”的文件输入元素将不会打开文件选择器对话框。这是 Android 上 Chromium 的一个回归,并且可以在 Android 上的独立 Chrome 浏览器中重现此问题(请参阅 https://code.google.com/p/android/issues/detail?id=62220)建议的解决方法是使用 Android 4.4 的 FileTransfer 和 File 插件。您可以监听来自输入类型“file”的 onClick 事件,然后弹出文件选择器 UI。为了将表单数据与上传绑定,您可以使用 JavaScript 将表单值附加到 FileTransfer 执行的多部分 POST 请求。
从 3.0.0 升级到 3.1.0
对于使用 cordova CLI 创建的项目
-
更新
cordova
CLI 版本。请参阅 命令行界面。 -
运行
cordova platform update android
对于未使用 cordova CLI 创建的项目,请运行
bin/update <project_path>
从 2.9.0 升级到 CLI(3.0.0)
-
使用 cordova CLI 创建一个新的 Apache Cordova 3.0.0 项目,如 命令行界面 中所述。
-
将您的平台添加到 cordova 项目,例如:
cordova platform add android
。 -
将项目
www
目录的内容复制到您刚刚创建的 cordova 项目根目录下的www
目录。 -
将任何原生资产从旧项目复制到
platforms/android
下的相应目录:此目录是您的原生 cordova-android 项目所在的位置。 -
使用 cordova CLI 工具安装您需要的任何插件。请注意,CLI 将所有核心 API 作为插件处理,因此可能需要添加它们。只有 3.0.0 插件与 CLI 兼容。
从 2.9.0 升级到 3.0.0
-
创建一个新的 Apache Cordova Android 项目。
-
将
www
目录的内容复制到新项目。 -
将任何原生 Android 资产从
res
目录复制到新项目。 -
将您从
src
子目录中安装的任何插件复制到新项目。 -
确保将旧
config.xml
文件中的任何已弃用的<plugin>
引用升级到新的<feature>
规范。 -
更新对
org.apache.cordova.api
包的任何引用,使其成为org.apache.cordova
。注意:所有核心 API 都已删除,必须作为插件安装。有关详细信息,请参阅 使用 Plugman 管理插件 指南。
从 2.8.0 升级到 2.9.0
- 运行
bin/update <project_path>
。
从 2.7.0 升级到 2.8.0
-
从项目的
libs
目录中删除cordova-2.7.0.jar
。 -
将
cordova-2.8.0.jar
添加到项目的libs
目录。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova.js
复制到您的项目。 -
更新您的 HTML 以使用新的
cordova.js
文件。 -
复制
res/xml/config.xml
文件以匹配framework/res/xml/config.xml
。 -
更新
framework/res/xml/config.xml
以使其具有与以前类似的设置。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 2.6.0 升级到 2.7.0
-
从项目的
libs
目录中删除cordova-2.6.0.jar
。 -
将
cordova-2.7.0.jar
添加到项目的libs
目录。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.7.0.js
复制到您的项目。 -
更新您的 HTML 以使用新的
cordova-2.7.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
更新
framework/res/xml/config.xml
以使其具有与以前类似的设置。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 2.5.0 升级到 2.6.0
-
从项目的
libs
目录中删除cordova-2.5.0.jar
。 -
将
cordova-2.6.0.jar
添加到项目的libs
目录。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.6.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.6.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
更新
framework/res/xml/config.xml
以使其具有与以前类似的设置。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
在 Cordova 源代码目录中列出项目路径,运行 bin/update <project>
命令。
从 2.4.0 升级到 2.5.0
-
从项目
libs
目录中删除cordova-2.4.0.jar
文件。 -
将
cordova-2.5.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.5.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.5.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
更新
framework/res/xml/config.xml
以使其具有与以前类似的设置。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 2.3.0 升级到 2.4.0
-
从项目
libs
目录中删除cordova-2.3.0.jar
文件。 -
将
cordova-2.4.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.4.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.4.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 2.2.0 升级到 2.3.0
-
从项目
libs
目录中删除cordova-2.2.0.jar
文件。 -
将
cordova-2.3.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.3.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.3.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 2.1.0 升级到 2.2.0
-
从项目
libs
目录中删除cordova-2.1.0.jar
文件。 -
将
cordova-2.2.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.2.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.2.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 2.0.0 升级到 2.1.0
-
从项目
libs
目录中删除cordova-2.0.0.jar
文件。 -
将
cordova-2.1.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.1.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.1.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。 -
将文件从
bin/templates/cordova
复制到项目的cordova
目录。
从 1.9.0 升级到 2.0.0
-
从项目
libs
目录中删除cordova-1.9.0.jar
文件。 -
将
cordova-2.0.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-2.0.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-2.0.0.js
文件。 -
复制
res/xml/config.xml
以匹配framework/res/xml/config.xml
。
在 2.0.0 版本中,config.xml
文件合并并替换了 cordova.xml
和 plugins.xml
文件。旧文件已弃用,虽然它们在 2.0.0 中仍然有效,但将在未来版本中停止工作。
从 1.8.1 升级到 1.9.0
-
从项目
libs
目录中删除cordova-1.8.0.jar
文件。 -
将
cordova-1.9.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.9.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-1.9.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
由于 1.9.0 版本中引入了 CordovaWebView
,第三方插件可能无法正常工作。这些插件需要使用 getContext()
或 getActivity()
从 CordovaInterface
获取上下文。如果您不是经验丰富的 Android 开发人员,请联系插件维护者并将此任务添加到他们的错误跟踪器中。
从 1.8.0 升级到 1.8.1
-
从项目
libs
目录中删除cordova-1.8.0.jar
文件。 -
将
cordova-1.8.1.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.8.1.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-1.8.1.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
从 1.7.0 升级到 1.8.0
-
从项目
libs
目录中删除cordova-1.7.0.jar
文件。 -
将
cordova-1.8.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.8.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-1.8.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
从 1.7.0 升级到 1.8.0
-
从项目
libs
目录中删除cordova-1.7.0.jar
文件。 -
将
cordova-1.8.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.8.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-1.8.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
从 1.6.1 升级到 1.7.0
-
从项目
libs
目录中删除cordova-1.6.1.jar
文件。 -
将
cordova-1.7.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.7.0.js
文件复制到您的项目中。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
从 1.6.0 升级到 1.6.1
-
从项目
libs
目录中删除cordova-1.6.0.jar
文件。 -
将
cordova-1.6.1.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.6.1.js
文件复制到您的项目中。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
从 1.5.0 升级到 1.6.0
-
从项目
libs
目录中删除cordova-1.5.0.jar
文件。 -
将
cordova-1.6.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.6.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-1.6.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。 -
用
res/xml/cordova.xml
文件替换res/xml/phonegap.xml
文件,以匹配framework/res/xml/cordova.xml
文件。
从 1.4.0 升级到 1.5.0
-
从项目
libs
目录中删除phonegap-1.4.0.jar
文件。 -
将
cordova-1.5.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
cordova-1.5.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
cordova-1.5.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。 -
用
res/xml/cordova.xml
文件替换res/xml/phonegap.xml
文件,以匹配framework/res/xml/cordova.xml
文件。
从 1.3.0 升级到 1.4.0
-
从项目
libs
目录中删除phonegap-1.3.0.jar
文件。 -
将
phonegap-1.4.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
phonegap-1.4.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
phonegap-1.4.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。 -
更新
res/xml/phonegap.xml
文件以匹配framework/res/xml/phonegap.xml
文件。
从 1.2.0 升级到 1.3.0
-
从项目
libs
目录中删除phonegap-1.2.0.jar
文件。 -
将
phonegap-1.3.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
phonegap-1.3.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
phonegap-1.2.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。 -
更新
res/xml/phonegap.xml
文件以匹配framework/res/xml/phonegap.xml
文件。
从 1.1.0 升级到 1.2.0
-
从项目
libs
目录中删除phonegap-1.1.0.jar
文件。 -
将
phonegap-1.2.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
phonegap-1.2.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
phonegap-1.2.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。 -
更新
res/xml/phonegap.xml
文件以匹配framework/res/xml/phonegap.xml
文件。
从 1.0.0 升级到 1.1.0
-
从项目
libs
目录中删除phonegap-1.0.0.jar
文件。 -
将
phonegap-1.1.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
phonegap-1.1.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
phonegap-1.1.0.js
文件。 -
更新
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。
从 0.9.6 升级到 1.0.0
-
从项目
libs
目录中删除phonegap-0.9.6.jar
文件。 -
将
phonegap-1.0.0.jar
文件添加到项目libs
目录中。 -
如果您使用 Eclipse,请刷新您的 Eclipse 项目并进行清理。
-
将新的
phonegap-1.0.0.js
文件复制到您的项目中。 -
更新您的 HTML 代码以使用新的
phonegap-1.0.0.js
文件。 -
添加
res/xml/plugins.xml
文件以匹配framework/res/xml/plugins.xml
文件。