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;
}
文章评论