頁面視圖 WebView - NativePHP 教學

上一堂課我們認識了頁面UI的對應位置，這堂課接續往下學習。

認識單一原生網頁檢視元件（WebView）

所有以 NativePHP 開發的行動裝置App，皆以單一原生網頁檢視元件（WebView）作為核心載體。透過網頁檢視元件，你能使用任何熟悉的前端網頁技術建構應用介面（UI）；因為本質上它就是內嵌瀏覽器，負責渲染所有網頁內容。

WebView 預設會填滿整個螢幕可視範圍；但若開啟相機等功能時，相機操作畫面會暫時覆蓋 WebView。

NativePHP 的核心架構：PHP 後端 + 任意前端技術混合開發（Vue、jQuery、Tailwind 等）

WebView 永遠置頂顯示，僅相機、內建瀏覽器等全螢幕場景會遮蓋它，我們看見的所有介面UI都由 WebView 負責呈現。

NativePHP 行動版底層核心：單一 WebView 容器，不具原生多頁面分層機制；也就是 NativePHP 自始至終只存在單一個頁面，頁面跳轉、返回動作全都在同一個 WebView 內完成。

NativePHP 行動App全程只會存在唯一一個原生 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 或 Blade PHP 頁面內加入這組 meta 標籤。現今多數網站都會配置這段語法，目的是讓網頁完美適配行動裝置瀏覽器；若缺少這組設定，頁面文字會顯得細小模糊。主因是手機螢幕 DPI 解析度極高，未做行動適配時頁面會以電腦版瀏覽器規格渲染，造成字體過細、排版混亂等狀況。

各位可隨意開啟網站示範，以 NativePHP 官方文件頁面為例：Web View – NativePHP mobile v3 – NativePHP，於瀏覽器右鍵檢視網頁原始碼即可看見該標籤。

這組設定包含兩個核心屬性：

width=device-width：頁面寬度等同裝置實體螢幕寬度

initial-scale=1：頁面初始縮放比例為1:1，不自動放大或縮小

2 停用雙指縮放（模擬原生App操作體感）

原生 Android、iOS App 預設無法透過雙指張開/收合放大縮小頁面，但一般行動瀏覽器允許此操作。若要讓 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」CSS樣式，請繼續往下閱讀。

安全區 Safe Areas

安全區定義為螢幕不會被遮擋的可視範圍：不會被硬體結構（螢幕圓角、前置鏡頭瀏海、動態島）、系統常駐介面（底部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 根容器標籤加上此類別，自動將內容限制在安全區範圍內，大幅簡化開發流程，參考上方範例程式碼。

我們透過範例對照差異，先以官方示範理解原理，後續再使用實機測試。首先示範未做安全區適配的狀況：

<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)

介面立刻完整填滿螢幕，美觀度大幅提升。

程式碼修改實作

接著修改上一堂課使用的範例檔案 welcome.blade.php

替換 body 內完整內容，範例使用 Tailwind 前端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)

儲存檔案後，開啟命令提示字元切換至專案根目錄，執行下方指令：

php artisan native:jumpCode language: CSS (css)

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

開發預覽網址：http://127.0.0.1:8000

僅透過電腦瀏覽器無法觀察行動裝置適配效果，必須使用實機執行測試。

實機偵錯流程

開發 Android App 流程相同：準備一台 Android 手機、透過傳輸線連接電腦，手機需開啟開發者模式；若不清楚開啟方式可上網查詢，步驟簡單。另外需安裝 ADB 工具，此為 Google 提供、電腦遠端操作手機的工具，安裝 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 執行以下指令編譯並安裝Android App：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、Gradle 等，因此需確保網路連線穩定。

若網路需透過代理，可修改專案內設定檔路徑：D:\phpproject\my-app\nativephp\android\gradle\wrapper\gradle-wrapper.properties

將 Gradle 下載位址替換為國內鏡像站台，範例如下：

#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 資料夾