wp-abilities-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Abilities API

When to use

适用场景

Use this skill when the task involves:

registering abilities or ability categories in PHP,
exposing abilities to clients via REST (
```
wp-abilities/v1
```
),
consuming abilities in JS (notably
```
@wordpress/abilities
```
),
diagnosing “ability doesn’t show up” / “client can’t see ability” / “REST returns empty”.

当任务涉及以下内容时，使用本技能：

在PHP中注册能力或能力分类，
通过REST接口（
```
wp-abilities/v1
```
）向客户端暴露能力，
在JS中使用能力（尤其是
```
@wordpress/abilities
```
），
排查“能力未显示”/“客户端无法看到能力”/“REST返回空值”等问题。

Inputs required

所需输入

Repo root (run
```
wp-project-triage
```
first if you haven’t).
Target WordPress version(s) and whether this is WP core or a plugin/theme.
Where the change should live (plugin vs theme vs mu-plugin).

仓库根目录（如果还没运行过
```
wp-project-triage
```
，请先执行）。
目标WordPress版本，以及当前是WP核心、插件还是主题开发。
变更应存放的位置（插件、主题或必须使用的插件mu-plugin）。

Procedure

操作步骤

1) Confirm availability and version constraints

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

If this is WP core work, check

signals.isWpCoreCheckout

and

versions.wordpress.core

If the project targets WP < 6.9, you may need the Abilities API plugin/package rather than relying on core.

如果是WP核心开发，检查

signals.isWpCoreCheckout

和

versions.wordpress.core

。

如果项目目标WP版本低于6.9，你可能需要使用Abilities API插件/包，而非依赖核心内置功能。

2) Find existing Abilities usage

2) 查找现有Abilities API使用情况

Search for these in the repo:

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

If none exist, decide whether you’re introducing Abilities API fresh (new registrations + client consumption) or only consuming.

在仓库中搜索以下内容：

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

如果没有找到任何相关内容，需决定是全新引入Abilities API（包括新的注册逻辑和客户端消费）还是仅进行客户端消费。

3) Register categories (optional)

3) 注册分类（可选）

If you need a logical grouping, register an ability category early (see

references/php-registration.md

如果需要逻辑分组，请尽早注册能力分类（参考

references/php-registration.md

）。

4) Register abilities (PHP)

4) 注册能力（PHP）

Implement the ability in PHP registration with:

stable
```
id
```
(namespaced),
```
label
```
/
```
description
```
,
```
category
```
,
```
meta
```
:
- add
```
readonly: true
```
  when the ability is informational,
- set
```
show_in_rest: true
```
  for abilities you want visible to clients.

Use the documented init hooks for Abilities API registration so they load at the right time (see

references/php-registration.md

通过PHP注册实现能力，需包含：

稳定的
```
id
```
（带命名空间），
```
label
```
/
```
description
```
，
```
category
```
，
```
meta
```
:
- 当能力仅为信息性时，添加
```
readonly: true
```
  ，
- 对于需要对客户端可见的能力，设置
```
show_in_rest: true
```
  。

使用Abilities API文档中指定的初始化钩子进行注册，确保代码在正确时机加载（参考

references/php-registration.md

）。

5) Confirm REST exposure

5) 确认REST接口暴露

Verify the REST endpoints exist and return expected results (see
```
references/rest-api.md
```
).
If the client still can’t see the ability, confirm
```
meta.show_in_rest
```
is enabled and you’re querying the right endpoint.

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

6) Consume from JS (if needed)

6) 从JS中消费能力（如有需要）

Prefer
```
@wordpress/abilities
```
APIs for client-side access and checks.
Ensure build tooling includes the dependency and the project’s build pipeline bundles it.

优先使用
```
@wordpress/abilities
```
API进行客户端访问和检查。
确保构建工具包含该依赖，且项目的构建流水线已将其打包。

Verification

验证步骤

wp-project-triage

indicates

signals.usesAbilitiesApi: true

after your change (if applicable).

REST check (in a WP environment): endpoints under
```
wp-abilities/v1
```
return your ability and category when expected.
If the repo has tests, add/update coverage near:
- PHP: ability registration and meta exposure
- JS: ability consumption and UI gating

变更后，

wp-project-triage

应显示

signals.usesAbilitiesApi: true

（如适用）。

在WP环境中进行REST检查：
```
wp-abilities/v1
```
下的端点应在预期情况下返回你的能力和分类。
如果仓库包含测试用例，添加/更新以下相关测试覆盖：
- PHP：能力注册和元数据暴露
- JS：能力消费和UI权限控制

Failure modes / debugging

故障模式与调试

Ability never appears:
- registration code not running (wrong hook / file not loaded),
- missing
```
meta.show_in_rest
```
  ,
- incorrect category/ID mismatch.
REST shows ability but JS doesn’t:
- wrong REST base/namespace,
- JS dependency not bundled,
- caching (object/page caches) masking changes.

能力始终不显示：
- 注册代码未执行（钩子错误/文件未加载），
- 缺少
```
meta.show_in_rest
```
  配置，
- 分类/ID不匹配。
REST接口显示能力但JS端无法获取：
- REST基础路径/命名空间错误，
- JS依赖未打包，
- 缓存（对象缓存/页面缓存）掩盖了变更。

Escalation

升级处理

If you’re uncertain about version support, confirm target WP core versions and whether Abilities API is expected from core or as a plugin.

For canonical details, consult:

```
references/rest-api.md
```
```
references/php-registration.md
```

若对版本支持不确定，请确认目标WP核心版本，以及Abilities API是预期由核心提供还是作为插件使用。

如需权威细节，请参考：

```
references/rest-api.md
```
```
references/php-registration.md
```