ThinkPHP 整合百度 UEditor 富文本編輯器完整教程 (配置、上傳、儲存、顯示)

ThinkPHP 3.x 整合 UEditor 富文本編輯器完整指南

UEditor (百度 Web 前端研發部出品) 功能豐富、UI 現代、支援圖片/視頻/附件上傳、代碼高亮、公式編輯。本文詳述在 ThinkPHP 3.x 專案中**下載部署、前端引入、後端配置路徑、表單提交、資料庫儲存、前端安全輸出**的全流程。

一、目錄部署

1. 將 UEditor 完整資料夾放入專案公開目錄：Public/ueditor/ (ThinkPHP 模板中可用 __PUBLIC__/ueditor/ 訪問)。
2. 確認結構：
   Public/ueditor/ueditor.config.js
Public/ueditor/ueditor.all.js (或 ueditor.parse.js 僅解析模式)
   Public/ueditor/themes/default/ueditor.css
Public/ueditor/php/ (後端上傳處理核心)

二、前端模板引入

<!-- 在需要編輯器的模板頁面 (如 Create/Edit) -->
<script type="text/javascript" src="__PUBLIC__/ueditor/ueditor.config.js"></script>
<script type="text/javascript" src="__PUBLIC__/ueditor/ueditor.all.js"></script>
<link rel="stylesheet" href="__PUBLIC__/ueditor/themes/default/ueditor.css" />

三、關鍵配置：UEditor 服務器端路徑 (絕對 URL)

編輯 Public/ueditor/ueditor.config.js，找到 URL 變數定義處，**強烈建議使用絕對路徑** (含協議、域名、端口)，避免不同控制器層級導致相對路徑錯誤。

// 原代碼 (自動偵測，易出錯)
URL = tmp.substr(0, tmp.lastIndexOf("/")+1).replace("_examples/", "");

// 改為絕對路徑 (請替換為你的實際域名)
URL = "https://yourdomain.com/Public/ueditor/";

若本地開發用 https://localhost:8080/Public/ueditor/，部署時統一修改此處或改用 JS 動態賦值 window.UEDITOR_HOME_URL。

四、表單頁面實例化編輯器

<form action="__URL__/insert" method="post">
    <!-- 編輯器容器 (type=text/plain 關鍵，防止表單提交雙份內容) -->
    <script type="text/plain" id="myEditor" name="content"></script>

    <input type="submit" value="發布" />
</form>

<script type="text/javascript">
var ue = UE.getEditor('myEditor', {
    toolbars: [[
        'source', '|', 'undo', 'redo', '|',
        'bold', 'italic', 'underline', 'strikethrough', '|',
        'forecolor', 'backcolor', '|',
        'fontfamily', 'fontsize', '|',
        'justifyleft', 'justifycenter', 'justifyright', '|',
        'insertorderedlist', 'insertunorderedlist', '|',
        'link', 'unlink', '|',
        'image', 'video', 'attachment', 'map', '|',
        'emotion', 'scrawl', 'insertcode', '|',
        'fullscreen', 'preview'
    ]],
    initialFrameHeight: 300,
    initialContent: '<p>請輸入內容...</p>',
    autoFloatEnabled: false, // 工具欄固定
    // 重要：指定表單提交時的字段名 (對應 name="content")
    textarea: 'content'
});
</script>

五、後端控制器接收與安全處理

public function insert() {
    if (!IS_POST) $this->error('非法請求');

    // 1. 獲取原始內容 (UEditor 會自動將內容塞入 name="content" 的隱藏 textarea)
    $rawContent = I('post.content'); // ThinkPHP I() 方法自動處理魔術引號等

    // 2. 安全過濾 (防 XSS) —— 推薦使用 HTMLPurifier
    // vendor('htmlpurifier.HTMLPurifier'); // 需 composer require ezyang/htmlpurifier
    // $purifier = new HTMLPurifier();
    // $cleanContent = $purifier->purify($rawContent);

    // 簡易方案 (僅示範，生產環境請用 Purifier)
    $cleanContent = htmlspecialchars(stripslashes($rawContent), ENT_QUOTES, 'UTF-8');

    // 3. 寫入資料庫
    $Article = M('Article');
    $data = [
        'title'   => I('post.title'),
        'content' => $cleanContent,
        'ctime'   => time(),
    ];
    if ($Article->add($data)) {
        $this->success('發布成功', U('index'));
    } else {
        $this->error('發布失敗');
    }
}

六、前端列表/詳情頁安全輸出

資料庫儲存的是**已轉義的 HTML 實體** (如 <p> → <p>)，直接輸出會顯示標籤而非渲染。需在模板中解碼：

<!-- ThinkPHP 模板標籤 volist 遍歷 -->
<volist name="list" id="vo">
    <div class="article-content">
        <!-- 使用模板修飾符 |htmlspecialchars_decode 解碼 -->
        {$vo.content|htmlspecialchars_decode}
    </div>
</volist>

原理：htmlspecialchars_decode 將 < → <，瀏覽器隨後渲染為豐富內容。等效 PHP：htmlspecialchars_decode($vo['content'])。

七、圖片/檔案上傳配置 (關鍵)

UEditor 上傳請求會發往 URL + "php/controller.php"，需確保：

1. Public/ueditor/php/config.json 中 imagePathFormat, filePathFormat 等路徑指向可寫目錄 (如 /Public/Uploads/ueditor/{yyyy}{mm}{dd}/{time}{rand:6})。
2. 該目錄 **Web 可訪問** (Nginx/Apache 無 deny 規則) 且 **PHP 可寫** (權限 755/775、擁有者 www-data)。
3. 上傳後返回 JSON 格式：{"state":"SUCCESS","url":"/Public/Uploads/...","title":"...","original":"..."}。

八、常見問題排查

九、總結

ThinkPHP + UEditor 整合核心在於：**絕對路徑配置 URL、表單 name 對應 textarea 參數、後端 Purifier 過濾入庫、前端 htmlspecialchars_decode 輸出、上傳目錄權限與 Web 可訪問**。完成這五點，即可獲得生產級富文本編輯體驗。