@wordpress/abilities-WordPress区块编辑器手册-果果开发

WordPress Abilities API 的客户端库，提供了一种标准化的方式来发现和执行 WordPress 能力。

安装

该客户端目前作为 Composer 包的一部分提供。

作为 WordPress 脚本

当安装了 Abilities API 时，客户端会自动在后台管理中注册并排队加载。

用法

// In your WordPress plugin or theme JavaScript
const { getAbilities, getAbility, executeAbility } = wp.abilities;
// or import { getAbilities, getAbility, executeAbility } from '@wordpress/abilities'; depending on your setup

// Get all abilities
const abilities = getAbilities();

// Get a specific ability
const ability = getAbility( 'my-plugin/my-ability' );

// Execute an ability
const result = await executeAbility( 'my-plugin/my-ability', {
    param1: 'value1',
    param2: 'value2',
} );

与 React 和 WordPress Data 配合使用

客户端包含一个数据仓库，可与 @wordpress/data 集成以在 React 组件中使用：

import { useSelect } from '@wordpress/data';
import { store as abilitiesStore } from '@wordpress/abilities';

function MyComponent() {
    const abilities = useSelect(
        ( select ) => select( abilitiesStore ).getAbilities(),
        []
    );

    const specificAbility = useSelect(
        ( select ) =>
            select( abilitiesStore ).getAbility( 'my-plugin/my-ability' ),
        []
    );

    return (
        <div>
            <h2>All Abilities</h2>
            <ul>
                { abilities.map( ( ability ) => (
                    <li key={ ability.name }>
                        <strong>{ ability.label }</strong>:{ ' ' }
                        { ability.description }
                    </li>
                ) ) }
            </ul>
        </div>
    );
}

API 参考

函数

getAbilities( args: AbilitiesQueryArgs = {} ): Ability[]

返回所有已注册的能力。可选择按类别 slug 进行过滤。

// Get all abilities
const abilities = getAbilities();
console.log( `Found ${ abilities.length } abilities` );

// Get abilities in a specific category
const dataAbilities = getAbilities( { category: 'data-retrieval' } );
console.log( `Found ${ dataAbilities.length } data retrieval abilities` );

getAbility( name: string ): Ability | undefined

按名称返回特定能力，如果未找到则返回 undefined。

const ability = getAbility( 'my-plugin/create-post' );
if ( ability ) {
    console.log( `Found ability: ${ ability.label }` );
}

getAbilityCategories(): AbilityCategory[]

返回所有已注册的能力类别。类别用于将能力组织到逻辑组中。

const categories = getAbilityCategories();
console.log( `Found ${ categories.length } categories` );

categories.forEach( ( category ) => {
    console.log( `${ category.label }: ${ category.description }` );
} );

getAbilityCategory( slug: string ): AbilityCategory | undefined

按 slug 返回特定能力类别，如果未找到则返回 undefined。

const category = getAbilityCategory( 'data-retrieval' );
if ( category ) {
    console.log( `Found category: ${ category.label }` );
    console.log( `Description: ${ category.description }` );
}

registerAbility( ability: Ability ): void

注册客户端能力。客户端能力在浏览器本地执行，必须包含回调函数和有效的类别。

import { registerAbility } from '@wordpress/abilities';

registerAbility( {
    name: 'my-plugin/navigate',
    label: 'Navigate to URL',
    description: 'Navigates to a URL within WordPress admin',
    category: 'navigation',
    input_schema: {
        type: 'object',
        properties: {
            url: { type: 'string' },
        },
        required: [ 'url' ],
    },
    callback: async ( { url } ) => {
        window.location.href = url;
        return { success: true };
    },
} );

registerAbilityCategory( slug: string, args: AbilityCategoryArgs ): void

注册客户端能力类别。这在注册引入服务器未定义的新类别的客户端能力时非常有用。

import { registerAbilityCategory } from '@wordpress/abilities';

// Register a new category
registerAbilityCategory( 'block-editor', {
    label: 'Block Editor',
    description: 'Abilities for interacting with the WordPress block editor',
} );

// Register a category with optional metadata
registerAbilityCategory( 'custom-category', {
    label: 'Custom Category',
    description: 'A category for custom abilities',
    meta: {
        color: '#ff0000',
    },
} );

// Then register abilities using the new category
registerAbility( {
    name: 'my-plugin/insert-block',
    label: 'Insert Block',
    description: 'Inserts a block into the editor',
    category: 'block-editor', // Uses the client-registered category
    callback: async ( { blockType } ) => {
        // Implementation
        return { success: true };
    },
} );

unregisterAbilityCategory( slug: string ): void

从存储中注销能力类别。

import { unregisterAbilityCategory } from '@wordpress/abilities';

unregisterAbilityCategory( 'block-editor' );

unregisterAbility( name: string ): void

从存储中注销客户端能力。

import { unregisterAbility } from '@wordpress/abilities';

unregisterAbility( 'my-plugin/navigate' );

executeAbility( name: string, input?: Record<string, any> ): Promise<any>

执行带有可选输入参数的能力。

// Execute an ability
const result = await executeAbility( 'my-plugin/create-item', {
    title: 'New Item',
    content: 'Item content',
} );

存储选择器

当与 @wordpress/data 配合使用时：

getAbilities( args: AbilitiesQueryArgs = {} ) – 从存储返回所有能力，可选择按查询参数过滤
getAbility( name: string ) – 从存储返回特定能力
getAbilityCategories() – 从存储返回所有类别
getAbilityCategory( slug: string ) – 从存储返回特定类别

import { useSelect } from '@wordpress/data';
import { store as abilitiesStore } from '@wordpress/abilities';

function MyComponent() {
    // Get all abilities
    const allAbilities = useSelect(
        ( select ) => select( abilitiesStore ).getAbilities(),
        []
    );

    // Get all categories
    const categories = useSelect(
        ( select ) => select( abilitiesStore ).getAbilityCategories(),
        []
    );

    // Get abilities in a specific category
    const dataAbilities = useSelect(
        ( select ) =>
            select( abilitiesStore ).getAbilities( {
                category: 'data-retrieval',
            } ),
        []
    );

    // Get a specific category
    const dataCategory = useSelect(
        ( select ) =>
            select( abilitiesStore ).getAbilityCategory( 'data-retrieval' ),
        []
    );

    return (
        <div>
            <h2>All Abilities ({ allAbilities.length })</h2>
            <h2>Categories ({ categories.length })</h2>
            <ul>
                { categories.map( ( category ) => (
                    <li key={ category.slug }>
                        <strong>{ category.label }</strong>:{ ' ' }
                        { category.description }
                    </li>
                ) ) }
            </ul>
            <h2>{ dataCategory?.label } Abilities</h2>
            <ul>
                { dataAbilities.map( ( ability ) => (
                    <li key={ ability.name }>{ ability.label }</li>
                ) ) }
            </ul>
        </div>
    );
}

为此包做出贡献

这是 Gutenberg 项目的一个独立包。该项目组织为一个单体仓库（monorepo）。它由多个自包含的软件包组成，每个包都有特定的用途。此单体仓库中的包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主要贡献者指南。

@wordpress/abilities

目录

安装