NativePHP v4 让 Blade 构建原生 iOS 与 Android 界面

NativePHP 现在可以将 Blade 组件渲染为 iOS 上真正的 SwiftUI 视图和 Android 上的 Jetpack Compose 视图，整个过程无需 WebView 或 HTML。NativePHP 将这项技术称为 SuperNative。Simon Hamp 与 Shane Rosenthal 于 7 月 30 日在二人于波士顿主办的 The Vibes 活动上发布了 SuperNative。这场活动共有 100 人参加，举办时间为 Laracon US 闭幕次日。

如果曾在一年前了解过 NativePHP，并将其视为运行在 WebView 中的 Laravel，v4 值得重新审视。WebView 仍然可用，现有应用也可以继续采用这种方式，但构建界面已经有了新的选择。SuperNative 是 v4 的默认方案，截至 4.1 版本仍处于 beta 阶段，因此文档提醒开发者为快速迭代做好准备。

主要亮点：

• • 使用 Blade 构建原生 UI。组件集名为 EDGE，即 Element Definition and Generation Engine，它会直接编译为 SwiftUI 和 Jetpack Compose 视图。
• • 无需经过网络。PHP 与原生层直接共享内存，因此组件与屏幕之间没有往返请求，也不需要 WebView 桥接。
• • 采用类似 Livewire 的组件模型。它支持公共属性、mount()、操作方法，以及 #[Poll]、#[Computed]、#[Lazy] 和 #[Locked] 等 Attribute（特性）。
• • 使用 Pest 测试原生界面。测试可以在进程内挂载组件，并对组件发布的内容执行断言，因此无需模拟器即可在 CI 中运行。
• • 四个插件并入核心。Device、Dialog、File 和 System 现在随 nativephp/mobile 一同提供，这是该版本唯一的破坏性变更。

SuperNative 的工作原理

SuperNative 的架构有别于 Skia 或 Impeller 这样的完全自定义渲染器、运行在 PHP 上层或与 PHP 并行的虚拟机、转译器，以及 HTML 到原生界面的转换器。

NativePHP 的架构文档描述了其实现方式：

传统 Blade 引擎生成 HTML；NativePHP 构建的专用 Blade 引擎会将真正的 Blade 组件转换为一种简单的二进制表示。

这种表示形式是一个定长字节数组，由原生端的解释器读取，并据此构建 SwiftUI 和 Compose 视图。

SuperNative 界面的启动速度快于 WebView 界面。它无需启动 WebView、解析 bundle，也无需在每次点击时通过桥接层执行序列化。

无障碍功能通常是 WebView 应用的薄弱环节。由于界面由真正的 SwiftUI 和 Compose 视图构成，VoiceOver、TalkBack、动态字体以及平台辅助功能控件无需额外适配即可工作。仅含图标的控件仍需显式设置 a11y-label。

编写 SuperNative 界面

在 v3 中，一个界面对应一条 Web 路由。Blade、Livewire 或 Inertia 负责生成 HTML，再由 WebView 渲染；EDGE 则使用 Blade 中的声明为界面包裹原生外壳，例如真正的顶部栏、底部导航或悬浮操作按钮。界面本身没有对应的 PHP 类。

在 v4 中，界面本身就是组件。它由一个继承 NativeComponent 的 PHP 类和一个 Blade 视图组成。公共属性负责保存状态，公共方法提供视图调用的操作，#[Poll] 等 Attribute 用于处理周期性任务。下面这个配送跟踪器会轮询状态变化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<?php

namespace App\NativeComponents;

use App\Models\Delivery;
use Illuminate\View\View;
use Native\Mobile\Attributes\Locked;
use Native\Mobile\Attributes\Poll;
use Native\Mobile\Edge\NativeComponent;

class DeliveryTracker extends NativeComponent
{
    #[Locked]
    public int $deliveryId;

    public string $status = 'awaiting_pickup';

    public ?string $courier = null;

    publicfunction mount(): void
{
        $this->syncFromDatabase();
    }

    #[Poll(5000)]
    publicfunction syncFromDatabase(): void
{
        $delivery = Delivery::findOrFail($this->deliveryId);

        $this->status = $delivery->status;
        $this->courier = $delivery->courier_name;
    }

    publicfunction confirmReceipt(): void
{
        Delivery::findOrFail($this->deliveryId)->markReceived();

        $this->syncFromDatabase();
    }

    publicfunction render(): View
{
        return view('native.delivery-tracker');
    }
}

路由位于 routes/mobile.php 中，并通过 Route::native 宏注册。该宏接收组件类，而非控制器。原生外壳来自继承 NativeLayout 的自定义布局类，通过 ->layout() 关联；Route::nativeGroup 则可以为多条路由应用同一个布局：

1
2
3

Route::native('/deliveries/{deliveryId}', DeliveryTracker::class)
    ->layout(DeliveryLayout::class)
    ->name('deliveries.show');

视图仍然使用 Blade，其中采用的是原生基础元素。解析器会将 Tailwind 类名映射到对应的平台布局：

1
2
3
4
5
6
7
8
9
10
11
12
13

<column class="flex-1 p-6 gap-4 bg-theme-background safe-area">
    <text class="text-2xl font-bold text-theme-on-background">
        {{ str($status)->headline() }}
    </text>

    @if ($courier)
        <text class="text-sm text-gray-500">Courier: {{ $courier }}</text>
    @endif

    <pressable @tap="confirmReceipt" class="px-6 py-4 rounded bg-theme-primary items-center">
        <text class="text-theme-on-primary font-semibold">Confirm receipt</text>
    </pressable>
</column>

<column> 在 iOS 上会成为真正的 SwiftUI 布局，在 Android 上则会成为 Compose Column。@tap 处理器会直接调用 PHP 类中的方法。v4 还为触摸按下与松开事件新增了 @pressDown 和 @pressUp，可用于实现按住操作；单次点击则由 @tap 处理。

在手机上运行这个界面无需安装 Xcode 或 Android Studio。php artisan native:jump 会启动开发服务器并输出二维码。使用 App Store 和 Google Play 上免费的配套应用 Jump 扫描二维码，即可通过 Wi-Fi 在设备上加载应用。原生调用会转发至开发计算机上运行的 PHP，因此相机和生物识别功能与打包应用中的表现一致。当 NATIVEPHP_START_URL 指向 Route::native 界面时，Jump 会直接渲染原生 UI。这是目前在真实设备上查看 SuperNative 的最快方式。

保留现有 WebView

现有 v3 应用可以继续使用原有实现。WebView 现在是放置在原生界面中的一个组件：

1

<webview php url="/" fullscreen />

将原生路由指向包含该元素的界面，再在 .env 中设置 NATIVEPHP_START_URL=/home，routes/web.php 中的视图便会像之前一样继续渲染。两种方式可以混合使用：在尚未转换的界面中保留 WebView，并在其周围使用原生导航。每个采用 PHP 模式的嵌入式 WebView 都拥有独立的 PHP 运行时，因此不会与原生界面的运行时竞争资源。

v4 只有在 Web 路由实际渲染时才会启动 WebView。

使用 Pest 测试原生界面

由于界面是一个负责发布元素树的 PHP 对象，因此无需设备即可进行测试。测试套件提供 FakeBridge，用于捕获组件发布的每一棵树和发起的每一次原生调用；测试本身就是普通的 Pest 测试：

1
2
3
4
5
6
7
8
9
10
11

use App\NativeComponents\DeliveryTracker;
use Native\Mobile\Testing\Native;

it('confirms receipt of a delivery', function () {
    $delivery = Delivery::factory()->create(['status' => 'out_for_delivery']);

    Native::visit("/deliveries/{$delivery->id}")
        ->assertSee('Out For Delivery')
        ->tap('Confirm receipt')
        ->assertSet('status', 'received');
});

Native::test() 会直接挂载组件类，Native::visit() 会经过已注册的原生路由并解析路由参数，tap() 会触发与指定 ref 或可见文本匹配的 pressable，随后重新渲染。php artisan native:make-test DeliveryTracker 可以生成测试文件。开发者还可以使用 FakeBridge 宏添加自定义断言，测试插件发起的原生调用。

4.1 版本