WordPress 插件用户指南

本指南分为四个部分。§1 快速开始 通过截图带你完成第一个短代码的发布,§2–§4 是你在编写或排查问题时会反复查阅的深入参考。

---

1. 快速开始

在 WordPress 后台打开 3Min API → + New,即可启动短代码构建器。按从上到下的四个步骤走完,一个短代码就完成了。

第一次来?先看一下 3Min API 介绍 了解端点和 API key 的发放方式,或者在 ChatGPT Apps 搜索 "3Min API" 直接通过对话开始。

1.1 端点设置 + 测试

1. 粘贴你的 端点 ID 和 API key,然后选择 HTTP 方法(Get Record / Get List / POST)。
2. 点击 Test endpoint — 真正的请求会被发出,响应会就地显示在下方。
3. 当响应看起来正常时,下面的卡片(变量、模板)会自动填充。

POST 端点无法在构建器中预览。先保存短代码,把它放到页面上,然后提交表单进行验证。

1.2 变量

插件会读取你的测试响应,并以芯片形式展示 可用的模板变量。最常见的几个:

• {{response}} — 完整响应
• {{response.payload}} — 用户记录的主体
• {{response.payload.title}}、{{response.id}} — 用"点表示法"深入访问

直接把这些变量放进下一步的 HTML/CSS;变量值会自动经过安全处理。

1.3 选择模板 + 用 AI 设计

1. 选择适合该方法的模板后,HTML/CSS 与 JavaScript 面板会自动填充。
2. 顶部的 Copy AI prompt 按钮把所选模板代码、插件的编写规则、以及自动识别的变量打包成一段系统提示词,复制到剪贴板。
3. 把它粘贴到 ChatGPT / Claude / Gemini 里,用自然语言来回打磨 — 比如"更简约一些"、"默认深色模式"、"显示星级评分"等等。
4. 把结果放回 HTML/CSS 面板(必要时也放入 JavaScript 面板),并在右侧实时预览中确认。

JavaScript 面板是可选的。只有站点管理员可以保存 JavaScript。

1.4 保存 + 发布

1. 输入 片段名称(首次保存后不可更改)。
2. 点击 Save — 构建器生成下列格式的短代码:

   [3minapi name="your-snippet-name"]
   

3. 把这一行粘贴到任意文章、页面、小工具或区块,你的 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 标签页查看。