页面视图 WebView

上节课，我们知道了我们的页面UI是在哪里，这节课继续来学习。

理解单个原生网页视图（WebView）

所有使用 NativePHP 构建的移动端应用，都以单个原生网页视图（WebView） 为核心载体。网页视图允许你使用任意你熟悉的前端网页技术搭建应用界面（UI）。因为本质上它就是一个网页，内嵌的浏览器就可以帮你渲染这些网页了。

WebView 默认会占满整个可视区域，所有人都可以看到；不过，在打开前提功能，例如打开摄像头，WebView就会暂时被打开摄像头的操作界面覆盖。

Nativephp的本质就是：PHP 后端 + 任意前端栈混合开发（Vue jQUERY Thaiwind等等）

WebView 永久置顶展示，仅相机 / 内置浏览器等全屏场景会遮挡。WebView就是你看到的界面UI部分。

NativePHP 移动端底层本质：单 WebView 容器，没有多页面原生分层意思就是 nativephp只有一个页面，跳转返回都是在这个webview

NativePHP 移动端自始至终只存在唯一一个原生 WebView 控件，整个 App 所有界面渲染全部放在这一块网页容器里：

页面跳转、路由切换、返回上一页、弹窗、子页面、SPA 切换，通通都不会新建、不会新开第二个 WebView；这样的目的可以保证更少的内存开销。
不存在 Android /iOS 原生多页面栈、原生 Activity/ViewController 分层页面；
我们看到的 “多个页面” 本质都是前端路由（Laravel / Livewire / Vue Router 等）在同一个 WebView 内切换 DOM，和网页单页应用逻辑一模一样。

1 Viewport 配置（meta 标签控制屏幕适配）

开发过，手机网页的读者应该都知道上面的这个东西

和普通浏览器一致，WebView 拥有Viewport概念，代表页面可视区域，通过 meta 标签控制，写法和传统网页完全相同。

<meta name="viewport" content="width=device-width, initial-scale=1">Code language: HTML, XML (xml)

在你的html 或者php的页面中，加上这个meta标签。现在是移动互联网时代，很多网页都又这个配置，目的是使得你的网页更加适配移动手机的浏览器，如果没有这个配置，你的网页看上去就可能会文字很细，因为它不是适配手机端的。手机的分辨率dpi很高，如果没有这个配置，你的网页的文字还是以pc浏览器为准渲染的，就会显得字体细，排版不好看等等。

读者可以随便打开一个网页，就那nativephp的官网，Web View – NativePHP mobile v3 – NativePHP 右键浏览器，查看网页源码，可以看到。

以上的配置，有两个属性

width=device-width：页面宽度等于设备物理屏幕宽度

initial-scale=1：页面初始缩放比例 1:1，不自动放大缩小

2 禁用用户双指缩放（模拟原生 App 体验）

我们知道，原生的Android APP 或者IOS ，你是无法通过双指（合并撑开）这样来放大缩小的，但是手机的浏览器是可以这样的。为了使得你的NativePHP的页面更像APP，就需要禁用这个功能了，否则你的页面用户可以放大缩小。

开发移动端 App 时，通常需要更强界面可控性，禁止用户手动缩放页面，让应用表现和纯原生 App 一致。

在上面的viewport 中加上如下属性

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">Code language: HTML, XML (xml)

user-scalable=no：关闭手动缩放手势

3. 全屏边缘渲染 Edge-to-Edge（刘海 / 曲面屏适配前置）

为给 UI 设计最大的自由度，WebView 默认占满整块屏幕，只需要依靠 HTML/CSS/JS 就能在前台状态下任意位置显示内容。

但要注意：屏幕并非全部区域都能正常使用的。因为绝大多数设备存在前置摄像头刘海、圆角、曲面屏幕，苹果有灵动岛等等。这些区域依然属于视口范围，但会被遮挡、无法点击。

想要适配异形屏幕，需要在 meta Viewport标签中添加 viewport-fit=cover，配合安全边距（Safe Area Insets）使用。

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, viewport-fit=cover">Code language: HTML, XML (xml)

viewport-fit=cover：允许页面渲染延伸到屏幕最边缘（刘海、圆角区域）但是仅开启该参数还是会导致内容被刘海遮挡，必须搭配「安全区 Safe Area」样式使用，请读者往下按

安全区 Safe Areas

安全区指屏幕未被遮挡的可视区域：不会被硬件结构（圆角、前置摄像头刘海,灵动岛）、系统常驻 UI（底部 Home 手势条、状态栏）等等遮盖。

设备运行时会自动计算安全区范围，并随横竖屏切换动态调整；Nativephp仅靠一套简单 CSS 变量就能实现多设备自适应布局。

<!-- body 添加全局安全区约束 -->
<body class="nativephp-safe-area">
    <!-- 顶部栏左右预留屏幕圆角边距 -->
    <div class="fixed top-0 left-0 w-full bg-red-500 pl-[var(--inset-left)] pr-[var(--inset-right)]">
        顶部导航栏
    </div>
</body>Code language: HTML, XML (xml)

--inset-top顶部安全距离（状态栏 / 刘海高度）
--inset-bottom底部安全距离（手势条高度）
--inset-left左侧曲面 / 圆角安全边距
--inset-right右侧曲面 / 圆角安全边距

上面这几个css的样式，都是NativePHP Mobile 官方内置的，框架自动注入，所以不需要你依赖引入其他的css库

快捷全局 CSS 类：nativephp-safe-area

读者可以直接给你的html的标签容器，加入这个css类，自动约束内容在安全区内，简化开发。参考上面代码

可以做个测试，是如下这个没有做安全区适配的，如下是官方的例子，我们先借助官方的例子了解原理先，后面我们再用真机来测试。首先是，如果没有做安全区域的适配，例如下面这个，

<div class="fixed top-0 left-0 w-full bg-red-500">
    ...
</div>Code language: HTML, XML (xml)

上图，你可以看到，我们的顶部标题栏，直接跑到了摄像头的下方了。

如果你切换到横向模式下面，那就更加糟糕了。例如

上面，我们可以看到，手机横向看的是，左右两边的区域直接不能用上了，连顶部的标题栏都不能占满横屏的，看着就好像左右两边有一个很大的间隙，看着很不美观。

你如果加上了安全区域配置，例如body中增加官方的样式

<body class="nativephp-safe-area">
<div class="fixed top-0 left-0 w-full bg-red-500 pl-[var(--inset-left)] pr-[var(--inset-right)]">
    ...
</div>Code language: HTML, XML (xml)

是不是瞬间好看了？整个UI占满整个屏幕

编辑代码

我们修改官方的例子，上节课的welcome.blade.php 文件

改为如下，也就是把body标签里面的内容替换成下面，我们这里用到了ThaiWind，这是一个前端的UI库，类似Bootstrap

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>{{ config('app.name', 'Mimi') }} - Built with NativePHP ： welcome to foxdevelop.com</title>

    </head>
    <body>
        <div class="fixed top-0 left-0 w-full bg-red-500">
			顶部导航栏
		</div>
    </body>
</html>
Code language: HTML, XML (xml)

然后保存，打开项目目录，CMD定位到这个目录，然后执行下面命令

php artisan native:jumpCode language: CSS (css)

D:\phpproject\my-app>php artisan native:jumpCode language: CSS (css)

访问：http://127.0.0.1:8000

用web查看看不出效果，下面我们要用真机运行

真机调试

首先，和开发其他android 一样，需要一台手机，android的手机，数据线链接到电脑，然后手机需要开启开发者模式，如果不知道如何开启，可以谷歌搜索一下，不难，并且要安装adb，这是一个谷歌开发的用来电脑操作手机的一个工具，你按照android studio 就可以自带了这个。

安装 Android Studio，完整安装：Android SDK、SDK Platform Tools（自带 ADB 调试工具）

检查一下是否成功按照adb

打开终端，输入：adb devices

D:\phpproject\my-app>adb devices
List of devices attached
a34354354354352    deviceCode language: PHP (php)

我这里有一个手机链接上了。

然后打开项目目录，CMD到这个目录，然后执行如下命令：php artisan native:run android

D:\phpproject\my-app>php artisan native:run android

  Running NativePHP for Android

 Build log: D:\phpproject\my-app\nativephp\android-build.log

  Updating Android configuration ....................................................................... 903.01ms DONE
  Copying Laravel source .................................................................................... 18s DONE
  Installing Composer dependenciesCode language: PowerShell (powershell)

这个过程，会安装一些依赖，例如Kotlin的Composer，gradle等等，所以你的网络环境需要跟上才可以。

如果需要代理，可以配置你的项目中的：D:\phpproject\my-app\nativephp\android\gradle\wrapper\gradle-wrapper.properties

例如替换为镜像地址：

#Mon Feb 10 07:33:27 EST 2025
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
#distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
distributionUrl=https\://mirrors.aliyun.com/maven/gradle/gradle-8.13-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
Code language: Properties (properties)

Previous: resources目录