ThinkPHP Mobile (TPM) 完整使用指南：從環境搭建到 Hybrid App 打包

前言：為什麼選擇 TPM？

在移動互聯網時代，企業往往面臨多端開發的困境：WebApp 雖然跨平台、開發成本低，但無法調用手機原生功能（如攝像頭、通訊錄），且靜態資源需從服務器下載，消耗用戶流量；NativeApp 體驗最好、可調用原生 API，但需為 iOS (Objective-C/Swift)、Android (Java/Kotlin)、Windows Phone (C#) 分別開發，成本極高；HybridApp 則結合了兩者優勢——使用 HTML、CSS、JS 開發，一次編寫、多端運行，經打包後安裝於手機，可調用原生功能，靜態資源本地存儲。

ThinkPHP 的模板本身就是基於 HTML/CSS/JS 構建，ThinkPHP Mobile (TPM) 應運而生：它能將 ThinkPHP 模板直接打包為 Hybrid App，讓開發者以「開發網站」的方式同步產出電腦站、手機站與手機 App，大幅降低維護成本。

核心架構差異：傳統 Hybrid vs TPM

傳統 Hybrid App 開發仍需編寫後端接口、前端 AJAX 請求邏輯。TPM 則採用「約定優於配置」機制：

• 開發者照常在 Action 中賦值模板變量，在模板中輸出。
• 打包為 App 後，TPM 運行時會自動請求對應 Action，Action 自動返回 JSON 格式數據。
• 前端由 TPM.js 解析模板標籤並渲染頁面，無需手寫接口調用代碼。

響應式設計基礎

移動設備尺寸碎片化嚴重，界面必須採用響應式佈局。建議熟悉媒體查詢、流式佈局、rem/vw 單位等技術，或引入 Bootstrap、PureCSS 等成熟 UI 框架以加速開發。參考閱讀：《移動端 WebApp 開發必備知識》。

環境搭建步驟

1. 獲取 TPM 擴展

從 ThinkPHP 官網或 GitHub 下載：
https://github.com/liu21st/extend/tree/master/Extend/Tool/TPM

將文件部署至項目：

• Tpl/ 目錄下文件 → 項目 Tpl/
• SwitchMobileTplBehavior.class.php → Lib/Behavior/
• TemplateMobile.class.php → ThinkPHP/Extend/Driver/Template/

2. 啟用 Layout 與行為綁定

在項目配置文件開啟 Layout：

'LAYOUT_ON' => true

在 Conf/tags.php 註冊行為：

<?php return array('action_begin' => array('SwitchMobileTpl'));

3. 修改核心 redirect 函數以支持 App 端跳轉

編輯 ThinkPHP/Common/functions.php，替換 redirect 函數（見原文完整代碼）。關鍵點：當常量 IS_CLIENT 為真時，發送 header('redirect:'.$url) 而非 Location，以便 App 端攔截跳轉。

4. 配置入口文件地址

編輯 Tpl/index.html，修改 TPM.run() 參數為項目真實訪問地址：

TPM.run("https://your-project-url");

5. 打包生成 App

命令行進入模板目錄執行：

php build.php

需開啟 PHP zip 和 curl 擴展，且需聯網。生成的安裝包位於模板目錄，可直接安裝測試。
支持參數：php build.php <platform> <name> <package> <version>
platform：android/ios（目前僅支持 android）
name：應用名稱（默認 TPM）
package：包名（默認 cn.thinkphp.tpm）
version：版本號（默認 1.0）

運行原理解析

瀏覽器訪問時使用 Tpl/layout.html；App 運行時使用 Tpl/index.html 作為 Layout，並加載 TPM.js。
TPM.js 負責：

1. 解析 ThinkPHP 模板標籤（純 JS 實現，無 PHP 環境）。
2. 自動請求 Action 接口獲取 JSON 數據。
3. 將渲染結果注入 id="main" 容器。
4. 請求期間顯示 class="ajax_wait" 加載提示層。

模板中必須包含：

<div id="main"></div> <div class="ajax_wait">正在加載中...</div>

模板標籤支持與限制

支持的標籤

volist, foreach, for, empty, notempty, present, notpresent, eq, neq, heq, nheq, egt, gt, elt, lt, if, elseif, else, switch, case, default, in, notin, between, notbetween, include

注意事項

• 不能使用 PHP 函數，故 U() 等函數不可用。
• include 標籤的 file 屬性必須寫全「控制器:方法」，不可省略。
• 未實現：defined、define 等標籤。
• 未實現模板替換變量：__URL__、__PUBLIC__、__ROOT__、__SELF__。
• URL 必須寫固定路徑，以「/」開頭，格式：/Action/method。

獨立手機 App 模板目錄

若需網站模板與 App 模板分離，配置：

'TPM_THEME' => 'mobile'

並在 Tpl/ 下建立 mobile/ 目錄存放 App 專用模板。
瀏覽器訪問渲染 Tpl/Index/index.html，App 打開渲染 Tpl/mobile/Index/index.html。

TPM.run 配置詳解

TPM.run(config) 接收對象參數，主要配置項：

配置示例

入口地址 https://www.xxx.com/index.php，首頁改為登錄頁 /Index/login：

TPM.run({ api_base: 'https://www.xxx.com/index.php', api_index: '/Index/login' });

若已隱藏入口文件：

TPM.run({ api_base: 'https://www.xxx.com', api_index: '/Index/login' });

僅配置 api_base 時可簡寫：

TPM.run('https://www.xxx.com');

元素事件監聽：TPM.ready

App 界面由接口渲染後動態插入 #main，傳統 $(document).ready() 無法監聽新生元素。請使用 TPM.ready：

<script>
TPM.ready(function($){
    $('#id').click(function(){ alert('click'); });
});
</script>

回調函數接收 jQuery 實例 $，確保在模板渲染完成後綁定事件。

總結與拓展

TPM 讓 ThinkPHP 開發者以極低成本擁有原生 App 能力。除核心功能外，還支持對接現有接口、提供插件擴展常用功能。掌握響應式設計、模板標籤限制、TPM.ready 事件機制，即可高效構建高質量 Hybrid App。