您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

ThinkPHP 動態頁面片段渲染：Widget 進階實戰與最佳實踐

編輯：PHP 綜合知識

前言

傳統 <include> 只能靜態包含模板片段，無法處理「導航菜單需查詢資料庫並根據權限動態生成」此類業務邏輯。ThinkPHP 的 Widget (小工具) 機制正是為此設計：封裝「數據獲取 + 模板渲染」為可復用組件，支援參數傳遞、緩存、獨立控制器邏輯。本文從基礎到進階，展示 Widget 完整應用模式。

一、Widget 核心概念

定義位置：Application/Widget/ 目錄下 (ThinkPHP 3.x) 或 app/widget/ (5.x/6.x)。
類命名：{Name}Widget 繼承 Widget 基類 (或 Controller)，方法對應渲染動作。
模板位置：Widget/{Name}/ 目錄下的 .html 檔案。
調用方式：模板中使用 {:W('WidgetName/action', params)} 或 {:R('WidgetName/action', params, 'Widget')}。

二、基礎範例：動態分類導航

1. 定義 Widget 控制器

<?php
// Application/Widget/CateWidget.class.php
namespace Widget;
use Think\Controller;

class CateWidget extends Controller {
    public function menu($limit = 10, $cacheTime = 300) {
        // 1. 嘗試讀取緩存
        $cacheKey = "cate_menu_{$limit}";
        $menu = S($cacheKey);
        
        if ($menu === false) {
            // 2. 緩存未命中，查詢數據庫
            $menu = M('Category')
                ->where(['status' => 1, 'is_nav' => 1])
                ->order('sort ASC')
                ->limit($limit)
                ->select();
            // 3. 寫入緩存
            S($cacheKey, $menu, $cacheTime);
        }
        
        // 4. 分配變量並渲染專屬模板
        $this->assign('menuList', $menu);
        $this->display('Cate:menu'); // 渲染 Widget/Cate/menu.html
    }
}

2. Widget 模板

<!-- Widget/Cate/menu.html -->
<ul class="nav navbar-nav">
    <volist name="menuList" id="vo">
        <li><a href="<?php echo U('Category/index', ['id'=>$vo['id']]); ?>"><?php echo $vo['title']; ?></a></li>
    </volist>
</ul>

3. 主模板調用

<!-- Tpl/Home/Index/index.html -->
<div class="header-nav">
    {:W('Cate/menu', array(15, 600))}
</div>

三、進階模式

1. 直接輸出模式 (無模板文件)

<?php
class StatsWidget extends Controller {
    public function onlineCount() {
        $count = M('Session')->where(['expire' => ['GT', time()]])->count();
        echo "<span class='badge'>在線: {$count} 人</span>";
    }
}

模板調用需用 {~W('Stats/onlineCount')} (~ 表示直接輸出不捕獲緩衝區)。

2. 參數化與預設值

public function tagCloud($limit = 20, $order = 'count DESC', $template = 'tag_cloud') {
    $tags = M('Tag')->order($order)->limit($limit)->select();
    $this->assign('tags', $tags);
    $this->display("Tag:{$template}");
}

調用：{:W('Tag/tagCloud', ['limit'=>30, 'order'=>'rand()'])}

3. 控制器中渲染 Widget (AJAX 片段更新)

<?php
class IndexController extends Controller {
    public function loadNav() {
        // 直接返回 Widget 渲染的 HTML 片段
        $html = R('Cate/menu', [], 'Widget'); // R 返回字串
        $this->ajaxReturn(['html' => $html, 'time' => time()]);
    }
}

4. Widget 緩存策略

public function hotProducts($cacheKey = 'hot_products', $expire = 1800) {
    // 使用 ThinkPHP 內建 S() 函數 (支援 File/Redis/Memcache)
    $data = S($cacheKey);
    if (!$data) {
        $data = M('Product')->where(['is_hot'=>1, 'status'=>1])
            ->field('id,name,price,thumb')
            ->limit(8)->select();
        S($cacheKey, $data, $expire);
    }
    $this->assign('products', $data);
    $this->display('Product:hot');
}

四、Widget vs R() vs include 對比

特性	Widget (W/R)	R() 方法調用	<include>
業務邏輯	獨立控制器類	任意控制器方法	無 (純模板)
數據查詢	內建	內建	需控制器預先賦值
參數傳遞	陣列/字串	陣列/字串	模板變量
獨立模板	是 (Widget/目錄)	共用模板目錄	同級或絕對路徑
緩存整合	原生支援 S()	手動處理	無
適用場景	高復用、有邏輯、跨頁面組件	控制器複用、AJAX 片段	靜態佈局片段 (header/footer)

五、常見坑與避坑指南

命名空間衝突：ThinkPHP 3.x Widget 類不支援命名空間，5.x+ 建議使用 app\widget 命名空間並配置自動載入。
模板路徑解析：$this->display('Cate:menu') 會尋找 Widget/Cate/menu.html，注意大小寫敏感 (Linux 環境)。
遞歸調用死循環：Widget 模板中調用同一 Widget 會導致無限遞歸，需在邏輯層防禦。
變量作用域隔離：Widget 內 $this->assign() 的變量不會污染主模板，反之亦然。
效能監控：開啟 SHOW_PAGE_TRACE 觀察 Widget 渲染耗時，超過 50ms 建議加緩存或異步載入。