事件

概述

许多原生移动操作需要时间完成并等待用户交互。PHP 并不适合处理这种异步行为；它被设计为完成工作、发送响应并尽快继续。

NativePHP for Mobile 使用简单的事件系统来平滑这种不同范式之间的差异，使用类似 webhook/websocket 的方法处理异步方法的完成，以通知你的 Laravel 应用。

理解异步 vs 同步

并非所有操作都是异步的。某些方法立即运行，在某些情况下立即返回结果。

以下是一些同步 API：

Haptics::vibrate();
System::flashlight();
Dialog::toast('Hello!');

异步操作触发可能稍后完成的操作。它们立即返回，通常返回 bool 或 void，允许 PHP 的执行完成。在许多情况下，用户直接与原生组件交互。

当用户完成任务并且原生 UI 被关闭时，应用将发出一个代表结果的事件。

事件的_类型_（类名）及其属性都帮助你选择适当的操作来响应结果。

// 这些触发操作并在完成时触发事件
Camera::getPhoto(); // → PhotoTaken 事件
Biometrics::prompt(); // → Completed 事件
PushNotifications::enroll(); // → TokenGenerated 事件

基本事件结构

所有事件都是标准的 Laravel 事件类。事件的公共属性包含来自原生应用端的相关数据。

自定义事件

几乎每个发出事件的函数都可以自定义为发出你定义的事件。这是确保只有相关监听器在这些事件触发时执行的好方法。

事件是接收一些参数的简单 PHP 类。为方便起见，你可以扩展现有事件。

让我们看一个完整的示例...

定义你的自定义事件类

namespace App\Events;

use Native\Mobile\Events\Alert\ButtonPressed;

class MyButtonPressedEvent extends ButtonPressed
{}

将此类传递给异步函数

use App\Events\MyButtonPressedEvent;

Dialog::alert('Warning!', 'You are about to delete everything! Are you sure?', [
        'Cancel',
        'Do it!'
    ])
    ->event(MyButtonPressedEvent::class)

处理事件

以下是在 Livewire 组件内处理自定义事件类的示例。

use App\Events\MyButtonPressed;
use Native\Mobile\Attributes\OnNative;

#[OnNative(MyButtonPressed::class)]
public function buttonPressed()
{
    // 做一些事情
}

事件处理

所有异步方法都遵循相同的模式：

1. 调用方法来触发操作。
2. 监听适当的事件来处理结果。
3. 根据结果更新你的 UI。

所有事件都直接发送到 Web 视图中的 JavaScript _以及_通过特殊路由发送到你的 PHP 应用程序。这允许你在最适合你应用程序的上下文中监听这些事件。

在前端

事件通过自定义 Native 助手通过 Web 视图"广播"到应用程序的前端。你可以通过几种方式轻松地通过 JavaScript 监听这些事件：

• 全局可用的 Native.on() 助手
• 直接导入 on 函数
• #[OnNative()] PHP 属性 Livewire 扩展

提示

通常，你不需要使用超过一种方法。你采用哪种方法将取决于你使用哪种前端技术栈来构建应用。

Native.on() 助手

直接在 JavaScript 中注册事件监听器：

@@use(Native\Mobile\Events\Alert\ButtonPressed)

<script>
    Native.on(@@js(ButtonPressed::class), (index, label) => {
        alert(`You pressed button ${index}: ${label}`)
    })
</script>

如果你没有使用任何特定的前端 JavaScript 框架，这种方法很有用。

on 导入

提示

确保你首先在 package.json 中设置了 Native 插件。

如果你使用像 Vue 或 React 这样的 SPA 框架，直接导入 on 函数来注册事件监听器更方便。以下是使用优秀的 Vue 的示例：

import { on, Events } from '#nativephp';
import { onMounted } from 'vue';

const handleButtonPressed = (payload: any) => {};

onMounted(() => {
    on(Events.Alert.ButtonPressed, handleButtonPressed);
});

注意我们上面也使用了 Events 对象来简化对内置事件名称的使用。对于自定义事件类，你需要通过它们的完整名称引用：

on('App\\Events\\MyButtonPressedEvent', handleButtonPressed);

在 SPA 领域，别忘了也使用 off 函数注销你的事件处理程序：

import { off, Events } from '#nativephp';
import { onUnmounted } from 'vue';

onUnmounted(() => {
    off(Events.Alert.ButtonPressed, handleButtonPressed);
});

#[OnNative()] 属性

Livewire 使监听"广播"事件变得简单。只需将 #[OnNative()] 属性附加到你想用作处理程序的 Livewire 组件方法上：

use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\Camera\PhotoTaken;

#[OnNative(PhotoTaken::class)]
public function handlePhoto(string $path)
{
    // 处理捕获的照片
}

在后端

你也可以在 PHP 端监听这些事件，因为它们同时传递给你的 Laravel 应用程序。

只需像往常一样添加监听器：

use App\Services\APIService;
use Native\Mobile\Events\Camera\PhotoTaken;

class UpdateAvatar
{
    public function __construct(private APIService $api) {}
    
    public function handle(PhotoTaken $event): void
    {
        $imageData = base64_encode(
            file_get_contents($event->path)
        );
        
        $this->api->updateAvatar($imageData);
    }
}