Capacitor2.3.0中文文档(十一)--Plugins目录下的插件列表

Capacitor插件接口

Capacitor包括许多可用于所有Capacitor应用程序的原生插件API。这些可以被认为是Capacitor的“核心插件”，它们使访问每个平台上常用的功能变得容易。

对于以前是用Cordova的用户，核心的Capacitor插件涵盖了Cordova的大部分核心插件，并且还包含一些新插件。

有关可用插件的完整列表，请参见左侧菜单上的“插件”列表。

 

API用法

要使用Capacitor插件，请按照以下步骤操作：

1）导入Plugins对象。它代表所有Capacitor插件的注册表。

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

 

2）从插件注册表（Plugins对象）获取插件。

const { Browser } = Plugins;

 

3）使用插件API：

async openBrowser() {
  // On iOS, for example, open the URL in SFSafariViewController (the in-app browser)
  await Browser.open({ url: "https://ionicframework.com" });
}

 

一个常见的错误是直接导入插件，然后立即使用插件API，从而导致使用的是Web实现：

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

async openBrowser() {
  // On iOS, for example, this will open the URL in Safari instead of
  // the SFSafariViewController (in-app browser)
  await Browser.open({ url: "https://ionicframework.com" });
}

通过使用插件注册表（Plugins对象）中的插件，可以使用插件的原生实现（如果可用），不会使用到web版本。

 

辅助功能

通过Accessibility API，可以轻松知道用户何时启用了屏幕阅读器，以及通过连接的屏幕阅读器以编程方式说出标签。

 

目录

• isScreenReaderEnabled()
• removeAllListeners()
• speak()
• addListener('accessibilityScreenReaderStateChange')

 

示例

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

const { Accessibility, Modals } = Plugins;

Accessibility.addListener('accessibilityScreenReaderStateChange', (state) => {
  console.log(state.value);
});

async isVoiceOverEnabled() {
  var vo = await Accessibility.isScreenReaderEnabled();
  alert('Voice over enabled? ' + vo.value);
}

async speak() {
  var value = await Modals.prompt({
    title: "Value to speak",
    message: "Enter the value to speak"
  });

  Accessibility.speak({value: value.value});
}

 

API

isScreenReaderEnabled

isScreenReaderEnabled(): Promise<ScreenReaderEnabledResult>

检查设备上是否启用了屏幕阅读器

返回值： Promise<ScreenReaderEnabledResult>

removeAllListeners

removeAllListeners ():void

删除此插件的所有原生监听器

返回： void

speak

speak(options: AccessibilitySpeakOptions): Promise<void>

用连接的屏幕阅读器说出一个字符串。

选项 AccessibilitySpeakOptions

返回值： Promise

addListener

addListener(eventName: “ accessibilityScreenReaderStateChange”,listenerFunc ： 

ScreenReaderStateChangeCallback): PluginListenerHandle

监听屏幕阅读器状态更改（打开/关闭）

eventName “ accessibilityScreenReaderStateChange”

listenerFunc ScreenReaderStateChangeCallback

返回值： PluginListenerHandle

 

使用的接口

ScreenReaderEnabledResult

interface ScreenReaderEnabledResult {
value : boolean;
}

 

AccessibilitySpeakOptions

interface AccessibilitySpeakOptions {
// The language to speak the string in, as its [ISO 639-1 Code](https://www.loc.gov/standards/iso639-2/php/code_list.php) (ex: "en"). Currently only supported on Android.
language ?: string;
// The string to speak
value : string;
}

 

ScreenReaderStateChangeCallback

type alias ScreenReaderStateChangeCallback {
}

 

App

App API处理高级应用程序状态和事件。

例如，这个API在应用程序进入和离开前台时发出事件，处理深度链接，打开其他应用程序，并管理持久的插件状态。

目录

• canOpenUrl()
• exitApp()
• getLaunchUrl()
• getState()
• openUrl()
• removeAllListeners()
• addListener('appStateChange')
• addListener('appUrlOpen')
• addListener('appRestoredResult')
• addListener('backButton')

 

注意canOpenUrl

要使用canOpenUrl，您需要在Info.plist文件的LSApplicationQueriesSchemes里面设置应用程序将要查询的URL方案

阅读更多关于 LSApplicationQueriesSchemes 和 configuring Info.plist。

 

示例

import { Plugins, AppState } from '@capacitor/core';

const { App } = Plugins;

App.addListener('appStateChange', (state: AppState) => {
  // state.isActive contains the active state
  console.log('App state changed. Is active?', state.isActive);
});

// Listen for serious plugin errors
App.addListener('pluginError', (info: any) => {
  console.error('There was a serious error with a plugin', err, info);
});

var ret = await App.canOpenUrl({ url: 'com.getcapacitor.myapp' });
console.log('Can open url: ', ret.value);

ret = await App.openUrl({ url: 'com.getcapacitor.myapp://page?id=ionicframework' });
console.log('Open url response: ', ret);

ret = await App.getLaunchUrl();
if(ret && ret.url) {
  console.log('App opened with URL: ' + ret.url);
}
console.log('Launch url: ', ret);

App.addListener('appUrlOpen', (data: any) => {
  console.log('App opened with URL: ' +  data.url);
});

App.addListener('appRestoredResult', (data: any) => {
  console.log('Restored state:', data);
});

 

安卓：使用appRestoredResult

在Android上，由于低端设备的内存限制，如果你的应用程序启动一个新的活动，你的应用程序可能会被操作系统终止，以减少内存消耗。

例如，这意味着Camera接口在启用相机进行拍照后，可能无法将数据返回到您的应用程序。

为了避免这种情况，Capacitor会把所有的重新打开的活动存放在控制台。您应该为appRestoredResult添加一个监听器，以便处理在应用程序未运行时传递的任何插件调用结果。

一旦得到结果（如果有），就可以更新UI以恢复用户的逻辑体验，例如导航或选择适当的选项卡。

我们建议每个Android应用程序使用依赖于外部活动（例如相机）的插件来处理这个事件和过程。

 

API

canOpenUrl

canOpenUrl(options: { url: string }): <{ value: boolean }>

检查应用程序是否能被给定的URL打开

options {url: string}

returns: Promise<{value: boolean}>

 

exitApp

exitApp(): never

强制退出应用程序。这只应与Android的“backButton”处理程序一起使用，以便在导航完成后退出应用程序。

returns: never

 

getLaunchUrl

getLaunchUrl():Promise<AppLaunchUrl>

获取应用程序启动时使用的URL（如果有）

returns: Promise

 

getState

getState():Promise<AppState>

获取当前APP的状态

returns: Promise

 

openUrl

openUrl(options: { url: string }):Promise <{ completed: boolean }>

通过给定的URL打开APP

options { url: string }

returns: Promise<{ completed: boolean}>

 

removeAllListeners

removeAllListeners(): void

删除此插件的所有原生监听器

returns: void

 

addListener

addListener(eventName: "appStateChange", listenerFunc: (state: ) => void): 
PluginListenerHandle

监听应用程序活动状态的更改（无论应用程序处于前台还是后台）

eventName "appStateChange"

listenerFunc (state: AppState) => void

returns: PluginListenerHandle

 

addListener

addListener(eventName: "appUrlOpen", listenerFunc: (data: AppUrlOpen ) => void): 
PluginListenerHandle

监听应用程序的url打开事件。这既可以处理自定义URL方案链接，也可以处理应用程序处理的URL（iOS上的通用链接和Android上的应用程序链接）

eventName "appUrlOpen"

listenerFunc (data: AppUrlOpen) => void

returns: PluginListenerHandle

 

addListener

addListener(eventName: "appRestoredResult", listenerFunc: 

(data: AppRestoredResult) => void): PluginListenerHandle

如果应用程序是使用先前保存的插件调用数据启动的，例如在Android上，当某个活动返回到已关闭的应用程序时，此调用将返回应用程序启动时使用的所有数据，并转换为插件调用的结果形式。

eventName "appRestoredResult"

listenerFunc (data: AppRestoredResult) => void

returns: PluginListenerHandle

 

addListener

addListener(eventName: "backButton", listenerFunc: (data: AppUrlOpen) => void): 

PluginListenerHandle

监听硬件后退按钮事件（仅限Android）。监听此事件将禁用默认的后退按钮行为，因此您可能需要手动调用window.history.back，如果你想要关闭APP，调用App.exitApp()。

eventName "backButton"

listenerFunc (data: AppUrlOpen) => void

returns: PluginListenerHandle

 

Interfaces Used

AppLaunchUrl

interface AppLaunchUrl {
	url : string;
}

 

AppState

interface AppState {
	isActive : boolean;
}