wp-abilities-api

WP Abilities API

适用场景

遇到以下任务时使用此技能：

• 在 PHP 中注册能力或能力类别，
• 通过 REST（wp-abilities/v1）向客户端公开能力，
• 在 JS 中使用能力（尤其是 @wordpress/abilities），
• 排查“能力未显示”／“客户端看不到能力”／“REST 返回空结果”。

所需输入

• 仓库根目录（如果尚未运行，请先运行 wp-project-triage）。
• 目标 WordPress 版本，以及这是 WP 核心还是插件／主题。
• 应将更改放在哪里（插件、主题还是 mu-plugin）。

流程

1) 确认可用性和版本限制

• 如果这是 WP 核心相关工作，请检查 signals.isWpCoreCheckout 和 versions.wordpress.core。
• 如果项目面向低于 WP 6.9 的版本，可能需要使用 Abilities API 插件／软件包，而不能依赖核心提供的功能。

2) 查找现有的 Abilities 用法

在仓库中搜索以下内容：

• wp_register_ability(
• wp_register_ability_category(
• wp_abilities_api_init
• wp_abilities_api_categories_init
• wp-abilities/v1
• @wordpress/abilities

如果均未找到，请判断你是要全新引入 Abilities API（新增注册并由客户端使用），还是仅使用现有 API。

3) 注册类别（可选）

如果需要进行逻辑分组，请尽早注册能力类别（参见 references/php-registration.md）。

4) 注册能力（PHP）

在 PHP 注册中实现该能力，并包含：

• 稳定的 id（使用命名空间），
• label／description，
• category，
• meta：
  • 如果该能力用于提供信息，请添加 readonly: true，
  • 对于希望客户端可见的能力，请设置 show_in_rest: true。

使用 Abilities API 文档规定的初始化钩子进行注册，确保其在正确的时机加载（参见 references/php-registration.md）。

5) 确认 REST 公开情况

• 验证 REST 端点是否存在并返回预期结果（参见 references/rest-api.md）。
• 如果客户端仍看不到该能力，请确认已启用 meta.show_in_rest，且查询的是正确的端点。

6) 从 JS 使用（如有需要）

• 优先使用 @wordpress/abilities API 在客户端访问能力并进行检查。
• 确保构建工具包含该依赖，且项目的构建流程会将其打包。

验证

• 更改后，wp-project-triage 会显示 signals.usesAbilitiesApi: true（如适用）。
• REST 检查（在 WP 环境中）：wp-abilities/v1 下的端点会在预期情况下返回你的能力和类别。
• 如果仓库中有测试，请在以下位置附近添加／更新覆盖：
  • PHP：能力注册和元数据公开
  • JS：能力使用和 UI 门控

故障模式／调试

• 能力始终不显示：
  • 注册代码未运行（钩子错误／文件未加载），
  • 缺少 meta.show_in_rest，
  • 类别／ID 不匹配。
• REST 显示能力，但 JS 不显示：
  • REST 基础路径／命名空间错误，
  • JS 依赖未打包，
  • 缓存（对象／页面缓存）遮蔽了更改。

升级处理

• 如果不确定版本支持情况，请确认目标 WP 核心版本，以及 Abilities API 应由核心提供还是作为插件提供。
• 如需权威细节，请参阅：
  • references/rest-api.md
  • references/php-registration.md