NativePHP Mobile 中文文档

Appearance

更新日志 ​

v2.2.0 ​

此版本包含对 EDGE 组件、安装体验和构建工具的重大改进。

EDGE 必需 Props 验证 ​

EDGE 组件现在在渲染时验证必需的 props。新的 MissingRequiredPropsException 提供清晰的错误消息，准确显示缺少哪些 props 以及如何修复。验证在 BottomNavItem、SideNavItem、TopBarAction、SideNavGroup 和 TopBar 上强制执行。

基于字体的图标渲染 ​

用使用字体连字的 348KB 字体文件替换了 30MB 的 material-icons-extended 库，以实现高效的图标渲染。

  • iOS：支持直接的 SF Symbol 路径（例如 car.side.fill、flashlight.on.fill）
  • Android：任何 Material Icon 连字名称都可以直接使用
  • 为方便起见，保留了跨平台友好的名称别名
blade
@use(Native\Mobile\Facades\System)

<native:bottom-nav-item
    ...
    icon="{{ System::isIos() ? 'flashlight.on.fill' : 'flashlight_on' }}"
/>

自动提示应用 ID ​

native:install 现在会在 NATIVEPHP_APP_ID 未设置时提示输入，并使用 com.{username}.{randomwords} 格式自动生成建议的 bundle ID。

改进的 iOS 构建日志 ​

使用 twoColumnDetail() 格式标准化了 App Store Connect 操作的控制台输出。用一致的 Laravel Prompts 样式替换了表情符号前缀的日志。

详细的错误诊断与常见 Xcode 构建错误的模式匹配现在为以下问题提供具体的可操作解决方案：

  • 证书/配置文件不匹配
  • 配置文件过期
  • 缺少签名证书
  • 代码签名错误

当构建失败时，会显示最后 30 行错误输出以及用于调试的构建日志路径。

其他改进 ​

  • 更好地处理 Apple 上传时的误报
  • 构建日志路径使用 note() 以保持一致的样式

v2.1.1 ​

前台权限 ​

当相机功能需要时，即使推送通知被禁用，也会阻止删除 FOREGROUND_SERVICE 和 POST_NOTIFICATIONS 权限

符号链接修复 ​

在 storage:link 之前运行 storage:unlink 以处理过时的符号链接，并从构建中排除 public/storage 以防止符号链接冲突

iOS 推送通知 ​

以不同方式处理推送通知 APNS 流程，在从 FCM 收到令牌后立即触发原生事件，而不是假设 AppDelegate 会处理它。

修复某些事件中缺失的 $id 参数 ​

某些事件缺少 $id 参数，这会导致用户在尝试从事件接收 ID 时遇到错误。

v2.1.0 ​

更简洁的控制台输出 ​

native:run 命令现在提供更简洁、更易读的输出，使开发过程中更容易跟踪正在发生的事情。

改进的 Windows 支持 ​

为 Windows 用户提供更好的兼容性和更流畅的开发体验。

所有用户注意

在内部，Gradle 已升级，第一次运行 Android 构建时将需要多花几分钟来下载和安装新的依赖项。

Blade 指令 ​

用于基于平台条件渲染的新 Blade 指令：

blade
仅在移动应用中渲染
@mobile / @endmobile

仅在 Web 浏览器中渲染
@web / @endweb

仅在 iOS 上渲染
@ios / @endios

仅在 Android 上渲染
@android / @endandroid

改进的文件监视器 ​

文件监视器已完全重构，从 fswatch 切换到 Watchman 以获得更好的性能和可靠性。监视器现在与 Vite HMR 结合，提供统一的开发体验。

常见 URL Scheme ​

NativePHP 现在自动处理常见的 URL scheme，在适当的原生应用中打开它们：

  • tel: - 电话呼叫
  • mailto: - 电子邮件
  • sms: - 短信
  • geo: - 地图/位置
  • facetime: - FaceTime 视频通话
  • facetime-audio: - FaceTime 音频通话

Android 深度链接 ​

支持 Android 上的自定义深度链接和应用链接，允许其他应用和网站直接链接到你的应用。

其他更改 ​

  • System::appSettings() 在系统设置应用中打开你的应用设置屏幕
  • Edge::clear() 移除所有 EDGE 组件
  • 向 JavaScript 库添加了 Native.shareUrl()
  • native:install：添加了 --fresh 和 -F 作为 --force 的别名
  • native:install：为较慢的网络增加了超时时间

Bug 修复 ​

  • 修复了扫描器权限
  • 修复了 Android 边到边显示
  • 修复了 iOS 上的 Browser::auth
  • 修复了 iOS 上原生顶部栏组件的文本对齐
  • 修复了 iOS 上的 plist 问题
  • 修复了 NATIVEPHP_START_URL 配置
  • 修复了 Android 上相机取消事件
  • 修复了底部导航值不能动态更新的问题

v2.0.0 ​

JavaScript/TypeScript 库 ​

全新的 JavaScript 桥接库，为 Vue、React、Inertia 和原生 JS 应用提供完整的 TypeScript 声明。这使得可以直接从前端代码调用原生设备功能。在此了解更多。

EDGE - 元素定义和生成引擎 ​

使用 Blade 在设备上原生渲染导航组件的新原生 UI 系统。在此了解更多。

Laravel Boost 支持 ​

与 Laravel Boost 完全集成，用于 AI 辅助开发。在此了解更多。

热模块替换 (HMR) 重构 ​

用于快速开发的完整 Vite HMR。在此了解更多。

功能：

  • 自定义 Vite 插件
  • iOS/Android 的自动 HMR 服务器配置
  • iOS 上 axios 的 PHP 协议适配器（不再需要 patch-inertia 命令！）
  • 即使没有物理设备插入也可以通过网络工作！

流畅的 Pending API (PHP) ​

所有异步方法现在都实现了流畅的 API，以获得更好的 IDE 支持和易用性。

php
Dialog::alert('Confirm', 'Delete this?', ['Cancel', 'Delete'])
    ->remember()
    ->show();
js
import { dialog, on, off, Events } from '#nativephp';
const label = ref('');

const openAlert = async () => {
    await dialog.alert()
        .title('Alert')
        .message('This is an alert dialog.')
        .buttons(['OK', 'Cool', 'Cancel']);
};

const buttonPressed = (payload: any) => {
    label.value = payload.label;
};

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

#[OnNative] Livewire 属性 ​

忘掉过去愚蠢的字符串拼接；使用这个直接替换进入今天时尚的属性用法：

php
use Livewire\Attributes\OnNative; // [tl! remove]
use Native\Mobile\Attributes\OnNative; // [tl! add]

#[On('native:'.ButtonPressed::class)] // [tl! remove]
#[OnNative(ButtonPressed::class)] // [tl! add]
public function handle()

视频录制 ​

在此了解更多关于新视频录制器支持的信息。

二维码/条形码扫描器 ​

在此了解更多关于新二维码/条形码扫描器支持的信息。

麦克风 ​

在此了解更多关于新麦克风支持的信息。

网络检测 ​

在此了解更多关于新网络检测支持的信息。

后台音频录制 ​

只需更新你的配置，即使设备锁定也能录制音频！

php
// config/nativephp.php
'permissions' => [
    'microphone' => true,
    'microphone_background' => true,
],

推送通知 API ​

用于推送通知注册的新流畅 API：

php
use Native\Mobile\Facades\PushNotifications;
use Native\Mobile\Events\PushNotification\TokenGenerated;

PushNotifications::enroll();

#[OnNative(TokenGenerated::class)]
public function handlePushNotificationsToken($token)
{
    $this->token = $token;
}
js
import { pushNotifications, on, off, Events } from '#nativephp';

const token = ref('');

const promptForPushNotifications = async () => {
    await pushNotifications.enroll();
};

const handlePushNotificationsToken = (payload: any) => {
    token.value = payload.token;
};

onMounted(() => {
    on(Events.PushNotification.TokenGenerated, handlePushNotificationsToken);
});

onUnmounted(() => {
    off(Events.PushNotification.TokenGenerated, handlePushNotificationsToken);
});

已弃用的方法：

  • enrollForPushNotifications() → 使用 enroll()
  • getPushNotificationsToken() → 使用 getToken()

平台改进 ​

iOS ​

  • 平台检测 - body 上的 nativephp-ios 类
  • 键盘检测 - 键盘显示时的 keyboard-visible 类
  • iOS 26 Liquid Glass 支持
  • 改进的设备选择器 - native:run 显示上次使用的设备
  • 加载时间 大幅改善。现在快 60-80%！

Android ​

  • 完整的 Android 16+ 16KB 页面大小 兼容性
  • Jetpack Compose UI - 从 XML 布局迁移
  • 平台检测 - body 上的 nativephp-android 类
  • 键盘检测 - 键盘显示时的 keyboard-visible 类
  • 并行 zip 解压 以加快安装速度
  • 加载时间 大幅改善。快约 40%！
  • 页面加载时间 大幅减少约 40%！

配置 ​

新选项 ​

php
'start_url' => env('NATIVEPHP_START_URL', '/'),

'permissions' => [
    'microphone' => false,
    'microphone_background' => false,
    'scanner' => false,
    'network_state' => true, // 默认为 true
],

'ipad' => false,

'orientation' => [
    'iphone' => [...],
    'android' => [...],
],

自定义权限原因 (iOS) ​

php
'camera' => 'We need camera access to scan membership cards.',
'location' => 'Location is used to find nearby stores.',

新事件 ​

  • Camera\VideoRecorded、Camera\VideoCancelled、Camera\PhotoCancelled
  • Microphone\MicrophoneRecorded、Microphone\MicrophoneCancelled
  • Scanner\CodeScanned

自定义事件 ​

许多原生调用现在接受自定义事件类！

php
Dialog::alert('Confirm', 'Delete this?', ['Cancel', 'Delete'])
    ->event(MyCustomEvent::class)

更好的文件系统支持 ​

NativePHP 现在为你的文件系统创建符号链接！持久化存储保留在 storage 中，但会符号链接到 public 目录以在 Web 视图中显示！另外还有预配置的 mobile_public 文件系统磁盘。

dotenv
FILESYSTEM_DISK=mobile_public
php
$imageUrl = Storage::url($path);
html
<img :src="$imageurl" />

Bug 修复 ​

  • 修复了某些 Laravel 设置中打包时的无限递归
  • 修复了不同设备尺寸的 iOS 工具栏填充
  • 修复了 Android 调试模式强制 APP_DEBUG=true
  • 修复了方向配置键大小写敏感性（iPhone vs iphone）

破坏性更改 ​

  • 无

基于 NativePHP 官方文档翻译

Copyright © 2024 NativePHP