WordPress 外掛使用者指南
本指南分為四個部分。§1 快速開始 透過截圖帶你完成第一個短代碼的發布,§2–§4 是你在撰寫或排查問題時會反覆查閱的深入參考。
1. 快速開始
在 WordPress 後台打開 3Min API → + New,即可啟動短代碼建立器。依由上到下的四個步驟走完,一個短代碼就完成了。
第一次來?先看看 3Min API 導覽 了解端點和 API key 的發放方式,或者在 ChatGPT Apps 搜尋 "3Min API" 直接用對話開始。
1.1 端點設定 + 測試
- 貼上你的 端點 ID 和 API key,然後選擇 HTTP 方法(Get Record / Get List / POST)。
- 點擊 Test endpoint — 實際的請求會被送出,回應會就地顯示在下方。
- 當回應看起來正常時,接下來的卡片(變數、範本)會自動填入。
POST 端點無法在建立器中預覽。先儲存短代碼,把它放到頁面上,然後送出表單來驗證。
1.2 變數
外掛會讀取你的測試回應,並以標籤形式呈現 可用的範本變數。最常見的幾個:
{{response}}— 完整回應{{response.payload}}— 使用者紀錄的本體{{response.payload.title}}、{{response.id}}— 用「點記號」深入存取
直接把這些變數放進下一步的 HTML/CSS;變數值會自動經過安全處理。
1.3 選擇範本 + 用 AI 設計
- 選擇適合該方法的範本後,HTML/CSS 與 JavaScript 面板會自動填入。
- 上方的 Copy AI prompt 按鈕會把所選範本程式碼、外掛的撰寫規則、以及自動偵測到的變數打包成一段系統提示詞,複製到剪貼簿。
- 把它貼到 ChatGPT / Claude / Gemini,用自然語言來回打磨 — 例如「再極簡一點」、「預設深色模式」、「顯示星等評分」之類。
- 把結果放回 HTML/CSS 面板(必要時也放入 JavaScript 面板),並在右側即時預覽中確認。
JavaScript 面板是選用的。只有網站管理員可以儲存 JavaScript。
1.4 儲存 + 發布
- 輸入 片段名稱(首次儲存後無法變更)。
- 點擊 Save — 建立器會產生下列格式的短代碼:
[3minapi name="your-snippet-name"] - 把這一行貼到任何文章、頁面、小工具或區塊,你的 UI 就會在那裡渲染。
同一個短代碼可以在多個頁面上使用,一個頁面也可以放入多個不同的短代碼 — 它們各自獨立渲染。
2. HTML/CSS 指南
儲存時,為了安全,部分 HTML/CSS 會被自動移除。下面幾節說明儲存後仍會保留的內容,以及如何依這份約定撰寫。
2.1 渲染方式
- Get Record:頁面載入時伺服器呼叫 API,回應被內嵌進 HTML/CSS 一起渲染,之後 JavaScript 才執行。
- Get List:與 Get Record 流程相同。只有第一頁在伺服器渲染 — 後續頁面透過
threeminApi.fetch()(「Load more」按鈕之類)取得。 - POST:表單 HTML/CSS 先渲染;API 呼叫與 JavaScript 處理函式在使用者送出時才執行。(你的 JavaScript 本身在渲染之後立即執行以註冊處理函式 — 送出時才觸發它們。)
- 每個短代碼在渲染時都會被自動包成
<div class="threemin-api-rendered" data-3minapi-preset="<snippet>">…</div>。在 JavaScript 裡用這個屬性來定位根元素 — 不要 自行在 HTML 上加data-3minapi-preset。
2.2 允許的標籤與 CSS
| 類別 | 允許 |
|---|---|
| 文字標籤 | h1–h6、p、div、span、blockquote、ul / ol / li、表格家族、a、img、figure、figcaption |
| 表單標籤 | form、input、button、textarea、select、option、fieldset、legend、label |
| 樣式 | <style> 區塊 |
| CSS | 顏色 / 排版、盒模型、版面(Flexbox + Grid)、動效(transform、transition、animation、filter)、互動(pointer-events、cursor、user-select) |
| 顯示切換 | hidden 屬性、<style> 中帶 display:none 的類別、行內 style="display:none" |
| 儲存時移除 | <script> 標籤、PHP 標籤(<?php、<?=)、行內事件處理器(onclick、onerror、…)、javascript: URL |
部分行內 style 屬性會在儲存時被移除 — 把 CSS 規則放進 <style> 區塊裡。
2.3 推薦寫法
- 語意化 HTML5 — 使用標題層級、清單、表格類標籤呈現表格資料;圖片配說明時使用
figure+figcaption。 - 以片段名為前綴的 BEM 類別 — 例如
.product-card、.product-card__title。同一短代碼在一頁中多次出現也不會衝突。 - 每個片段一個
<style>區塊。 - 現代版面 — Flex / Grid /
gap全部允許。 - 響應式單位 —
rem、%、vw、vh。 - 圖片延遲載入 —
<img loading="lazy">。 - 無障礙 —
aria-label、aria-hidden、role="..."儲存後都仍然生效。 - HTML5 表單驗證 —
required、min、max、pattern、type=email/number/date/…都會直接套用。
2.4 應避免的寫法
- ⚠️ 在表單類標籤上使用自訂
data-3minapi-*(頭號無聲失敗原因 — 連錯誤都不會出現)。 在<button>/<input>/<textarea>/<form>/<select>/<fieldset>加任何不在白名單裡的data-*屬性,儲存時會被默默移除。你的querySelector('[data-...]')會回傳null,監聽器永遠不會綁定,主控台也不會有任何日誌。按鈕、輸入這類互動元素請改用 BEM 類別。<div>/<span>/<li>這類一般標籤接受任何data-*。 - 選擇器必須與 HTML 完全一致 — 一個字元的錯字就會無聲地讓行為失效。
- 使用
<button>而不是<div role="button">。 - 不要用行內
style="..."寫版面 — 把版面規則放進<style>區塊。 - 不要用
id設定樣式 — 同一短代碼在一頁中出現兩次時 ID 會衝突。請用類別。 - 最上層容器不要寫死
px寬度 — 響應式版面會被破壞。
2.5 各方法的寫法提示
2.5.1 Get Record — 把 API 欄位接進 HTML
- 執行 Test endpoint 之後,Variables 卡片會顯示兩個標籤:
{{response}}(完整回應)與{{response.payload}}(使用者紀錄)。 - 用點記號存取巢狀欄位:
{{response.payload.title}}、{{response.id}}、{{response.payload.author.name}}。 - 變數值會自動經過安全處理。
- 檢視/編輯切換屬性(表單類標籤的白名單):
data-3minapi-view-mode、data-3minapi-edit-mode、data-3minapi-edit-toggle、data-3minapi-save、data-3minapi-cancel、data-3minapi-delete。編輯表單裡的 input 用一般的name="..."。
2.5.2 Get List — 動態渲染項目
- HTML 裡只放一個空容器 — JavaScript 在執行時逐列加入。寫死的列在發布頁面上會重複出現。
- 白名單 DOM hook:
<ul data-3minapi-feed-list>(項目容器)、<button data-3minapi-feed-more>(Load more)、[data-3minapi-feed-empty](空狀態)。 - 變數標籤:
{{response.data}}(陣列 — 在範本中會被替換為空,僅供參考)、{{response.pagination.next_cursor}}、{{response.data.0.payload.x}}(以索引存取單筆紀錄,適用於靜態顯示區域)。 - 多列渲染與分頁放進 JS 面板。
2.5.3 POST — 把表單接到你的端點
- 在 3Min API 後台查看你端點的 body 欄位定義。
- 讓每個 input 的
name屬性與 body 欄位名稱完全一致。 - 自動送出綁定:把
<form data-3minapi-form>放進[data-3minapi-preset]內,執行時會攔截 submit 事件。內建 POST 範本已經包含這部分。 - 自動狀態回饋:在表單裡放一個
<div data-3minapi-status></div>。執行時會寫入textContent並切換is-success/is-error類別。 - HTML5 驗證屬性(
required、min、max、pattern、type=email/number/date/…)都直接套用 — 不需 JS 的輕量驗證。 - 自訂驗證、條件送出或生命週期 hook,放進 JavaScript 面板。
3. JavaScript 指南
JavaScript 面板是選用的,只有網站管理員可以儲存。貼到這裡的程式碼會在短代碼的 HTML/CSS 渲染完成之後自動執行。
3.1 執行方式
- 執行時會把你的程式碼自動包成
(function(scope){ /* your code */ })('<snippet>')。不需要<script>標籤、import 或 IIFE 包裝。 scope變數會自動注入 — 直接使用即可。不要把片段名稱當字串字面值硬編碼 在程式碼裡。- 如果同一短代碼在一頁中渲染多次,每個實例都以各自的 scope 獨立執行。
- 所有 helper 都掛在
window.threeminApi.*上。準確的回應欄位路徑與完整範例程式碼,請看 Copy AI prompt 輸出中的[Sample —]區塊。
3.2 執行環境
- 一般的瀏覽器 JavaScript(ES2017+) —
async/await、fetch、Promise、箭頭函式、解構都可以用。 - 直接使用 DOM API —
document.querySelector、addEventListener、createElement等等。 - 片段內部不能用
import。外部函式庫透過佈景主題/外掛裡的wp_enqueue_script載入,再以全域變數(window.X)的方式存取。 - 只有網站管理員可以儲存 JavaScript。HTML/CSS 等其他欄位非管理員使用者也可以儲存。
3.3 Helper 一覽
| Helper | 模式 | 作用 |
|---|---|---|
data(scope) |
All | 解析內嵌回應(無網路請求)。缺失時回傳 null。 |
fetch(scope, q) |
Get List | 透過伺服器代理取得下一頁。{ cursor: <next_cursor> }。 |
fetchById(scope, id) |
Get List | 依 id GET 單筆紀錄。 |
submit(scope, body) |
POST | 存在 <form data-3minapi-form> 時自動綁定 — 很少需要手動呼叫。 |
update(scope, body) |
Get Record | PUT 短代碼所指向的紀錄。 |
updateById(scope, id, body) |
Get List | 依 id PUT 單筆紀錄。 |
delete(scope) |
Get Record | DELETE 短代碼所指向的紀錄。 |
deleteById(scope, id) |
Get List | 依 id DELETE 單筆紀錄。 |
on(scope, event, cb) |
POST | 註冊 'before-submit' / 'success' / 'error' hook。 |
mutation 只回傳佇列確認回應,不會回傳更新後的紀錄。
update/delete/updateById/deleteById的回應只包含success、message、id(佇列任務 id,不是 紀錄 id)和queued_at。用你剛送出的 body 樂觀地更新 DOM。實際的紀錄寫入相較於下一次 GET 可能延遲約 3 秒。
3.4 推薦 / 應避免
推薦
- 只查找一次 root —
var root = document.querySelector('[data-3minapi-preset="' + scope + '"]');,之後所有選擇器都透過root.querySelector(...)限定範圍。即使同一短代碼渲染多次也安全。 - 事件委派 — 對於動態加入的列,在容器上掛一個監聽器,透過
e.target.closest('.…')識別列。 - 用 dataset 標識每列 —
li.dataset.recordId = item.id標記一次,處理函式中讀取e.target.closest('li').dataset.recordId。 - 讀取使用快取 —
threeminApi.data(scope)只解析內嵌 JSON,所以反覆呼叫沒有效能負擔。 - mutation 回應是確認回應 —
update/delete只回傳佇列確認回應,所以用你送出的 body 來更新 DOM(樂觀 UI)。
應避免
- ⚠️ 用
scope+record_id拼接元素 id — 片段名稱與上游紀錄 id 是完全不同的字串。 - ⚠️ mutation 回應的 wrap 深度弄錯 — success 在
res.json.data.data.success。讀res.json.data.success(少一個.data)永遠是 falsy → HTTP 200 會被路由到錯誤處理路徑,這是最常見的陷阱。 - 試圖從 mutation 回應中讀取更新後的紀錄 — 佇列確認回應中沒有紀錄內容。
- mutation 之後立即重新查詢 — 非同步處理可能延遲約 3 秒。用
setTimeout(..., 3000)配合 "Saving…" 指示器。 - 把 mutation 的 body 包成
{ payload: { ... } }— body 是一層物件{ field: value }形式。巢狀物件在 URL 編碼過程中會無聲消失。 - 自行合成
record_id— 必須符合[A-Za-z0-9_-]、≤256 字元。違反時伺服器回傳 422 錯誤。請直接沿用 API 在上一次回應中回傳的 id。 - 把片段名稱當字串字面值硬編碼 — 使用自動注入的
scope變數。
3.5 回應的 wrap 深度 — 常見陷阱
WordPress 的 wp_send_json_success 包一層,外掛的 admin-ajax 處理器再包一層。結果是:
- 頁內單筆 GET 讀取(
data(scope))—data(scope).data.payload.X。 fetch()下一頁 — 完整回應在res.json.data.data(兩個.data)。fetchById()單筆紀錄 — 紀錄在res.json.data.data.data(三個.data)。- mutation 佇列確認回應 —
res.json.data.data.{success, message, id, queued_at}(兩個.data)。 - POST
'success'hook 事件 —e.response.data.data.{success, …}(兩個.data)。
完整的簽章與經過驗證的範例程式碼,請看 Copy AI prompt 輸出中的 [Sample —] 區塊。
4. 常見問題
4.1 「按鈕點擊沒反應,而且主控台也沒有錯誤」
你在表單類標籤(<button>、<input>、<form>、<select>、<fieldset>)上加了 data-* 屬性。WordPress 的安全過濾器(wp_kses)在儲存時把它移除了,所以 querySelector('[data-...]') 回傳 null,監聽器永遠不會綁定,主控台也沒有日誌。
解決 — 把那個元素換成 BEM 類別(<button class="my-card__back">),用 root.querySelector('.my-card__back') 來找它。
4.2 「卡片是空的,或是欄位顯示為 undefined」
你讀取回應的路徑錯了。每個 helper 的準確路徑都在 AI prompt 的 [Sample —] 區塊裡有文件。常見的正確答案:
data(scope).data.payload.X— 單筆 GET。res.json.data.data.data.payload.X—fetchById(包了三層)。
4.3 「Update 回傳了 HTTP 200,但畫面沒變」
你在檢查 res.json.data.success。這個路徑少了一個 .data,對 mutation 來說永遠是 undefined。mutation 的 success 旗標在 res.json.data.data.success(WP 包一次,外掛包一次)。delete / updateById / deleteById 也是相同。POST 'success' hook 對應的路徑是 e.response.data.data.success。
4.4 「清單渲染為空,但 API 回傳 200」
你的 DOM hook 選擇器與 HTML 不完全一致。重新檢查 HTML,確認 data-3minapi-feed-list(或你自訂的 hook)逐字出現。
4.5 「儲存後 CSS 規則沒套用」
要麼這條規則是行內的、被安全過濾器移除了;要麼這個屬性不在安全 CSS 清單上。把它移到 <style> 區塊裡。
4.6 「POST 送出正常,但是看不到回饋」
你的表單裡沒有 <div data-3minapi-status></div>。執行時只會在這個元素上寫 textContent 並切換 is-success / is-error 類別。
4.7 「Update 成功了,但是 UI 上還顯示舊值」
你在嘗試從 mutation 回應中讀取更新後的紀錄。mutation 只回傳佇列確認回應 — 沒有紀錄內容。直接用你剛送出的 body 來更新 DOM。
4.8 「mutation 之後就算重新整理頁面,結果仍是舊資料」
mutation 是非同步處理的,下一次讀取可能延遲約 3 秒。請使用樂觀 UI。如果一定要重新拉取,用 setTimeout(..., 3000) 搭配 "Saving…" 指示器。
4.9 「JS 面板被停用,並顯示一段提示」
你的帳號沒有儲存 JavaScript 的權限(在多站點或受限角色下很常見)。請在不帶 JavaScript 的情況下儲存,或請網站管理員儲存 JavaScript 部分。
4.10 「Test endpoint 回傳網路錯誤」
請在你的 3Min API 後台檢查端點 ID 與 API key。
哪裡可以取得協助
- 體驗 3Min API — 3minapi.com/tour
- 直接聯絡 — contact@3minapi.com
- WordPress.org 支援論壇 — 在外掛正式公開之後,可在目錄頁面的 Support 分頁查看。