Elementor 使用数据上报 Schema 全解析usage.json 结构与 usage 追踪实现【免费下载链接】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本篇指南以 Elementor 开源仓库中的 usage schema 演进记录 与 usage.json JSON Schema 定义 为核心系统讲解 Elementor 匿名使用数据Usage Tracking的上报数据模型从顶层字段、system环境信息、usages统计维度到posts、library、elements、settings等各数据块的字段含义与枚举约束并结合 includes/tracker.php 与 modules/usage/module.php 的源码实现与测试用例帮助读者完整掌握这份 Schema 的数据结构、演进历史与底层统计逻辑具备直接阅读、校验甚至扩展 Elementor 使用数据格式的能力。一、先认识关联文档一份记录 Schema 演进的 Changelog仓库中 tests/phpunit/schemas/readme.md 全篇是一份精简的 Changelog记录了usage.json这个使用数据 Schema 在两次版本迭代中的结构变化Schema 版本变更内容对应数据块3.3.0新增usage/non-elementor-posts用于统计未使用 Elementor 构建的文章数量usages.non-elementor-posts3.5.0新增usage/library-details为每种 post-type 补充 library 模板的详细数量usages.library-details这两次演进揭示了一个重要设计思路Elementor 的使用数据上报Usage Tracking不仅要统计用了 Elementor 的内容还要统计没用的内容作为对照non-elementor-posts同时把模板库的统计从按模板类型汇总library细化到按模板类型 文章状态library-details。后文将结合源码逐一还原这两条记录的实现。而 Changelog 所描述的承载对象就是同一目录下的核心文件 usage.jsonJSON Schema draft-07 格式共 1387 行它是本文的主体。二、usage.json 顶层结构一次上报请求包含什么usage.json声明了上报数据的根节点类型为object并设置了 4 个顶层必填字段required: [ system, site_lang, email, usages ]同时根节点还允许出现以下可选字段均通过additionalProperties: false严格约束任何未声明字段都会被 Schema 校验器拒绝顶层字段类型含义systemobject必填站点运行环境服务器、WordPress、主题、插件等site_langstring必填站点语言LCID 格式如en-USemailstring必填管理员邮箱受^\S\S$正则约束usagesobject必填Elementor 各组件使用情况统计is_first_timeboolean是否为首次上报使用数据install_timenumber安装时间戳allowed_usage_timenumber允许统计的起始时间点site_keystring站点唯一标识analytics_eventsarray同意共享使用数据的用户的行为事件数组这一结构与 includes/tracker.php 中Tracker::get_tracking_data()的构造逻辑完全对应该方法先组装system、site_lang、email、usages四个必填块再按条件附加is_first_time、install_time、site_key、allowed_usage_time最后通过elementor/tracker/send_tracking_data_params过滤器允许其他模块如 modules/usage/module.php 中的add_tracking_data继续追加数据。值得注意的是email字段在 Schema 中带有一条注释TODO: Remove duplicated data说明它同时在system.wordpress.admin_email与顶层各出现一次属于已知的冗余设计。2.1 全局复用的枚举定义Schema 的definitions.global定义了 4 组被多处$ref引用的字符串枚举理解它们有助于读懂后续所有字段枚举名取值典型用途yes_noYes/No布尔式状态如system.server.gd_installedyes_no_lowercaseyes/no小写布尔式状态如usages.settings.general.allow_trackingactive_inactiveActive/Inactive启停状态如system.wordpress.debug_modeactive_inactive_lowercaseactive/inactive实验功能状态如usages.settings.experiments.*.default三、system 数据块服务器、WordPress、主题与插件环境system是描述站点运行环境的核心对象必填字段为server、wordpress、theme、plugins可选字段包括user、network_plugins、mu_plugins、elementor_compatibility。3.1 serverWeb 服务器环境必填字段共 11 个覆盖了排查环境问题时最关心的信息字段类型/枚举说明与示例osstring服务器操作系统如DarwinsoftwarestringHTTP 服务器类型与版本如Apache/2.4.46 (Unix) PHP/7.2.34mysql_versionstringMySQL 版本如Homebrew v10.5.8php_versionstringPHP 版本如7.2.34php_memory_limitstringPHP 内存上限如128Mphp_max_input_varsstringPHP 允许的最大输入变量数如1000php_max_post_sizestringPHP 允许的最大 POST 体积如8Mgd_installedyes_no是否安装 GD 图像处理扩展zip_installedyes_no是否安装 zip 扩展write_permissionsstring目录写权限检查结果正常为All right异常时为问题文件列表elementor_librarystringElementor 库连接状态格式为Connected或Not connected (错误信息)3.2 wordpressWordPress 环境12 个必填字段中值得注意的有is_multisite是否多站点默认No复用yes_no枚举max_upload_size最大上传大小示例2 MBmemory_limit与max_memory_limit分别描述普通请求与后台管理请求的内存上限示例40M/256Mpermalink_structure固定链接结构如/blog/%year%/%monthnum%/%day%/%postname%/languageWordPress 语言LCID 格式如en-UStimezoneGMT 偏移量可为负admin_email引用全局email定义debug_mode调试模式是否开启复用active_inactive默认Inactive。3.3 theme 与 usertheme记录当前主题的name、version、author与is_child_theme是否子主题yes_no枚举。其中version与author的类型均为[string, boolean]联合类型默认值false用于兼容主题头部信息缺失的情况。user为可选块注释标记Optional描述当前登录用户role可为null或字符串如administrator、locale如en_US、agent浏览器 User-Agent 字符串。3.4 plugins 体系active / network / must-use 三层插件definitions.plugins是插件对象的通用定义键名通过patternProperties匹配.*\.php$插件主文件路径如elementor/elementor.php每个插件对象必填 14 个字段Elementor tested up to、Name、PluginURI、Version、Description、Author、AuthorURI、TextDomain、DomainPath、Network、RequiresWP、RequiresPHP、Title、AuthorName。其中Elementor tested up to表示该插件兼容测试到的 Elementor 最高版本Network为布尔值标识是否为 WordPress 多站点网络级插件。system.plugins.active_plugins引用该定义并额外要求必须包含elementor/elementor.php即 Elementor 自身必须是已激活插件这是 Schema 的硬性约束network_plugins.network_active_plugins与mu_plugins.must_use_plugins同样引用该定义分别覆盖网络激活插件与必须使用must-use插件。elementor_compatibility为可选对象记录各插件与 Elementor 的兼容状态。四、usages 数据块从文章、模板到控件级使用统计usages是整份 Schema 中信息量最大的部分必填字段为posts、non-elementor-posts、library、library-details、elements另有favorites、settings、tools、connect、kit、onboarding_features、global_classes等可选块。4.1 posts 与 non-elementor-postsElementor 覆盖率的正反两面两者共用同一个定义posts_per_type_per_post_status其结构为文章类型 → 文章状态 → 数量的二级嵌套{ type: [object, array], patternProperties: { ([^\\s]): { patternProperties: { (draft|pending|private|publish|inherit|trash)$: { type: integer, title: Count of post(s) per post-type } }, additionalProperties: false } }, additionalProperties: false }内层键被正则严格限定为六种文章状态之一draft草稿、pending待审、private私密、publish已发布、inherit继承如附件、trash回收站。non-elementor-posts在 Schema 中给出了一组真实示例{ attachment: { inherit: 15 }, elementor_snippet: { auto-draft: 1, publish: 1 }, page: { draft: 1, publish: 1 }, post: { auto-draft: 2 } }对应的底层实现分别位于 includes/tracker.php 的get_posts_usage()与 includes/tracker.php 的get_non_elementor_posts_usage()两条 SQL 的区别在于 JOIN 条件统计 Elementor 文章时筛选meta_key _elementor_edit_mode AND meta_value builder的文章并按post_type、post_status分组计数且排除elementor_library类型统计非 Elementor 文章时3.3.0 新增通过LEFT JOIN后取meta_value IS NULL的行即没有_elementor_edit_mode元数据的文章从而得到站点中未用 Elementor 构建的内容数量两个数据块配合即可计算 Elementor 在站点中的覆盖率。4.2 library 与 library-details模板库的两代统计口径usages.library键为模板类型patternProperties匹配[^\s]如section、page、widget、kit值为该类型的模板总数type: stringSchema 注释标明TODO: Should be number即历史遗留的类型不严谨之处。usages.library-details3.5.0 新增键为模板类型值为count_per_post_status定义——按文章状态细分的数量对象状态键同样受(draft|pending|private|publish|inherit|trash)$正则约束。Schema 示例{ kit: { publish: 1 }, page: { draft: 3 }, section: { draft: 1, publish: 1 }, widget: { draft: 1, publish: 1, trash: 2 } }实现上includes/tracker.php 的get_library_usage()只按_elementor_template_type分组计数而 includes/tracker.php 的get_library_usage_extend()在GROUP BY中额外加入了post_status从而产出按模板类型 状态细分的library-details。两代口径并存正是 Changelog 中 3.5.0 变更的代码落点。4.3 elements控件级使用统计最深的数据维度usages.elements是 Schema 中层级最深的数据块采用文档类型 → 元素类型 → 元素统计 → 控件统计的四级结构{ type: [object, boolean], description: Usage of controls per document-type., patternProperties: { ([^\\s]): { patternProperties: { ([^\\s]): { required: [count, controls], properties: { count: { type: number }, control_percent: { type: number }, controls: { patternProperties: { (content|style|advanced|layout|general)$: { ... } } } } } } } } }每个元素对象必填count元素在文档类型中的使用次数与controls可选control_percent被修改控件占该元素全部控件的百分比。controls的键被正则限定为五个标签页content、style、advanced、layout、general每个标签页下再按分区section→ 控件名 → 使用次数层层嵌套。general标签页有特殊子结构__dynamic__动态标签下包含一个count字段用于统计使用动态标签Dynamic Tags的次数。这一点在测试用例 tests/phpunit/elementor/schemas/test-usage.php 中得到验证断言$usage[elements][wp-post][heading][controls][general]中必须包含__dynamic__键。该结构的实际生成逻辑在 modules/usage/module.php 的get_elements_usage()中通过Plugin::$instance-db-iterate_data()遍历文档的_elementor_data区分widgetType控件与elType元素后交由使用计算器处理。计算器体系由 contracts/element-usage-calculator.php 定义的Element_Usage_Calculator接口can_calculate/calculate与 element-usage-calculator-registry.php 注册表组成Atomic Widgets 模块激活时优先使用Atomic_Element_Usage_Calculator否则回退到 calculators/legacy-element-usage-calculator.php 的Legacy_Element_Usage_Calculator。以 Legacy 计算器为例其calculate()会累加元素计数并遍历元素 settings 中与默认值不同的控件add_controls内if ( $value ! $control_config[default] )判定按tab、section、control三级键递增计数同时计算control_percent 变更控件数 / (控件总数 / 100)后四舍五入。动态标签则通过add_general_controls()归入general标签页的__dynamic__分组。4.4 settings 与 tools非默认配置上报usages.settings按general、advanced、performance、experiments四个子块组织仅上报非默认值的配置这从实现端 modules/usage/module.php 的get_settings_usage()可以看出跳过隐藏字段、跳过默认值。Schema 为每个字段给出了完整枚举与默认值例如generalcpt_support支持的 post-type 数组、disable_color_schemes/yes、disable_typography_schemes/yes、allow_trackingyes_no_lowercase默认yesadvancededitor_break_lines/1默认1、unfiltered_files_upload、google_font1/0默认1、font_displayauto/block/swap/fallback/optional默认auto、load_fa4_shim默认yes、meta_generator_tagperformancecss_print_methodinternal/external默认internal、optimized_image_loading、optimized_gutenberg_loading、lazy_load_background_imagesexperiments每个实验对象包含defaultactive/inactive、stateactive/inactive/default三者 oneOf、tagstypelabel对象数组。usages.tools类似地分为generalsafe_mode为/global、enable_inspector为/enable、versionbeta是否参与 Beta 测试默认no、maintenancemaintenance_mode_mode为/coming_soon/maintenancemaintenance_mode_exclude_mode为logged_in/custom另有maintenance_mode_exclude_roles角色数组与maintenance_mode_template_id模板 ID。4.5 其余可选数据块favorites按收藏类型favorite-type列出被收藏的元素 ID 字符串数组connectElementor Connect 授权信息含site_keystring/boolean、count用户数、users数组每项含id、email、roles注释提醒 id 仅在单个 WP 站点内唯一kitElementor Kit 使用情况defaults内含count整数与elements字符串数组onboarding_features引导流程Onboarding启用的功能名称字符串数组global_classes全局类Global Classes统计total_count为总数applied_classes_per_element_type按元素类型记录应用次数。五、Schema 的实战用法校验、报告与重新计算5.1 用 PHPUnit 校验真实上报数据仓库将 Schema 直接用于测试tests/phpunit/elementor/schemas/test-usage.php 通过JsonSchema\Exception\ValidationException与ElementorEditorTesting\Base_Schema基类做了四类验证test__ensure_clean_is_valid在插件 mock 数据下用Tracker::get_tracking_data()生成的完整数据必须通过 Schema 校验test__ensure_invalid_exception空数组[]必须触发ValidationException因为缺少必填字段test__ensure_all_objects_have_no_additional_properties断言 Schema 中所有对象都设置了additionalProperties: false保证数据格式的封闭性test__ensure_tracking_data_with_usage_full_mock构造尽可能完整的全量 mock——创建普通文章、创建not-supported模板、发布含动态标签Dynamic Tags的文档、注册Title/Link两个测试动态标签、写入 Connect 假数据等再断言posts、library、elements含wp-post文档类型下的 4 个元素与__dynamic__控件均存在最后整体通过 Schema 校验。运行方式为仓库标准的 PHPUnit 测试流程参见 docs/devlopment/phpunit.mdSchema 本身则通过其$schema声明http://json-schema.org/draft-07/schema可被任何 JSON Schema 校验器如 ajv、json-schema-validator离线复用。5.2 在系统信息面板查看与重算usages模块在 modules/usage/module.php 的add_system_info_report()中注册了两个系统信息System Info报告器usage-reporter.phpElements Usage报告遍历elementor_controls_usage选项按文档类型列出各元素的计数页面中带有一个Recalculate链接通过elementor_usage_recalc查询参数触发Module::recalc_usage()全量重算settings-reporter.phpSettings报告输出Module::get_settings_usage()收集的非默认设置项。重算逻辑 recalc_usage() 支持分页参数$limit/$offset偏移为 0 时先清空旧选项通过WP_Query查询所有带_elementor_data元数据的publish/private文章逐一执行after_document_save()重新累计适合站点数据迁移或数据损坏后的重建场景。5.3 数据生命周期何时写入、何时扣除从 modules/usage/module.php 的构造器可以看出模块只在用户允许追踪Tracker::is_allow_track()时启用并挂载了四个生命周期钩子transition_post_status文章状态迁移时若从publish/private移出则remove_from_global()扣除旧统计迁入则save_document_usage()累加before_delete_post删除文章前扣除其用量elementor/document/before_save与elementor/document/after_save编辑器内保存文档时先移除旧统计再写入新统计elementor/tracker/send_tracking_data_params把elementor_controls_usage选项即usages.elements数据注入上报参数。单篇文档的用量存于文章 meta_elementor_controls_usage全站聚合存于选项elementor_controls_usageSchema 中usages.elements的结构与后者完全一致。这种逐文档记账 全局聚合的设计使得 Schema 校验通过的数据可以直接用于站点健康度分析、插件兼容性排查等功能。六、小结以 readme.md 这份两行的 Changelog 为索引可以完整还原 Elementor 使用数据 Schema 的演进脉络3.3.0 引入的non-elementor-posts让统计数据具备了未使用 Elementor 内容的对照维度3.5.0 引入的library-details将模板库统计细化到状态粒度。而 usage.json 本身则通过严格的 JSON Schema必填约束、正则枚举、additionalProperties: false约束着从system环境信息到usages.elements控件级计数的全部上报字段其背后是 includes/tracker.php 的 SQL 聚合、modules/usage/module.php 的逐文档记账以及 tests/phpunit/elementor/schemas/test-usage.php 的持续校验。对开发者而言这份 Schema 既是理解 Elementor 数据上报的契约文档也是可复用的数据格式参考——它完整定义了一款 WordPress 页面构建器产品在做匿名使用统计时会关注哪些环境指标与使用行为维度。【免费下载链接】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），仅供参考