@wordpress/commands

Commands 是一个通用包，允许注册和修改命令以通过命令菜单（也称为命令面板）显示。可以使用 cmd+k 在编辑器中访问命令面板。

命令类型

有两种注册命令的方式：静态或动态。两种方法都将命令对象作为参数接收，该对象提供：

• name：命令的唯一机器可读名称
• label：人类可读的标签
• icon：SVG 图标
• callback：当选择命令时调用的回调函数
• category：（可选）命令的类别。参见下面的“命令类别”
• context：（可选）命令的上下文
• keywords：（可选）用于搜索匹配的关键词数组

静态命令

可以使用 wp.data.dispatch( wp.commands.store ).registerCommand 操作或使用 wp.commands.useCommand React 钩子来注册静态命令。静态命令通常用于执行特定操作。这些操作可能包括添加新页面或打开编辑器界面的某个部分，例如打开编辑器首选项模态框。参见下面的 useCommand 代码示例。

动态命令

另一方面，动态命令是使用“命令加载器” wp.commands.useCommandLoader 注册的。当命令列表取决于用户在命令面板输入中输入的搜索词，或者某些命令仅在满足某些条件时才可用时，需要这些加载器。

例如，当用户键入“contact”时，命令面板需要使用该输入来过滤可用页面，以尝试找到“Contact”页面。参见下面的 useCommandLoader 代码示例。

上下文命令

静态和动态命令都可以具有上下文。这意味着在给定上下文中（例如，在导航站点编辑器或编辑模板时），某些特定命令具有更高的优先级，并且在打开命令面板时会立即可见。此外，在键入命令面板时，这些上下文命令会显示在其他命令之上。

目前，已实现三种上下文：

• site-editor：这是在您导航站点编辑器（侧边栏可见）时设置的上下文。
• entity-edit：这是在您编辑文档（模板、模板片段或页面）时设置的上下文。
• block-selection-edit：这是在选中块时设置的上下文。

随着命令面板的使用范围扩大，将添加更多上下文。

将命令或命令加载器附加到给定上下文就像在 useCommand 或 useCommandLoader 调用中添加 context 属性（使用上述可用上下文中的正确上下文值）一样简单。

命令类别

每个命令都可以分配一个 category，描述它执行的操作类型。命令类别用于在视觉上区分命令。以下类别可用：

• command：执行代码或切换命令（例如，添加块、复制块）。
• view：导航到管理区域或打开面板（例如，“转到：模板”）。
• edit：导航以编辑文档（例如，编辑模板、编辑页面）。
• action：不适合其他类别的命令的通用回退。这也是在提供无效类别时的默认值。

如果未指定 category，则命令将设置为 action。如果提供了无效值，则在开发模式下会发出警告，并且类别默认为 action。

类别还可以提供回退图标，当命令未传递自己的 icon 时使用：view 回退为箭头，以便在整个面板中导航的读取方式保持一致。该类别中的命令应依赖回退而不是传递图标，除非其自身的图标传达了箭头无法传达的内容，例如打开新标签页。

WordPress Data API

命令面板还提供了一系列 选择器和操作 来操纵其状态，其中包括：

• 使用以下选择器 getCommands 和 getCommandLoader 检索已注册的命令和命令加载器
• 使用 isOpen 选择器检查命令面板是否打开。
• 使用 open 和 close 操作以编程方式打开或关闭命令面板。

有关更多信息，请参阅 Commands Data 文档。

安装

安装模块

npm install @wordpress/commands --save

此包假设您的代码将在 ES2015+ 环境中运行。如果您使用的是对这类语言特性和 API 支持有限或完全不支持的环境，您应该包含 @wordpress/babel-preset-default 随附的 polyfill。

此包要求包含以下样式表以正确设置样式：

/* From node_modules: */
@import '@wordpress/components/build-style/style.css';
@import '@wordpress/commands/build-style/style.css';

API

store

命令命名空间的存储定义。

相关

• https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

用法

import { store as commandsStore } from '@wordpress/commands';
import { useDispatch } from '@wordpress/data';
...
const { open: openCommandCenter } = useDispatch( commandsStore );

类型

• Object

useCommand

将命令附加到命令面板。用于静态命令。

用法

import { useCommand } from '@wordpress/commands';
import { plus } from '@wordpress/icons';

useCommand( {
    name: 'myplugin/my-command-name',
    label: __( 'Add new post' ),
    icon: plus,
    category: 'command',
    callback: ( { close } ) => {
        document.location.href = 'post-new.php';
        close();
    },
} );

参数

• command import('../store/actions').WPCommandConfig：命令配置。

useCommandLoader

将命令加载器附加到命令面板。用于动态命令。

面板始终调用最新的 hook。更改 hook 实例不会重新渲染面板。

用法

import { __ } from '@wordpress/i18n';
import { addQueryArgs } from '@wordpress/url';
import { useCommandLoader } from '@wordpress/commands';
import { page } from '@wordpress/icons';
import { useSelect } from '@wordpress/data';
import { store as coreStore } from '@wordpress/core-data';
import { useMemo } from '@wordpress/element';

function usePageSearchCommandLoader( { search } ) {
    // Retrieve the pages for the "search" term.
    const { records, isLoading } = useSelect(
        ( select ) => {
            const { getEntityRecords } = select( coreStore );
            const query = {
                search: !! search ? search : undefined,
                per_page: 10,
                orderby: search ? 'relevance' : 'date',
            };
            return {
                records: getEntityRecords( 'postType', 'page', query ),
                isLoading: ! select( coreStore ).hasFinishedResolution(
                    'getEntityRecords',
                    [ 'postType', 'page', query ]
                ),
            };
        },
        [ search ]
    );

    // Create the commands.
    const commands = useMemo( () => {
        return ( records ?? [] ).slice( 0, 10 ).map( ( record ) => {
            return {
                name: record.title?.rendered + ' ' + record.id,
                label: record.title?.rendered
                    ? record.title?.rendered
                    : __( '(no title)' ),
                icon: page,
                category: 'edit',
                callback: ( { close } ) => {
                    const args = {
                        p: '/page',
                        postId: record.id,
                    };
                    document.location = addQueryArgs( 'site-editor.php', args );
                    close();
                },
            };
        } );
    }, [ records ] );

    return {
        commands,
        isLoading,
    };
}

useCommandLoader( {
    name: 'myplugin/page-search',
    hook: usePageSearchCommandLoader,
} );

参数

• loader import('../store/actions').WPCommandLoaderConfig：命令加载器配置。

useCommands

将多个命令附加到命令面板。用于静态命令。

用法

import { useCommands } from '@wordpress/commands';
import { plus, pencil } from '@wordpress/icons';

useCommands( [
    {
        name: 'myplugin/add-post',
        label: __( 'Add new post' ),
        icon: plus,
        category: 'command',
        callback: ( { close } ) => {
            document.location.href = 'post-new.php';
            close();
        },
    },
    {
        name: 'myplugin/edit-posts',
        label: __( 'Edit posts' ),
        icon: pencil,
        category: 'view',
        callback: ( { close } ) => {
            document.location.href = 'edit.php';
            close();
        },
    },
] );

参数

• commands import('../store/actions').WPCommandConfig[]: 命令配置数组。

为此包做出贡献

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

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