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

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<?php
2
3namespace App\NativeComponents;
4
5use App\Models\Delivery;
6use Illuminate\View\View;
7use Native\Mobile\Attributes\Locked;
8use Native\Mobile\Attributes\Poll;
9use Native\Mobile\Edge\NativeComponent;
10
11class DeliveryTracker extends NativeComponent
12{
13    #[Locked]
14    public int $deliveryId;
15
16    public string $status = 'awaiting_pickup';
17
18    public ?string $courier = null;
19
20    public function mount(): void
21    {
22        $this->syncFromDatabase();
23    }
24
25    #[Poll(5000)]
26    public function syncFromDatabase(): void
27    {
28        $delivery = Delivery::findOrFail($this->deliveryId);
29
30        $this->status = $delivery->status;
31        $this->courier = $delivery->courier_name;
32    }
33
34    public function confirmReceipt(): void
35    {
36        Delivery::findOrFail($this->deliveryId)->markReceived();
37
38        $this->syncFromDatabase();
39    }
40
41    public function render(): View
42    {
43        return view('native.delivery-tracker');
44    }
45}
46

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

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

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

1<column class="flex-1 p-6 gap-4 bg-theme-background safe-area">
2    <text class="text-2xl font-bold text-theme-on-background">
3        {{ str($status)->headline() }}
4    </text>
5
6    @if ($courier)
7        <text class="text-sm text-gray-500">Courier: {{ $courier }}</text>
8    @endif
9
10    <pressable @tap="confirmReceipt" class="px-6 py-4 rounded bg-theme-primary items-center">
11        <text class="text-theme-on-primary font-semibold">Confirm receipt</text>
12    </pressable>
13</column>
14

<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 />
2

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

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

使用 Pest 测试原生界面

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

1use App\NativeComponents\DeliveryTracker;
2use Native\Mobile\Testing\Native;
3
4it('confirms receipt of a delivery', function () {
5    $delivery = Delivery::factory()->create(['status' => 'out_for_delivery']);
6
7    Native::visit("/deliveries/{$delivery->id}")
8        ->assertSee('Out For Delivery')
9        ->tap('Confirm receipt')
10        ->assertSet('status', 'received');
11});
12

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

4.1 版本

4.1 版本于 8 月 7 日发布。#[Locked] 用于标记双向绑定无法写入的属性（#260）。如果误写 native:model="deliveryId"，系统会抛出错误，从而阻止文本输入框改写当前界面上的记录。

TreeObservers 可以观察运行时发布的元素树（#259），为会话录制和调试工具提供所需能力。同一版本还提供基于该钩子的 TreeSpy 测试工具，使测试既能对中间帧执行断言，也能检查最终状态。

此外还有两项较小的更新：NativeRouteFallback 用于设置浏览器访问仅限原生端的路由时看到的内容（#268）；Tailwind 解析器现在会对超出支持范围的类名发出警告（#296）。

从 v3 升级

v4 的大部分改动都是新增内容，升级指南说明应用代码无需改动。唯一的破坏性变更来自依赖项。Device、Dialog、File 和 System 现在属于核心组件，而 nativephp/mobile 会通过 Composer 声明与这四个独立插件包冲突，因此必须先移除它们，Composer 才能完成依赖解析：

1php artisan native:plugin:uninstall --core-v4
2

该命令会移除全部四个插件，并从 NativeServiceProvider 中取消注册。添加 --force 可以跳过提示。随后将版本约束升级到 ~4.0.0，并重新生成原生项目文件：

1composer update
2php artisan native:install --force
3

Facade 和事件保持不变，因此现有的 Dialog::alert() 调用仍可继续工作。Vite 开发服务器现在改为按需启用：需要使用时，为 native:watch 或 native:run 传入 --vite，并从脚本中移除 --no-vite 参数。插件作者应将版本约束扩展为 ^3.0|^4.0。该软件包还在内置 Boost skills 中提供了一个 v3 到 v4 的升级 skill，开发者也可借助智能体完成升级。

针对 NativePHP 的常见质疑是，原生外壳中的 WebView 算不上原生应用。对于开发者选择转换的界面，v4 已经给出了回应，同时无需学习 Swift 或 Kotlin。组件是 PHP 类，模板使用 Blade，测试则由 Pest 编写。

界面还可以逐个转换。由于 <webview> 已成为组件，团队可以优先迁移存在滚动性能或无障碍问题的界面，其余部分继续沿用现有实现。

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

《NativePHP v4 让 Blade 构建原生 iOS 与 Android 界面》 是转载文章，点击查看原文。