Capacitor2.3.0中文文档(三)--Cordova/PhoneGap

Cordova and PhoneGap

Apache Cordova（和Adobe PhoneGap）创建于2008年，是一个开源项目，它使web开发人员能够使用他们的HTML、CSS和JavaScript内容为各种移动和桌面平台创建一个原生应用程序。

有关Cordova历史的更多详细信息以及它是如何工作的，请参阅此处。

为什么要创建新项目？

开源空间充满了新的项目，这些项目是在旧项目的基础上构建的，这些项目做出了切实的改进，如果不从根本上改变原始产品，这些改进是无法实现的。这正是Capacitor所需要的。Ionic团队认为，由于技术和政治原因，Cordova不可能做到这一点。不管这是对是错，这是团队得出的结论。也就是说，Ionic仍然大量使用Cordova，并将在未来很长一段时间内继续对该平台进行投资。

好的一面是，Ionic现在几乎控制了它的所有的技术栈。当你构建一个Ionic应用程序并使用Capacitor时，我们控制原生运行时层、UI控件和用于构建控件（模具）的“框架”。我们唯一不能控制的部分是你在上面使用的前端框架（Angular、React、Vue或什么都没有）。这很重要：如果我们控制的技术栈的任何部分出现问题，我们可以立即修复它。Capacitor已经被证明是一项值得的投资-它使我们能够建立一个更强大的Ionic，并专注于我们独特擅长的事情。

Capacitor和Cordova之间的区别

在精神上，Capacitor和Cordova非常相似。两者都管理一个WebView，并提供一种结构化的方式来向Web代码公开原生功能。然而，Capacitor有几个关键的区别，这需要web开发人员（以前习惯于Cordova的方法）来改变应用程序开发工作流程。

原生项目管理

Capacitor将每个平台项目视为source asset，而不是build time asset。这意味着您将把Xcode和Android Studio项目纳入源代码控制中，并在需要时使用这些ide进行特定于平台的配置和运行/测试。

这种方法的改变有一些影响。首先，Capacitor不使用config.xml或类似的自定义配置来对平台进行设置。取而代之的是，配置更改是通过直接编辑适当的特定于平台的配置文件来实现的，例如Android的AndroidManifest.xml文件和Xcode的Info.plist文件。Capacitor在capacitor.config.json中有一些高级配置选项。这些通常不会修改原生功能，但会控制Capacitor的工具。

此外，Capacitor不是“在设备上运行”或通过命令行进行模拟。相反，这些操作是通过特定于平台的开发工具实现的，它提供了一种遵循该平台应用程序开发标准的更快速、更典型的体验。例如，苹果并不支持从命令行运行iOS应用程序，所以Xcode是首选。

虽然这些变化可能与长期使用Cordova的用户有关，但有一些值得注意的好处：

通过抽象的工具如config.xml来更新或者修改原生项目很容易出错。使用特定于平台的开发工具变得更加自如，这使得故障排除变得更加容易。添加应用程序所需的自定义原生代码更容易，而无需为其构建新的插件。此外，原生团队可以在同一个项目中与web团队一起工作。创建更具吸引力的应用程序体验现在更容易了，因为您“拥有”了原生项目，例如在web应用程序上添加一个原生UI外壳。随着新的移动操作系统版本的发布，对原生项目更改的可见性和应用程序的可维护性更好。当引入对Capacitor的重大更改或将更改应用于原生项目模板时，团队将发布逐步升级的说明，以确保更新过程尽可能顺利。

插件管理

Capacitor管理插件的方式与Cordova不同。首先，Capacitor不会在构建之前将插件源代码复制到应用程序中。相反，所有插件都是作为框架（iOS）和库（Android）构建的，并使用针对每个平台的领先依赖关系管理工具（分别是CocoaPods和Gradle/Maven）进行安装。此外，Capacitor不会修改原生源代码，因此必须手动添加任何必需的原生项目设置（例如，AndroidManifest.xml中的权限). 我们认为这种方法不容易出错，并且使开发人员更容易在社区中为每个特定平台找到帮助。

一个主要的区别是插件处理它们需要从WebView执行的JavaScript代码的方式。Cordova要求插件提供自己的JavaScript并手动调用exec()。相反，Capacitor根据运行时检测到的方法注册并导出每个插件的所有JavaScript，因此只要WebView加载，所有插件方法都可用。这一点的一个重要含义是：再也不需要deviceready事件。一旦你的应用程序代码加载，你就可以开始调用插件方法了。

虽然Capacitor不需要插件来提供JavaScript，但是很多插件都希望JavaScript中有逻辑。在这种情况下，提供一个带有额外JavaScript的插件就像提供一个传统的JavaScript库（bundle、module等）一样简单，通过Capacitor.Plugins.MyPlugin代替了Cordova中调用插件的exec()方法。

最后，Capacitor对插件作者有启示。在iOS上，swift4得到官方支持，甚至更倾向于构建插件（Objective-C也受支持）。插件不再导出Plugin.xml文件；Capacitor在iOS上提供了一些简单的宏和Android上的注释，用于将元数据添加到插件源代码中，Capacitor在运行时读取这些源代码。

CLI/版本管理

与Cordova不同，Capacitor不使用全局CLI。相反，Capacitor“CLI”作为npm脚本在本地安装到每个项目中。这使得管理多个不同应用程序的Capacitor版本变得更容易。因此，不是直接从命令行运行Capacitor，而是通过调用应用程序目录中的npx cap来调用Capacitor。

迁移策略

从Cordova迁移到Capacitor可能会随着时间的推移而慢慢发生，或者在许多情况下可以完全替换。所需要的努力很大程度上取决于应用程序的复杂性。

为什么要迁移？

长治久安。 Capacitor的后盾是Ionic，它是Cordova和更大的开源生态系统的长期贡献者。Ionic仍然大量使用Cordova，并将在未来很长一段时间内继续对该平台进行投资。它与Cordova向后兼容，所以只要准备好，就可以轻松地将现有的web应用切换到它。Capacitor从一开始就是为了支持丰富的开箱即用的Cordova插件生态系统而设计的。因此，在Capacitor中使用Cordova插件很容易。

Ionic为什么要和Capacitor搭配使用？

将Ionic和Capacitor一起使用是构建最佳应用程序体验的方法，因为Ionic框架提供了Capacitor没有的UI和UX增强功能。此外，它还可以与您最喜欢的web应用程序框架一起工作，包括Angular、React和Vue。

随着Capacitor的发布，Ionic现在几乎控制了它的所有技术栈。当你现在构建一个Ionic应用程序时，我们现在控制原生运行时层（Capacitor）、UI控件（Ionic框架）和用于构建控件的“框架”（由模板驱动的web组件）。这很重要：如果我们控制的技术栈的任何部分出现问题，我们可以立即修复它。我们唯一不能控制的部分是您在上面使用的前端框架（Angular、React、Vue或纯JavaScript）。

你用的是新的Ionic吗，比如Ionic React或Ionic Vue？Capacitor是官方支持的原生运行时。

已经在用Ionic了吗？考虑升级到Ionic4

电容器适用于任何Ionic项目（1.0至4.x+），但为了享受最好的应用程序开发体验，建议使用Ionic4及以上版本。如果你有一个Ionic1到Ionic3的App，你可以参考下面的Ionic4迁移指南。如果您需要进一步的帮助，Ionic 能够帮助你。我们提供咨询服务，包括Ionic4培训、架构审查和迁移帮助。

迁移过程概述

审计然后迁移现有的Cordova插件

从审计你现有的Cordova插件开始-你可能可以删除那些不再需要的插件。

接下来，回顾一下Capacitor的所有核心插件以及社区插件。你可以切换到与Cordova等效的Capacitor插件。

有些插件可能无法完全匹配功能，但基于您需要的功能，这可能并不重要。

如果有必要的话，继续使用Cordova或者Ionic 原生插件

要在Capacitor应用程序中使用用Cordova和/或Ionic原生插件，请参阅此处。如果替换插件不存在，继续按原样使用Cordova插件。如果你想要某个插件被支持，请告诉我们。

将使用Cordova的Web应用程序迁移到Capacitor

将使用Cordova的web应用程序完全迁移到Capacitor上需要几个步骤。

请注意，在应用这些更改时，建议在单独的代码分支中进行。

添加Capacitor

请在终端打开你的项目，然后把Capacitor添加到一个web应用或者ionic应用。

下一步，打开config.xml并在widget元素中找到id字段。在这个例子中，它是io.ionic.myapp.

<widget id="io.ionic.myapp" version="0.0.1" 
xmlns="http://www.w3.org/ns/widgets" 		                         xmlns:cdv="http://cordova.apache.org/ns/1.0">

找到你的应用的name属性

<name>MyApp</name>

现在，用这个应用程序信息初始化Capacitor：

npx cap init [appName] [appId]

在这个例子中，上面的命令应该是npx cap init MyApp io.ionic.myapp这些值可以在新创建的capacitor.config.json文件里面找到。

构建你的web应用

在添加任何原生平台之前，必须至少构建一次你的web项目。

因为这个构建动作会生成一个www文件夹，这将确保www是存在的，因为在capacitor.config.json文件当中，Capacitor已经自动配置www文件夹作为自己的webDir这个属性的值。

添加平台

Capacitor原生平台存在于它们自己的顶层文件夹中。Cordova位于platforms/ios或platforms/android下。

npx cap add ios
npx cap add android

以上的命令会在项目的根目录下创建android和ios文件夹。这些是完全独立的原生项目构件，应该被视为应用程序的一部分（例如，将它们纳入源代码管理，在它们自己的开发工具中编辑它们，等等）。另外，以前通过npm install添加到项目中的任何Cordova插件（位于dependencies目录下的package.json文件中)会被Capacitor自动安装到每个新的原生项目中（不包括任何不兼容项目）：

"dependencies": {
    "@ionic-native/camera": "^5.3.0",
    "@ionic-native/core": "^5.3.0",
    "@ionic-native/file": "^5.3.0",
    "cordova-android": "8.0.0",
    "cordova-ios": "5.0.0",
    "cordova-plugin-camera": "4.0.3",
    "cordova-plugin-file": "6.0.1",
}

启动屏幕和图标

如果您以前创建过图标和启动屏幕图像，则可以在项目的顶层resources文件夹中找到它们。有了这些图片，你就可以使用cordova res工具为基于Capacitor的iOS和Android项目生成图标和启动屏幕。

首先，安装cordova-res:

$ npm install -g cordova-res

接下来，运行以下命令来重新生成映像并将其复制到原生项目中：

$ cordova-res ios --skip-config --copy
$ cordova-res android --skip-config --copy

详见这里。

迁移插件

从检查你现有的Cordova插件开始-你也许可以先删除那些不再需要的插件。

接下来，查看一下Capacitor的所有核心插件以及社区插件。你可以切换到与Cordova插件等效的Capacitor插件。

有些插件可能无法完全匹配功能，但基于您需要的功能，这可能并不重要。

请注意，任何不兼容或导致生成问题的插件都会自动跳过。

移除Cordova插件

将Cordova插件替换为Capacitor插件（或干脆将其完全删除）后，卸载该插件，然后运行sync命令从原生项目中删除这些插件代码：

npm uninstall cordova-plugin-name
npx cap sync [android | ios]

设置权限

默认情况下，在iOS和Android的默认原生项目中为您设置了最新版本Capacitor所请求的全部初始权限。但是，您可能需要通过对应plugin.xml里面的设置来修改iOS和Android上的必需设置。有关如何配置每个平台的信息，请参阅iOS和Android配置指南。

Cordova插件首选项

当npx cap init运行时，Capacitor读取config.xml中的所有首选项然后把它们复制到capacitor.config.json文件中。您可以手动向cordova.preferences添加更多首选项。

{
  "cordova": {
    "preferences": {
      "DisableDeploy": "true",
      "CameraUsesGeolocation": "true"
    }
  }
}

附加config.xml领域

你可能很好奇config.xml`中的元素在Capacitor应用程序中是怎样工作的。

Author元素可以在package.json中配置，但Capacitor或应用程序中不使用：

<author email="email@test.com" href="http://ionicframework.com/">Ionic Framework Team</author>

大部分allow-intent值都不会被用到，或者在capacitor.config.json中有可替代的。

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
<allow-intent href="mailto:*" />
<allow-intent href="geo:*" />

iOS的edit-config元素需要在Info.plist中进行配置。

<edit-config file="*-Info.plist" mode="merge" target="NSCameraUsageDescription">
    <string>Used to take photos</string>
</edit-config>

不可能覆盖所有config.xml可用元素。然而，当我们在网上搜索大多数问题比如“如何配置Capacitor中的X？”的答案时，我们应该去搜索“如何在[平台]（iOS/Android）中配置X？”。

设置方案

在Ionic与Cordova一起使用时，您的应用程序默认使用cordova-plugin-ionic-webview，在iOS上，它使用Ionic://方案来提供内容。Capacitor应用程序使用capacitor://作为iOS的默认方案。这意味着使用源代码绑定的Web API（如LocalStorage）将导致数据丢失，因为源代码不同。可以通过更改用于提供内容的方案来解决此问题：

{
  "server": {
    "iosScheme": "ionic"
  }
}

移除Cordova

一旦您测试了所有迁移更改都已正常应用并且应用程序运行良好，就可以从项目中删除Cordova了。删除config.xml以及platform和plugins文件夹。请注意，技术上不必移除Cordova，因为Capacitor与它一起工作。事实上，如果您打算继续使用Cordova插件，或者认为将来可能会继续使用，那么您可以将Cordova资源文件留在原来的位置。

下一步

这只是你的Capacitor之旅的开始。了解有关在Capacitor项目中使用Cordova插件的更多信息，或了解有关Capacitor开发工作流的更多详细信息。

使用Cordova插件和Ionic原生插件

当我们开发一个使用Capacitor的应用时，我们很可能同时用到Cordova和Ionic Native插件。

下载Cordova插件

只需安装您选择的插件，同步您的项目，完成任何必需的原生项目配置，您就可以开始：

npm install cordova-plugin-name
npx cap sync

升级Cordova插件

与安装步骤类似。只需将cordova插件更新到最新版本，Capacitor将接受更改：

npm install cordova-plugin-name@latest
npx cap update

如果你不想冒险引入突破性的变化，使用npm update cordova-plugin-name来替代update时总是遵循的@latest。

安装Ionic Native插件

Ionic Native为Cordova插件提供了TypeScript包装器和一致的API和命名约定，以便于开发。Capacitor支持它，所以每当你找到你想要使用的Ionic Native包装器时，安装JavaScript代码，安装相应的Cordova插件，然后同步你的项目：

npm install @ionic-native/javascript-package-name
npm install cordova-plugin-name
npx cap sync

升级Ionic Native插件

类似于安装步骤。更新Ionic Native JavaScript库，删除并重新添加Cordova插件，然后更新您的项目：

npm install @ionic-native/javascript-package-name@latest
npm install cordova-plugin-name@latest
npx cap update

如果你不想冒险引入突破性的变化，使用npm update cordova-plugin-name来替代@latest。

确定已安装的插件版本

查看项目中安装的Capacitor和Cordova插件列表（及其确切版本号）：

npx cap ls

重要：配置

Capacitor不支持Cordova安装变量、自动配置或钩子，因为我们的理念是让您控制原生项目源代码（这意味着像钩子这样的东西是不必要的）。如果您的插件需要设置变量或一些设置，那么您需要通过手动参考插件的plugin.xml里面的配置来对应设置iOS和Android上的必需设置。

有关如何配置每个平台的信息，请参阅iOS和Android配置指南。

兼容性问题

有些Cordova插件不能与Capacitor一起工作，或者Capacitor提供了一个相互冲突的替代方案。有关详细信息和已知的不兼容列表，请参阅下面。

已知的不兼容的Cordova插件

虽然我们已经测试了许多流行的Cordova插件，但可能Capacitor并不支持每个Cordova插件。有些插件Capacitor不兼容或Capacitor提供了一个相互冲突的替代方案。如果已知插件冲突或导致生成问题，则在运行npx cap update时将跳过该插件。如果您发现现有Cordova插件存在问题，请通过提供问题的详细信息和插件信息让我们知道。

已知的不兼容插件（可能会更改）

cordova-plugin-add-swift-support (not needed, Capacitor has built in Swift support)
cordova-plugin-admobpro (see details)
cordova-plugin-braintree (see details)
cordova-plugin-compat (not needed)
cordova-plugin-console (not needed, Capacitor has its own)
cordova-plugin-crosswalk-webview (Capacitor doesn't allow to change the webview)
cordova-plugin-fcm (see details)
cordova-plugin-firebase (see details)
cordova-plugin-ionic-keyboard (not needed, Capacitor has it's own)
cordova-plugin-ionic-webview (not needed, Capacitor uses WKWebView)
cordova-plugin-music-controls (causes build failures, skipped)
cordova-plugin-qrscanner (see details)
cordova-plugin-splashscreen (not needed, Capacitor has its own)
cordova-plugin-statusbar (not needed, Capacitor has its own)
cordova-plugin-wkwebview-engine (not needed, Capacitor uses WKWebView)
cordova-plugin-googlemaps (causes build failures on iOS, skipped for iOS only)

本作品采用知识共享署名 4.0 国际许可协议进行许可