Elementor Global Classes API 完全指南REST 接口与 MCP Abilities 实战详解【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementorElementorV4 Atomic Builder将全局类Global Classes作为站点级设计令牌体系的核心通过两类表面对外暴露管理能力REST API 与 MCP abilities。本文基于仓库文档 docs/atomic-builder/global-classes/api.md 展开逐条剖析路由契约、PUT载荷结构、MCP 批量操作协议与底层实现global-classes-rest-api.php、global-classes-repository.php、manage-classes-ability.php读完你将能够为编辑器集成或自动化脚本 CRUD Kit 级全局类、让 LLM Agent 在build-composition之前预置设计令牌、通过导入导出管线迁移全局类以及在生产环境查询类引用关系后再安全删除。一、是什么两条管理面 一个只读资源Global Classes API 面向**活动 Kitactive kit**提供全局类的管理能力一共由三部分组成表面载体用途REST APIGlobal_Classes_REST_API命名空间elementor/v1/global-classes编辑器editor-global-classes包与任意 HTTP 客户端MCP abilitieselementor/manage-classes、elementor/reorder-classes面向 LLM Agent 的批量增删改与优先级调整只读 MCP resourceelementor://global-classes返回{ priority_description, classes }按 CSS 优先级从高到低排序的类清单三者面向同一个数据模型全局类持久化为CPT 帖子每个类一帖配合Kit 帖子元数据顺序、label 映射、id→帖子查找表共同构成内存形态{ items, order }。详细字段级设计见 数据模型文档此处不赘述。二、何时使用文档明确给出四类典型场景均以管理活动 Kit 上的类为边界编辑器集成或自动化 CRUD通过 REST 接口对 Kit 类做增删改查覆盖保存草稿与发布两个上下文LLM Agent 预设设计令牌在调用build-composition之前用 MCP 能力批量创建可复用的全局类再在组合步骤中按label引用Kit 导入导出导出管线生成global-classes.json导入管线调用Global_Classes_Repository::put()全量替换删除前的引用查询通过GET /global-classes/usage确认某类在哪些文档中被使用避免误删。三、核心概念一REST 路由与权限模型基础路径为elementor/v1/global-classes五个路由统一挂在rest_api_init钩子上源码见 global-classes-rest-api.php#L61-L227MethodRoute权限用途GET/global-classes已登录用户列出{ id, label }索引GET/global-classes/post?post_id已登录用户返回指定文档用到的样式 orderGET/global-classes/styles?ids已登录用户按逗号分隔 id 批量取样式 orderGET/global-classes/usagemanage_options按类统计文档引用PUT/global-classeselementor_global_classes_update_class批量创建 / 更新 / 删除 / 排序三个值得注意的细节context参数除/usage外的四个路由均接受可选context枚举值为frontend默认与preview对应已发布态与草稿态两套存储。在 global-classes-repository.php#L21-L22 中二者被定义为CONTEXT_FRONTEND frontend与CONTEXT_PREVIEW preview。写权限是独立 capabilityPUT需要elementor_global_classes_update_class该能力由数据库迁移 add-capabilities.php 注入与读路由的仅需登录形成严格的读写分离。/usage门槛最高manage_options要求管理员权限因为其返回的是跨文档的引用分布数据由 applied-global-classes-usage.php 计算。三个读路由的语义差别GET /global-classes返回的是轻量索引id → label用于编辑器面板、MCP 资源发现等只需要知道存在哪些类的场景实现上调用all_labels()而非全量读取。GET /global-classes/post先通过Global_Classes_Relations反查该文档实际引用的类 idget_styles_by_post()再批量取回完整样式定义order元数据只保留与文档相关的子集源码见 global-classes-rest-api.php#L245-L270。GET /global-classes/styles直接按调用方提供的ids逗号分隔字符串取样式order同样按请求 id 过滤global-classes-rest-api.php#L272-L298。四、核心概念二RESTPUT增量契约PUT /global-classes采用**增量变更delta**语义这是它与全量替换式导入接口最本质的区别。契约要点items中只为changes.added/changes.modified中的 id 提供完整定义被删除的 id 只出现在changes.deleted中不需要也不应携带items条目changes.order为布尔值表示本次请求是否改变了顺序。完整示例载荷{ context: preview, changes: { added: [g-newid1], deleted: [], modified: [g-abc123], order: true }, items: { g-abc123: { id: g-abc123, label: wc26-gold, type: class, variants: [] }, g-newid1: { id: g-newid1, label: wc26-navy, type: class, variants: [] } }, order: [g-abc123, g-newid1] }响应码与错误语义204成功无内容400DUPLICATED_LABELlabel 冲突服务端会自动重命名响应体携带modifiedLabels映射original→modified400global_classes_limit_exceeded超过每 Kit 上限1000个类常量Global_Classes_REST_API::MAX_ITEMS。服务端处理链路源码级put()的实际执行顺序可以从 global-classes-rest-api.php#L306-L397 还原解析changes与order计算total_count 现有数 - 删除数 新增数先做上限校验Global_Classes_Parser::parse_items()校验items结构与变体variant合法性失败返回invalid_items检测重复 label冲突项通过Global_Classes_Labels::generate_unique_label()以DUP_前缀重命名最大 50 字符并记录modifiedLabelsparse_order()校验 / 修正order未出现在order中的既有 id 会被自动追加到末尾避免脏数据落盘调用Global_Classes_Repository::apply_changes( $touched_items, $changes, $order )——它才是真正的写后端负责批量 CPT 增删改、更新 order/label 元数据、并触发elementor/global_classes/update事件见 global-classes-repository.php#L119-L177。其中预览态 vs 发布态的联动值得注意当contextfrontend提交时仓库会同步更新预览 order、清空受影响类的 preview 元数据确保草稿不会残留过期数据。五、核心概念三MCPelementor/manage-classes批量 CRUD面向 LLM Agent 的批量操作能力以原始 CSS 声明为输入服务端经Css_Converter转换为符合Style_Schema的样式 props 后再落盘能力定义见 manage-classes-ability.php。典型请求{ operations: [ { action: create, label: wc26-gold, css: { color: #D4AF37 } }, { action: update, id: g-abc123, label: wc26-gold, css: { color: #FFD700 } }, { action: delete, id: g-def456 } ] }三种操作的关键约束create服务端自动生成g-*内部 idCSS 经Css_Converter针对Style_Schema校验与转换桌面断点变体meta.breakpoint: desktopupdateid内部 id、label、css均可更新id与label都是唯一标识符缺id时会按 label 反查 iddelete只需id或 label为破坏性操作文档明确建议先与用户确认。css字段格式css是属性 → 值的映射对象能力 schema 中声明为字符串形式的原始 CSS实际同时支持声明映射。进阶规则属性值可使用变量var(--brand-primary)但变量必须已存在于elementor://global-variables否则返回invalid_css错误null或字符串null的值表示重置该属性patch 模式下移除该 prop简写属性shorthand可能无法被精确转换此时会退化为custom_css兜底存储base64 编码更新操作支持modepatch默认upsert 变体保留未触及的变体all: null可清空某断点变体与replace丢弃受影响断点的全部旧变体后写入新值null值无效果。重复 label 的自动处理create/update 遇到重复 label 时会通过Global_Classes_Labels::generate_unique_label()自动以DUP_前缀重命名。响应中对应操作会携带modified_label: { original, modified }供 Agent 感知改名结果——这是 Agent 必须处理的语义因为重命名后继续按原 label 引用会落空。响应与错误{ status: completed, results: [ { index: 0, action: create, status: ok, id: g-abc123, label: hero-heading } ], order: [g-abc123, g-existing] }批量中的单个操作失败不会中断整批错误项携带index、action、code、message其余操作照常执行请求上限 50 个操作MAX_BATCH_SIZE超出返回batch_size_exceededKit 总类数同样受MAX_ITEMS 1000约束超限的 create 会被拒收并标记global_classes_limit_exceeded实现见 manage-classes-ability.php#L512-L539从队尾开始拒绝 create。最佳实践始终先读取elementor://global-classes做发现避免重复 label、获取内部 id再执行 create/update/delete在build-composition与manage-elements中只按label引用类内部g-*id 仅用于 update/delete。六、核心概念四MCPelementor/reorder-classes优先级调整当多个已应用全局类对同一 CSS 属性产生冲突且结果不正确时用该能力调整类优先级详见 reorder-classes.md。顺序表第一位的类优先级最高越靠前的类在级联中越能覆盖靠后的类。输入二选一moves与order只能提供其一相对移动最多 50 步顺序执行{ moves: [ { id: g-accent, position: before, ref: g-base }, { id: g-heading, position: start } ] }position取值before/after/start/end其中before与after必须提供ref。显式顺序完整或部分{ order: [g-heading, g-accent, g-base] }规则请求中出现的 id 必须存在且只能出现一次未提及的既有 id 会按当前相对顺序追加到末尾并在响应appended_ids中返回。输出示例{ changed: true, order: [g-heading, g-accent, g-base], appended_ids: [], moves: [{ id: g-heading, from: 2, to: 0 }] }无操作请求顺序未变化返回changed: false不会触发 CSS 缓存失效避免无谓重绘。内部实现通过Global_Classes_Repository::apply_changes()以仅排序的变更落盘同步更新 frontend 与 preview 两套 order 元数据见 reorder-classes-ability.php。七、Kit 导入导出导出当导出设置include中包含settings时Kit 导出包写入global-classes.json导出运行器见 import-export/export-runner.php导入导入流程调用Global_Classes_Repository::put()做全量替换——对比当前 order 与传入 items 自动推导added / deleted / modified / order四组变更再走与 REST 相同的落盘与缓存失效管线global-classes-repository.php#L193-L234。八、公共 API 速查表PHP 侧服务端SymbolSignature用途Global_Classes_REST_APIpublic function register_hooks(): void在rest_api_init上注册全部路由Global_Classes_REST_APIconst API_NAMESPACE elementor/v1REST 命名空间Global_Classes_REST_APIconst MAX_ITEMS 1000每 Kit 类数量上限Global_Classes_Repositorypublic function apply_changes( array $touched_items, array $changes, array $order ): voidREST 写操作后端批量持久化Global_Classes_Parserpublic function parse( $data ): Parse_Result导入导出全量载荷校验JS 侧editor-global-classes包源码见 api.tsSymbolSignature对应路由apiClient.all( context? )默认previewGET /global-classesapiClient.getStylesForPost( postId, context? )—GET /global-classes/postapiClient.getStylesByIds( ids, context? )ids 为数组内部 join 成逗号串GET /global-classes/stylesapiClient.saveDraft( payload )固定contextpreviewPUT /global-classesapiClient.publish( payload )固定contextfrontendPUT /global-classesapiClient.usage()—GET /global-classes/usageJS 侧同样暴露API_ERROR_CODES.DUPLICATED_LABEL方便编辑器对重命名场景做 UI 反馈。九、扩展与集成方式目标路径Agent 集成MCPelementor/manage-classes原始 CSS 进、校验后的 variants 出与elementor/reorder-classes优先级调整编辑器对齐RESTPUT传{ items, order, changes }与编辑器保存链路同构组合composition在build-composition中通过classeslabel 映射引用不直接走 REST关于组合层applying-classes.md 补充了两个关键机制Classes_Prop_Type接受符合/^[a-z][a-z-_0-9]*$/i的字符串数组作为classes设置项渲染时Classes_Transformerelementor/atomic-widgets/settings/transformers/classes过滤器把内部 id 解析为 HTML class 名label。局部样式providerdocument-elements优先级 50始终覆盖全局类providerglobal-classes优先级 30这是设计上刻意为之的覆盖优先级。十、内部机制与缓存失效写后事件Global_Classes_Repository::apply_changes()与put()都会触发elementor/global_classes/updateaction事件载荷包含{ added, deleted, modified, order, affected_post_ids }删除操作额外触发elementor/global_classes/cleanup。缓存失效上述事件最终驱动 atomic-global-styles.php 的Atomic_Global_Styles::invalidate_cache_for_updated_classes()使生成 CSS 失效前端按[global, $post_id, $context]注册每文档 CSS且只包含该文档实际使用的类避免无引用类污染样式输出。批量读优化仓库读取按每批 100 个 id 分块执行get_posts并在批次间clean_post_cache与wp_cache_flush_runtime防止内存与对象缓存膨胀global-classes-repository.php#L310-L332。JS MCP 工具mcp-integration/manage-classes-tool.ts封装了 Agent 侧的调用入口。十一、继续深入数据模型CPT 与 Kit meta 字段级设计类在原子元素上的应用与级联规则MCP manage-classes 能力全参数说明MCP reorder-classes 能力全参数说明CSS 转换器Css_Converter / Style_Schema总览MCP 资源模型elementor://global-classes【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考