在 Plasmic 中集成 WordPress：使用 @plasmicpkgs/plasmic-wordpress 拉取并渲染文章与页面

• 低代码
• 前端
• 后端

本指南围绕仓库中 plasmicpkgs/plasmic-wordpress/README.md 所述主题展开：如何把 WordPress REST API 作为 Plasmic 可视化的数据源，在无代码/低代码画布中拉取文章与页面并渲染为可复用组件。读完本文，你将掌握WordpressProvider、WordpressFetcher、WordpressField三个核心组件的配置方法，理解底层 REST 查询与筛选原理，并能在自己的 Plasmic 应用中直接注册和调用这些组件。

一、包定位：为 WordPress REST API 而生的 Plasmic 组件集

@plasmicpkgs/plasmic-wordpress是一个专注于 WordPress REST API 的 Plasmic 代码组件包。它的 README 用一句话概括了全部职责："Plasmic components and registration calls for Wordpress REST API"——即既提供可视化组件，也提供把组件注册进 Plasmic 画布的注册调用。

整个包只包含一个核心源文件 src/wordpress.tsx，向画布暴露了三个可拖拽单元：

此外，src/index.tsx 导出一个registerAll(loader?)入口，用于一次性完成全部注册。该包通过@plasmicapp/host的registerComponent与registerGlobalContext与 Plasmic 画布交互，这是所有 Plasmic 代码组件的标准接入方式。registerAll接受一个可选 loader 参数（包含registerComponent和registerGlobalContext两个函数），传入时改用 loader 注册，否则回退到直接注册——这一设计让同一套注册代码可以同时服务于普通项目与 Plasmic 自定义 loader 场景。

包的依赖关系也很精简，见 package.json：运行时依赖仅有dlv（用于深层对象取值），peer 依赖为@plasmicapp/host >= 1.0.0、@plasmicapp/query >= 0.1.0、react >= 16。数据查询能力实际上来自姊妹包@plasmicpkgs/wordpress的_queryWordpress函数。

二、WordpressProvider：配置站点地址的全局上下文

WordpressProvider是 Global Context 组件，作用是向整棵组件树注入 WordPress 站点地址。其唯一属性wordpressUrl在 WordpressProviderMeta 中定义：

• 类型：string
• 显示名：Wordpress URL
• 默认值：https://techcrunch.com/

实现上，它只是通过 React Context（CredentialsContext）向下传递{ wordpressUrl }。WordpressFetcher在挂载时通过ensure(useContext(CredentialsContext), "WordpressFetcher must be used within a WordpressProvider")强校验该上下文存在，一旦缺失会直接抛错。因此，任何使用WordpressFetcher的页面都必须在组件树上层放置一个WordpressProvider。

需要说明的是，WordPress REST API 默认开放于/wp-json/wp/v2/路径，并不需要认证即可读取已发布内容，因此这里只需填站点根地址（如https://example.com），无需任何密钥。

三、WordpressFetcher：数据拉取与自动重复渲染

WordpressFetcher是包的核心。它在 WordpressFetcherMeta 中声明了providesData: true，声明自己向画布提供数据；默认样式为单列网格（display: grid; grid-template-columns: 1fr; grid-row-gap: 8px; padding: 8px），默认子内容是一个WordpressField。

3.1 核心属性

queryOperator的可选值定义在 utils.ts：

• search—— 关键词搜索
• slug—— 按 Slug 精确过滤
• author—— 按作者过滤

3.2 渲染逻辑与数据上下文

WordpressFetcher的渲染流程（wordpress.tsx 渲染段）包含多层防御性提示：

• 未选择queryType→ 渲染 "Please specify query type"
• 有 operator 无 value → "Please specify Filter Value"
• 有 value 无 operator → "Please specify Query Operator"
• 筛选结果为空 → "No published posts/pages found"

当数据正常返回时：

• 默认情况下，它会用data.items.map(...)为每条记录包一层DataProvider，并通过repeatedElement(i, children)重复渲染子节点，同时把当前记录注入到名为currentWordpressPost（对应posts）或currentWordpressPage（对应pages）的 Plasmic 数据上下文中；
• 全部条目数组还会被注入到名为wordpressItems的数据上下文中；
• noAutoRepeat: true时只渲染一次 children，不再逐条重复；
• noLayout: false时渲染为<div className={className}>包裹，noLayout: true时以 Fragment 形式直接输出，交由父容器布局。

3.3 查询的缓存键

组件通过usePlasmicQueryData发起查询，缓存键为{ queryOperator, filterValue, limit, queryType, wordpressUrl }的 JSON 序列化结果（缓存键构造）。这意味着任何筛选参数变化都会触发新的请求，而相同参数组合则会命中 Plasmic 查询缓存，避免重复请求。

四、WordpressField：按字段渲染单条记录

WordpressField负责在WordpressFetcher内部把当前记录中的某个字段渲染为 DOM。其field属性是一个 choice 控件，预置了 WordPress 文章/页面对象上最常见的字段：

title、slug、content、excerpt、date、modified、link、status

取值时，它通过useSelector("currentWordpressPost")/useSelector("currentWordpressPage")读取上下文（WordpressField 实现），再用dlv按点路径取深层值（例如content.rendered）。渲染规则有三条：

1. 如果取到的值是{ rendered: "..." }结构（WordPress 的 HTML 富文本字段如content、excerpt均如此），则通过dangerouslySetInnerHTML输出 HTML，并设置whiteSpace: normal；
2. 如果值为空或仍为对象 → 提示 "Please specify a valid field."；
3. 否则按普通文本渲染。

同样地，它也有上下文缺失的兜底提示："WordpressField must be used within a WordpressFetcher"。注意：由于field支持点路径，dlv取值意味着在画布中甚至可以访问嵌套属性（如_embedded.author[0].name），只要路径合法即可。

五、底层查询原理：wp-json 端点与参数构造

组件的数据能力来自@plasmicpkgs/wordpress的 query-wordpress.ts。该文件把wordpressUrl与queryType拼接为标准的 WordPress REST 端点：

{wordpressUrl}/wp-json/wp/v2/{posts|pages}

随后通过URLSearchParams追加查询参数（参数构造段）：

• 旧式单筛选（已废弃但兼容）：queryOperator+filterValue直接作为{operator}={value}追加，例如search=test、slug=test-slug、author=1；
• 分页：limit被转为per_page且上限封顶为 100（Math.min(limit, 100)）；page与offset也直接映射为同名参数；
• 排序：reverseOrder为 true 时追加order=asc；orderby直接透传（可选值包括relevance、date、modified、title、slug、author、id，对 pages 还额外支持menu_order、parent）。

响应处理方面（响应解析段）：请求失败时尝试解析 WordPress 返回的 JSON 错误消息，否则抛出WordPress API error (status)；成功时除items外，还从响应头X-WP-Total与X-WP-TotalPages提取总条数与总页数，返回结构化结果：

{ items: any[]; // 文章/页面数组 total: number; // 总条数（来自 X-WP-Total） totalPages: number;// 总页数（来自 X-WP-TotalPages） page: number; // 当前页码（默认 1） perPage: number; // 每页条数（默认 10） }

这些 URL 构造与返回结构都有对应的单元测试佐证，见 query-wordpress.test.ts：例如无筛选时请求https://example.com/wp-json/wp/v2/posts、带search=test时追加查询参数、limit: 2时追加per_page=2、返回对象包含items/total/totalPages/page/perPage等。

六、现代查询方式：filterLogic 与 JSON Logic 筛选

query-wordpress.ts同时导出了面向 Plasmic 画布注册的自定义查询函数queryWordpress（元信息见 queryWordpressMeta），它提供了比旧式queryOperator更强大的filterLogic筛选能力。filterLogic使用 JSON Logic 格式表达筛选条件，例如：

{ "==": [{ "var": "status" }, "publish"] }

其类型标注明确注释了旧式筛选 props 已废弃："These filter props are deprecated. UsefilterLogicwith the query builder instead. Only used by the deprecated plasmic-wordpress package"——即旧接口仅为当前plasmic-wordpress包保留向后兼容。

6.1 查询构建器的字段模型

where.ts 定义了查询构建器（query builder）的字段模型：

• 文章（posts）字段：id、date、modified、slug、author、categories（多选）、tags（多选）、sticky、search、search_columns；
• 页面（pages）字段：继承上述通用字段，并额外增加parent、menu_order；
• date/modified默认使用greater（大于）运算符，避免默认展示等值比较；
• 分类与标签的下拉选项由fetchCategories/fetchTags动态拉取（/wp-json/wp/v2/categories?per_page=100与/wp-json/wp/v2/tags?per_page=100）。

构建器配置刻意做了限制：conjunctions 仅支持 AND，maxNesting: 1，showNot: false。源码注释解释了原因：WordPress REST API 原生不支持 OR 逻辑，因此只开放 AND 组合、禁用嵌套分组，保证生成的筛选条件一定能被 REST 端点消费。

6.2 JSON Logic 到 REST 参数的映射

rulesLogicToWordPressFilters把构建器产出的 JSON Logic 翻译为 REST 查询参数（转换实现）：

不支持的比较（如对非日期字段使用</>）会打印console.warn并返回空过滤，保证不产生非法请求。

七、安装与注册：把组件接入你的 Plasmic 项目

在 Plasmic 项目（如examples下的 Next.js 项目）中接入该包的方式：

1. 安装依赖：

npm install @plasmicpkgs/plasmic-wordpress # 或 pnpm add @plasmicpkgs/plasmic-wordpress

2. 调用registerAll注册（可参考 src/index.tsx）：

import { registerAll } from "@plasmicpkgs/plasmic-wordpress"; registerAll();

如果你的项目使用自定义 loader，可传入 loader 实例：registerAll({ registerComponent, registerGlobalContext })。注册完成后，Wordpress Provider、Wordpress Fetcher、Wordpress Field会出现在 Plasmic 画布组件面板中。

3. 画布装配流程：

• 拖入Wordpress Provider，在属性面板把Wordpress URL填为你的站点地址；
• 在 Provider 内部拖入Wordpress Fetcher，设置query type（posts/pages），并按需设置筛选、limit；
• 在 Fetcher 内部放置Wordpress Field，选择要展示的字段（如title、excerpt、content）；
• 运行时组件会自动为每条记录重复渲染子节点，形成文章/页面列表。

八、集成提示与边界

• 只读场景：该包仅消费公开的只读 REST 端点，适合展示文章列表、最新博客内容等场景；涉及写操作需要另外的方案。
• limit上限：底层会将limit映射为per_page并封顶 100，超出部分不会生效（实现位置）。
• HTML 渲染：content/excerpt通过dangerouslySetInnerHTML输出，字段来源是站点自身数据，需确保 WordPress 站点可信。
• 缓存：usePlasmicQueryData会按{queryType, queryOperator, filterValue, limit, wordpressUrl}缓存结果，同一参数组合不会重复请求（缓存键构造）。
• 向后兼容：包中旧的_queryWordpress与queryOperator筛选在源码中明确标记为 deprecated，新项目建议直接使用queryWordpress+filterLogic（即@plasmicpkgs/wordpress的自定义函数）。

如果想深入底层细节，可继续阅读 query-wordpress.ts 与 where.ts 的实现，以及 query-wordpress.test.ts 中的 URL 构造断言；包的公开 API 签名可以查阅 api/index.api.md。

• 低代码
• 前端
• 后端