移动端插件开发

插件可以运行用 Kotlin（或 Java）和 Swift 编写的本地移动代码。默认插件模板包含一个使用 Kotlin 的 Android 库项目和一个 Swift 包，其中包含一个示例移动命令，展示了如何从 Rust 代码触发其执行。

初始化插件项目

按照插件开发指南中的步骤初始化新的插件项目。

如果您有现有的插件并希望为其添加 Android 或 iOS 功能，可以使用plugin android init和plugin ios init来引导移动库项目并指导您完成所需的更改。

默认插件模板将插件的实现分为两个单独的模块：desktop.rs和mobile.rs。

桌面实现使用 Rust 代码来实现功能，而移动实现将消息发送到本地移动代码以执行功能并获取结果。如果两个实现都需要共享逻辑，则可以在lib.rs中定义

use tauri::Runtime;

impl<R: Runtime> <plugin-name><R> {
  pub fn do_something(&self) {
    // do something that is a shared implementation between desktop and mobile
  }
}

此实现简化了共享可由命令和 Rust 代码使用的 API 的过程。

开发 Android 插件

Android 的 Tauri 插件被定义为一个 Kotlin 类，该类扩展了app.tauri.plugin.Plugin并使用app.tauri.annotation.TauriPlugin进行注释。每个使用app.tauri.annotation.Command注释的方法都可以由 Rust 或 JavaScript 调用。

Tauri 默认使用 Kotlin 进行 Android 插件实现，但如果您愿意，可以切换到 Java。生成插件后，在 Android Studio 中右键单击 Kotlin 插件类，然后从菜单中选择“将 Kotlin 文件转换为 Java 文件”选项。Android Studio 将指导您完成项目迁移到 Java 的过程。

开发 iOS 插件

iOS 的 Tauri 插件被定义为一个 Swift 类，该类扩展了Tauri包中的Plugin类。每个带有@objc属性和(_ invoke: Invoke)参数的函数（例如@objc private func download(_ invoke: Invoke) { }）都可以由 Rust 或 JavaScript 调用。

插件被定义为一个Swift 包，这样您就可以使用其包管理器来管理依赖项。

插件配置

有关开发插件配置的更多详细信息，请参阅插件开发指南的插件配置部分。

移动端的插件实例具有插件配置的 getter

Android
iOS

import android.app.Activity
import android.webkit.WebView
import app.tauri.annotation.TauriPlugin
import app.tauri.annotation.InvokeArg

@InvokeArg
class Config {
    var timeout: Int? = 3000
}

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
  private var timeout: Int? = 3000

  override fun load(webView: WebView) {
    getConfig(Config::class.java).let {
       this.timeout = it.timeout
    }
  }
}

struct Config: Decodable {
  let timeout: Int?
}

class ExamplePlugin: Plugin {
  var timeout: Int? = 3000

  @objc public override func load(webview: WKWebView) {
    do {
      let config = try parseConfig(Config.self)
      self.timeout = config.timeout
    } catch {}
  }
}

生命周期事件

插件可以挂钩到几个生命周期事件

load：插件加载到 Web 视图时
onNewIntent：仅限 Android，当活动重新启动时

插件开发指南中还有额外的插件生命周期事件。

load

何时：插件加载到 Web 视图时
原因：执行插件初始化代码

Android
iOS

import android.app.Activity
import android.webkit.WebView
import app.tauri.annotation.TauriPlugin

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
  override fun load(webView: WebView) {
    // perform plugin setup here
  }
}

class ExamplePlugin: Plugin {
  @objc public override func load(webview: WKWebView) {
    let timeout = self.config["timeout"] as? Int ?? 30
  }
}

onNewIntent

注意：此功能仅适用于 Android。

何时：活动重新启动时。更多信息请参见Activity#onNewIntent。
原因：处理应用程序重新启动，例如单击通知或访问深度链接时。

import android.app.Activity
import android.content.Intent
import app.tauri.annotation.TauriPlugin

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
  override fun onNewIntent(intent: Intent) {
    // handle new intent event
  }
}

添加移动命令

在各自的移动项目中有一个插件类，其中可以定义命令，这些命令可以由 Rust 代码调用

Android
iOS

import android.app.Activity
import app.tauri.annotation.Command
import app.tauri.annotation.TauriPlugin

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
  @Command
  fun openCamera(invoke: Invoke) {
    val ret = JSObject()
    ret.put("path", "/path/to/photo.jpg")
    invoke.resolve(ret)
  }
}

如果要使用 Kotlin suspend 函数，则需要使用自定义协程作用域

import android.app.Activity
import app.tauri.annotation.Command
import app.tauri.annotation.TauriPlugin

// Change to Dispatchers.IO if it is intended for fetching data
val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
  @Command
  fun openCamera(invoke: Invoke) {
    scope.launch {
      openCameraInner(invoke)
    }
  }

  private suspend fun openCameraInner(invoke: Invoke) {
    val ret = JSObject()
    ret.put("path", "/path/to/photo.jpg")
    invoke.resolve(ret)
  }
}

在 Android 上，原生命令安排在主线程上。执行长时间运行的操作会导致 UI 冻结，并可能导致“应用程序无响应”(ANR) 错误。

如果需要等待一些阻塞 I/O，可以像这样启动一个协程

CoroutineScope(Dispatchers.IO).launch {
  val result = myLongRunningOperation()
  invoke.resolve(result)
}

class ExamplePlugin: Plugin {
  @objc public func openCamera(_ invoke: Invoke) throws {
    invoke.resolve(["path": "/path/to/photo.jpg"])
  }
}

使用tauri::plugin::PluginHandle从 Rust 调用移动命令

use std::path::PathBuf;
use serde::{Deserialize, Serialize};
use tauri::Runtime;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CameraRequest {
  quality: usize,
  allow_edit: bool,
}

#[derive(Deserialize)]
pub struct Photo {
  path: PathBuf,
}


impl<R: Runtime> <plugin-name;pascal-case><R> {
  pub fn open_camera(&self, payload: CameraRequest) -> crate::Result<Photo> {
    self
      .0
      .run_mobile_plugin("openCamera", payload)
      .map_err(Into::into)
  }
}

命令参数

参数被序列化为命令，并可以在移动插件中使用Invoke::parseArgs函数进行解析，该函数接受描述参数对象的类。

Android

在 Android 上，参数被定义为一个带有@app.tauri.annotation.InvokeArg注释的类。内部对象也必须注释

import android.app.Activity
import android.webkit.WebView
import app.tauri.annotation.Command
import app.tauri.annotation.InvokeArg
import app.tauri.annotation.TauriPlugin

@InvokeArg
internal class OpenAppArgs {
  lateinit var name: String
  var timeout: Int? = null
}

@InvokeArg
internal class OpenArgs {
  lateinit var requiredArg: String
  var allowEdit: Boolean = false
  var quality: Int = 100
  var app: OpenAppArgs? = null
}

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
  @Command
  fun openCamera(invoke: Invoke) {
    val args = invoke.parseArgs(OpenArgs::class.java)
  }
}

iOS

在 iOS 上，参数被定义为继承Decodable的类。内部对象也必须继承 Decodable 协议

class OpenAppArgs: Decodable {
  let name: String
  var timeout: Int?
}

class OpenArgs: Decodable {
  let requiredArg: String
  var allowEdit: Bool?
  var quality: UInt8?
  var app: OpenAppArgs?
}

class ExamplePlugin: Plugin {
  @objc public func openCamera(_ invoke: Invoke) throws {
    let args = try invoke.parseArgs(OpenArgs.self)

    invoke.resolve(["path": "/path/to/photo.jpg"])
  }
}

权限

如果插件需要最终用户的权限，Tauri 简化了检查和请求权限的过程。

Android
iOS

首先定义所需的权限列表和用于在代码中识别每个组的别名。这在TauriPlugin注释中完成

@TauriPlugin(
  permissions = [
    Permission(strings = [Manifest.permission.POST_NOTIFICATIONS], alias = "postNotification")
  ]
)
class ExamplePlugin(private val activity: Activity): Plugin(activity) { }

首先重写checkPermissions和requestPermissions函数

class ExamplePlugin: Plugin {
  @objc open func checkPermissions(_ invoke: Invoke) {
    invoke.resolve(["postNotification": "prompt"])
  }

  @objc public override func requestPermissions(_ invoke: Invoke) {
    // request permissions here
    // then resolve the request
    invoke.resolve(["postNotification": "granted"])
  }
}

Tauri 自动为插件实现了两个命令：checkPermissions和requestPermissions。这些命令可以直接从 JavaScript 或 Rust 调用

JavaScript
Rust

import { invoke, PermissionState } from '@tauri-apps/api/core'

interface Permissions {
  postNotification: PermissionState
}

// check permission state
const permission = await invoke<Permissions>('plugin:<plugin-name>|checkPermissions')

if (permission.postNotification === 'prompt-with-rationale') {
  // show information to the user about why permission is needed
}

// request permission
if (permission.postNotification.startsWith('prompt')) {
  const state = await invoke<Permissions>('plugin:<plugin-name>|requestPermissions', { permissions: ['postNotification'] })
}

use serde::{Serialize, Deserialize};
use tauri::{plugin::PermissionState, Runtime};

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct PermissionResponse {
  pub post_notification: PermissionState,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct RequestPermission {
  post_notification: bool,
}

impl<R: Runtime> Notification<R> {
  pub fn request_post_notification_permission(&self) -> crate::Result<PermissionState> {
    self.0
      .run_mobile_plugin::<PermissionResponse>("requestPermissions", RequestPermission { post_notification: true })
      .map(|r| r.post_notification)
      .map_err(Into::into)
  }

  pub fn check_permissions(&self) -> crate::Result<PermissionResponse> {
    self.0
      .run_mobile_plugin::<PermissionResponse>("checkPermissions", ())
      .map_err(Into::into)
  }
}

插件事件

插件可以使用trigger函数在任何时间点触发事件

Android
iOS

@TauriPlugin
class ExamplePlugin(private val activity: Activity): Plugin(activity) {
    override fun load(webView: WebView) {
      trigger("load", JSObject())
    }

    override fun onNewIntent(intent: Intent) {
      // handle new intent event
      if (intent.action == Intent.ACTION_VIEW) {
        val data = intent.data.toString()
        val event = JSObject()
        event.put("data", data)
        trigger("newIntent", event)
      }
    }

    @Command
    fun openCamera(invoke: Invoke) {
      val payload = JSObject()
      payload.put("open", true)
      trigger("camera", payload)
    }
}

class ExamplePlugin: Plugin {
  @objc public override func load(webview: WKWebView) {
    trigger("load", data: [:])
  }

  @objc public func openCamera(_ invoke: Invoke) {
    trigger("camera", data: ["open": true])
  }
}

然后可以使用addPluginListener辅助函数从 NPM 包调用辅助函数

import { addPluginListener, PluginListener } from '@tauri-apps/api/core';

export async function onRequest(
  handler: (url: string) => void
): Promise<PluginListener> {
  return await addPluginListener(
    '<plugin-name>',
    'event-name',
    handler
  );
}

在 Open Collective 上支持在 GitHub 上赞助