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

一个用于应用偏好设置的键/值存储。

安装

安装模块

npm install @wordpress/preferences --save

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

核心概念

作用域

许多 API 调用需要一个作为命名空间的 “scope” 参数。如果你有多个使用相同键但应用于应用不同部分的参数，使用作用域是隔离它们的最佳方式。

键

每个偏好设置都对应一个键，该键应为字符串。

值

值可以是任意类型，但受配置的持久化层限制，支持的类型可能有限。例如，如果偏好设置以 JSON 格式保存到浏览器的 localStorage，则只应使用可 JSON 序列化的类型。

默认值

默认值是当偏好设置为 undefined 时返回的值。这些值不会被持久化，只会保存在内存中。它们应在应用初始化期间设置。

示例

数据存储

通过在初始化时派发一个动作来设置任何功能的默认偏好设置：

import { dispatch } from '@wordpress/data';
import { store as preferencesStore } from '@wordpress/preferences';

function initialize() {
    // ...

    dispatch( preferencesStore ).setDefaults(
        'namespace/editor-or-plugin-name',
        {
            myBooleanFeature: true,
        }
    );

    // ...
}

使用 get 选择器获取偏好设置值，并使用 set 动作更新偏好设置：

wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 1
wp.data
    .dispatch( 'core/preferences' )
    .set( 'namespace/editor-or-plugin-name', 'myPreferenceName', 2 );
wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 2

使用 toggle 动作在 true 和 false 之间切换布尔偏好设置：

wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // true
wp.data
    .dispatch( 'core/preferences' )
    .toggle( 'namespace/editor-or-plugin-name', 'myPreferenceName' );
wp.data
    .select( 'core/preferences' )
    .get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // false

设置持久化层

默认情况下，此包仅在内存中存储值。但可以通过可选的持久化层将偏好设置持久化到浏览器存储或数据库。

使用 setPersistenceLayer 动作配置 store 如何持久化其偏好设置值。

wp.data.dispatch( 'core/preferences' ).setPersistenceLayer( {
    // `get` 是异步的，以支持使用 REST API 持久化偏好设置。
    // 它会立即被 `setPersistenceLayer` 调用，返回的
    // 值将用作偏好设置的初始状态。
    async get() {
        return JSON.parse( window.localStorage.getItem( 'MY_PREFERENCES' ) );
    },

    // `set` 是同步的。可以使用异步代码，但
    // preferences store 不会等待 promise resolve，该函数是
    // “触发后不管”的。
    set( preferences ) {
        window.localStorage.setItem(
            'MY_PREFERENCES',
            JSON.stringify( preferences )
        );
    },
} );

对于将数据持久化到异步 API 的应用，一个担忧是加载偏好设置可能导致应用启动变慢。

建议预加载持久化层数据并将其保存在本地缓存中，特别是在使用异步 API 持久化数据时。

注意：目前 get 仅在触发 setPersistenceLayer 时调用。未来可能会更改，因此使用本地缓存优化 get 是合理的，如下面的示例所示。

// 从服务器预加载的数据。
let cache = preloadedData;
wp.data.dispatch( 'core/preferences' ).setPersistenceLayer( {
    async get() {
        if ( cache ) {
            return cache;
        }

        // 调用一个虚构的异步 API。
        return await api.preferences.get();
    },
    set( preferences ) {
        cache = preferences;
        api.preferences.set( { data: preferences } );
    },
} );

组件

PreferenceToggleMenuItem 组件可以与 DropdownMenu 一起使用，以实现用于更改偏好设置的菜单。

function MyEditorMenu() {
    return (
        <DropdownMenu>
            { () => (
                <MenuGroup label={ __( 'Features' ) }>
                    <PreferenceToggleMenuItem
                        scope="namespace/editor-or-plugin-name"
                        name="myPreferenceName"
                        label={ __( 'My feature' ) }
                        info={ __( 'A really awesome feature' ) }
                        messageActivated={ __( 'My feature activated' ) }
                        messageDeactivated={ __( 'My feature deactivated' ) }
                    />
                </MenuGroup>
            ) }
        </DropdownMenu>
    );
}

API 参考

动作

在 wp.data.dispatch( 'core/preferences' ) 返回的对象上，可以使用以下一组可派发的动作创建器：

set

返回一个动作对象，用于表示应将某个偏好设置为指定值。

参数

scope string：偏好设置作用域（例如 core/edit-post）。
name string：偏好设置名称。
value *：要设置的值。

SetAction：动作对象。

setDefaults

返回一个动作对象，用于表示应设置偏好设置默认值。

参数

scope string：偏好设置作用域（例如 core/edit-post）。
defaults ScopedDefaults：偏好设置名称到值的键/值映射。

SetDefaultsAction：动作对象。

setPersistenceLayer

设置持久化层。

设置持久化层后，偏好设置 store 将：

立即调用 get，并将 store 状态更新为返回的值。
在任一偏好设置值发生变化时，使用所有偏好设置调用 set。

理想情况下，setPersistenceLayer 应在应用生命周期开始时派发，并且在向偏好设置 store 派发任何其他动作之前。

参数

persistenceLayer WPPreferencesPersistenceLayer< D >：持久化层。

Promise< SetPersistenceLayerAction< D > >：动作对象。

toggle

返回一个动作对象，用于表示应切换某个偏好设置。

参数

scope string：偏好设置作用域（例如 core/edit-post）。
name string：偏好设置名称。

选择器

在 wp.data.select( 'core/preferences' ) 返回的对象上，可以使用以下选择器：

get

返回一个布尔值，指示某个作用域中的偏好设置是否处于激活状态。

参数

state StoreState：store 状态。
scope string：功能的作用域（例如 core/edit-post）。
name string：功能名称。

*：该功能是否启用？

为此包做贡献

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

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