Capacitor2.3.0中文文档(二)--Basics

基础

开发工作流-Capacitor工作流

Capacitor工作流包括几个一致的任务：

 

1.开发和构建你的Web应用

Capacitor将您的web应用程序转换为每个平台的原生二进制文件。因此，您的大部分工作将包括开发并构建一个以移动端为中心的web应用程序。

您将使用Capacitor的插件（如Camera），或者使用与Capacitor兼容的现有的Cordova插件与底层的原生平台进行交互。

最后一步，您将使用类似以下命令构建应用程序：

npm run build

如果使用的是框架，请遵循框架的构建过程。例如，如果您使用的是Ionic，则可以是：

ionic build

 

2.拷贝你的Web资源文件夹

当你准备在原生设备或者模拟器运行你的项目的时候，请使用下面的命令拷贝你构建好的Web资源文件夹：

npx cap copy

 

3.打开你的原生开发工具

Capacitor使用原生开发者工具来构建、模拟和运行应用程序。要打开一个原生开发者工具，请运行：

npx cap open

 

4.升级原生项目

在某些情况下，Capacitor应用程序需要更新，例如在安装新插件时。

要安装新插件（包括Cordova插件），请运行：

npm install really-cool-plugin
npx cap update

 

5.升级Capacitor

要检查电容器本身是否有任何新的更新，请运行npx cap doctor打印出当前安装的依赖项，并查看最新可用的。

要更新Capacitor Core和CLI：

npm install @capacitor/cli@latest
npm install @capacitor/core@latest

要更新任何或者所有的平台你应该使用：

npm install @capacitor/ios@latest
npm install @capacitor/android@latest

注意：如果您不想冒险引入破坏性的更改，请使用npm update@capacitor/package-name而不是@latest，因为update遵循版本控制。

 

打开原生开发者工具-打开原生项目

Capacitor使用每个平台自己的原生开发工具来保证所需的配置，并构建、测试和部署应用程序。

对于iOS开发，这意味着您必须安装Xcode 11或更高版本。对于Android，您需要安装Android Studio 3或更高版本。

两个平台的开发工具都可以手动打开，也可以使用npx cap open命令打开：

 

打开Xcode

npx cap open ios

或者，也可以手动打开Xcode：

open ios/App/App.xcworkspace

 

打开Android Studio

npx cap open android

或者，您可以打开Android Studio并将android/目录作为Android Studio项目导入。

 

构建你的应用

Capacitor的构建过程总共分为3步：首先，构建你的web代码（如果有必要的话）。然后，构建好的web代码会被拷贝到各个平台。最后，使用各个平台特有的工具编译应用。

 

1.构建web代码

Capacitor没有任何内置功能来构建web代码。取而代之的是，您将使用您自己选择的框架构建。

无论您的构建过程如何，我们都建议将build脚本添加到package.json来启用标准前端构建命令：

{
  "scripts": {
    "build": "command-to-build (ex: webpack, tsc, babel, etc.)"
  }
}

npm run build

如果你已配置渐进式Web应用支持的话，上面的操作将生成渐进式Web应用程序。

 

2.复制web代码

一旦你的web代码完成了构建，它还需要被拷贝到各个原生平台：

npx cap copy

每次执行构建动作以后都要执行上面的这行命令，而且你还需要考虑将它添加到你的package.json这个文件里面的构建脚本的末尾。

 

3.构建原生项目

 

iOS

iOS依赖Xcode完成最终的应用程序编译：

npx cap copy ios
npx cap open ios

一旦Xcode启动，您就可以通过标准Xcode工作流构建应用程序二进制文件。

 

Android

Android依赖Android Studio（也可以选择Android CLI工具）来构建应用程序：

npx cap copy android
npx cap open android

一旦Android Studio启动，你就可以通过标准的Android Studio工作流来构建你的应用。

运行你的应用

Capacitor依赖各个平台自己的开发工具来运行和测试你的应用。

iOS

iOS需要使用Xcode运行你的应用

npx cap open ios

一旦Xcode启动，您就可以通过标准Xcode工作流构建/模拟/运行应用程序。

Android

npx cap open android

一旦Android Studio启动，您就可以通过标准Android Studio工作流来构建/模拟/运行您的应用程序。

渐进式web应用

Capacitor有一个用于本地测试的小型开发web服务器，但是建议使用您选择的框架的服务器工具来运行web应用程序。

npx cap serve

这行命令将在浏览器的本地web服务器实例中打开您的web应用程序。

 

使用插件

Capacitor附带许多内置插件，如摄像头和文件系统。 然而，你的应用程序很可能需要访问比Capacitor开箱即用的功能之外的其他更多的本地功能。 幸运的是，您可以通过编写少量的原生代码，然后按照插件指南将其公开为Capacitor插件，从而快速添加自己的原生功能。

 

查找插件

社区已经为各种原生功能构建了许多插件，您可以轻松地将它们添加到您的应用程序中。 查看我们的社区插件列表中的一些选项。

使用Cordova和Ionic原生插件

Capacitor还支持广泛的Cordova插件，因此有很多可供选择。

 

原生项目配置

Capacitor采用“一次编码，处处配置”的理念：配置是按平台管理的，而不是像Cordova那样的抽象的config.xml配置文件。

 

按平台管理

与Cordova相比，Capacitor要求您更多地参与本机项目配置。我们认为这是正确的方法，因为它可以很容易地遵循现有的原生iOS/Android指南，从Stack Overflow上面获取帮助，并完全控制您的项目。

此外，由于配置Capacitor项目与配置任何iOS或Android项目没有区别，现有的原生开发团队可以轻松地与web开发人员合作，双方都使用他们熟悉的工具和SDK。当然，我们相信web开发人员可以自己处理所有必需的原生配置，而Capacitor文档的存在正是为了帮助web开发人员做到这一点。

 

通用配置

Capacitor有一些在Capacitor配置文件中设置的高级配置选项。这些通常不会修改原生功能，但会控制Capacitor的工具。

 

原生配置

iOS和Android都有配置指南，对其行为进行常见更改：

（详情看后面的专门的文档。）

 

渐进式Web应用

Capacitor对渐进式web应用有一流的支持，这使得构建一个在iOS和Android上运行的应用程序变得非常容易，同时也可以作为移动Web应用程序或“渐进式Web应用程序”在Web上运行。

 

什么是渐进式web应用？

简单地说，渐进式Web应用程序（PWA）是一种使用现代Web功能向用户提供类似原生app体验的Web应用程序。这些应用被部署到传统的web服务器上，可以通过url访问，并且可以被搜索引擎索引。

对于所有实际目的而言，渐进式Web应用程序只是针对移动端性能进行了优化的网站的另一个术语，该网站利用新提供的Web api来提供与传统原生app类似的功能，例如推送通知和离线存储。

 

Capacitor和渐进式web应用

Capacitor对渐进式web应用和原生应用有一流的支持。这意味着Capacitor的插件桥支持在原生上下文或web中运行，在这两个上下文中都有许多核心插件，API和调用约定完全相同。

这意味着您使用@capacitor/core作为本地应用程序和渐进式Web应用程序的依赖项，并且Capacitor在需要时无缝地调用Web代码，在可用时无缝地调用原生代码。

此外，Capacitor还提供了许多实用程序，用于查询当前平台，以便在本机或web上运行时提供定制的体验。

 

给你的app添加渐进式web应用支持

将PWA支持添加到任何现有的前端项目都很容易。只需添加应用程序清单文件并配置一个service worker：

 

应用清单

首先，你需要添加一个应用程序清单文件(manifest.json)在你index.html文件的旁边，并提供有关应用程序的元数据，如名称、主题颜色和图标。例如，当应用程序安装在主屏幕上时会用到这些信息。

 

Service Worker

接下来，为了发送推送通知和离线存储数据，Service Worker将启用您的web应用程序代理网络请求，并执行处理和同步数据所需的后台任务。

Service Worker很强大，但很复杂。一般来说，不建议从头开始写。取而代之的是，看看像Workbox这样的工具，这些工具提供了通用Service Worker配置，可以很容易地添加到你的应用程序中。

在MDN上的Using Service Workers页面上阅读更多关于使用服务工作线程的信息，包括如何注册它们。

 

渐进式Web应用性能

渐进式Web应用程序是由几个性能标准来评判的，包括交互时间和第一次有意义的绘制。

在上线之前，请遵循渐进式Web应用检查表，并使用Lighthouse来审核和测试您的应用程序。

如果您正在努力通过现有的前端技术栈来满足渐进式Web应用程序性能标准，那么可以看看Ionic4或更高版本，以获得几乎零配置的快速PWA支持。Ionic 4.x或更高版本是一个web组件库，可以在几种流行的前端框架中工作，不仅仅是Angular。

 

原生或者web运行

Capacitor的一个关键特性是能够构建一个既在本地（在应用商店中）运行的应用程序，也可以在web上运行的应用程序。Capacitor通过在底层平台和您想要使用的api/插件之间提供一个层来实现这一点。

如果你的应用程序进行了没有web替代的本地插件调用，比如SplashScreen.show（），应用程序将允许这些调用而不会崩溃。返回promise的调用将返回被拒绝的promise，您应该在应用程序中处理该问题。

此外，Capacitor的JavaScript API有许多实用程序，可以通过编程方式检查某些API是否可用。

例如，如果您的应用程序通常依赖用于拍照的相机应用程序，则可以检查相机是否可用，如果不可用，则请求用户上传一个文件来代替拍照：

import { Capacitor } from '@capacitor/core';

const isAvailable = Capacitor.isPluginAvailable('Camera');

if (!isAvailable) {
  // Have the user upload a file instead
} else {
  // Otherwise, make the call:
  Camera.getPhoto()
}

 

JavaScript实用程序

Capacitor有几个JavaScript实用程序，可以确保使用同一套代码的应用程序在多个平台上成功运行。要使用它们，请导入Capacitor，然后调用所需的实用函数：

import { Capacitor } from '@capacitor/core';
const isAvailable = Capacitor.isPluginAvailable('Camera');

 

转换文件源

convertFileSrc: (filePath: string) => string;

把一个实体设备能够识别的文件路径转换为一个对web应用友好的路径。

Capacitor应用程序使用不同于设备文件的协议。为了避免这些协议之间的识别困难，必须重写设备文件的路径。例如，在安卓平台上，在Web视图中使用之前，file:///path/to/device/file必须被重写为http://localhost/_capacitor_file_/path/to/device/file

// file:///path/to/device/photo.jpg
const savedPhotoFile = await Filesystem.writeFile({
  path: "myFile.jpg",
  data: base64Data,
  directory: FilesystemDirectory.Data
});

// http://localhost/path/to/device/photo.jpg
const savedPhoto = Capacitor.convertFileSrc(savedPhotoFile.uri),
document.getElementById("savedPhoto").src = savedPhoto;

 

getPlatform

getPlatform: () => string;

获取应用当前运行平台的名称：web,ios,android.

if (Capacitor.getPlatform() === 'ios') {
  // do something
}

 

isNative

isNative?: boolean;

检查应用当前运行的平台是否是原生平台(ios,android)。

if (Capacitor.isNative) {
  // do something
}

 

isPluginAvailable

isPluginAvailable: (name: string) => boolean;

检查在当前运行的平台上某个插件是否可用。插件的名称是在插件注册时使用的名称(例如：const {Name} = Plugins),这就意味着，自定义插件也可以同样使用这个方法来检测。

const isAvailable = Capacitor.isPluginAvailable('Camera');

if (!isAvailable) {
  // Have the user upload a file instead
} else {
  // Otherwise, make the call:
  const image = await Camera.getPhoto({
    resultType: CameraResultType.Uri
  });
}