@wordpress/首选项

应用程序首选项的键/值存储。

安装

安装模块

npm install@wordpress/preferences--保存

此包假定您的代码将在2015年欧洲标准+环境。如果您使用的环境对此类语言功能和API的支持有限或不支持，那么您应该包括polyfill发货@wordpress/babel预设在代码中。

关键概念

范围

许多API调用都需要类似于命名空间的“scope”参数。如果有多个参数具有相同的键，但它们应用于应用程序的不同部分，则使用范围是隔离它们的最佳方法。

钥匙

每个首选项都针对一个应该是字符串的键进行设置。

价值

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

默认值

默认值是当首选项为未定义。这些不是持久化的，它们只保存在内存中。它们应该在应用程序初始化期间。

示例

数据存储

通过调度操作为初始化时的任何功能设置默认首选项：

从“@wordpress/data”导入{dispatch}；从“@wordpress/preferences”导入{store as preferencesStore}；函数initialize（）{// ...分派（preferencesStore）.setDefaults(“namespace/editor-or-plugin-name”，{myBooleanFeature:真的，});// ...}

使用得到选择器以获取首选项值设置更新首选项的操作：

wp数据.select（'核心/首选项'）.get（'namespace/editor-or-plugin-name'，'myPreferenceName'）；//1wp.数据.dispatch（“核心/首选项”）.set（“namespace/editor-or-plugin-name”，“myPreferenceName”，2）；wp.数据.select（“核心/首选项”）.get（'namespace/editor-or-plugin-name'，'myPreferenceName'）；//2

使用切换在以下对象之间翻转布尔首选项的操作真的和假:

wp.数据.select（'核心/首选项'）.get（'namespace/editor-or-plugin-name'，'myPreferenceName'）；//真的wp数据.dispatch（“核心/首选项”）.togle（“namespace/editor-or-plugin-name”，“myPreferenceName”）；wp.数据.select（'核心/首选项'）.get（'namespace/editor-or-plugin-name'，'myPreferenceName'）；//假

设置持久层

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

使用setPersistenceLayer（设置持久层）配置商店如何保持其首选项值的操作。

wp.data.dispatch（'core/preferences'）.setPersistenceLayer（{//“get”是异步的，可以使用REST API支持持久化首选项。//它将立即被“setPersistenceLayer”调用，并返回//值用作首选项的初始状态。异步获取（）{return JSON.parse（window.localStorage.getItem（'MY_PREFERENCES'））；},//“set”是同步的。可以使用异步代码，但//首选项存储不会等待承诺解决，功能是//“点燃并忘却”。集合（首选项）{window.local存储.setItem('我的引用'，JSON.stringify（首选项）);},} );

对于将数据持久化到异步API的应用程序，一个问题是加载首选项可能会导致应用程序启动速度较慢。

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

注：目前得到仅在以下情况下调用setPersistenceLayer（设置持久层）已触发。这在未来可能会改变，因此优化是明智的得到使用本地缓存，如下例所示。

//从服务器预加载数据。let cache=预加载数据；wp.data.dispatch（'core/preferences'）.setPersistenceLayer（{异步获取（）{if（缓存）{返回缓存；}//调用自制的异步API。return waiting api.preferences.get（）；},设置（首选项）{cache=首选项；api.preferences.set（{data:preferences}）；},} );

组件

这个首选项切换菜单项组件可以与下拉菜单以实现用于改变偏好的菜单。

函数MyEditorMenu（）{返回(<下拉菜单>{ () => (<菜单组标签={__（“功能”）}><首选项切换菜单项scope=“namespace/editor-or-plugin-name”name=“myPreferenceName”label={__（'我的功能'）}info={__（'一个非常棒的功能'）}messageActivated={__（'我的功能已激活'）}messageDeactivated={__（'我的功能已停用'）}/></MenuGroup（菜单组）>) }</DropdownMenu>);}

API参考

行动

以下调度操作创建者集可用于返回的对象wp.data.dispatch（“核心/首选项”）:

设置

返回用于发出应将首选项设置为值的信号的操作对象

参数

• 范围 一串：首选范围（例如core/edit-post）。
• 名称 一串：首选项名称。
• 价值 *：要设置的值。

退换商品

• 对象：Action对象。

设置默认值

返回用于发出应设置首选项默认值的信号的操作对象。

参数

• 范围 一串：首选范围（例如core/edit-post）。
• 默认值 对象<string，*>：首选项名称到值的键/值映射。

退换商品

• 对象：Action对象。

setPersistenceLayer（设置持久层）

设置持久层。

设置持久层后，首选项存储将：

• 呼叫得到立即将存储状态更新为返回的值。
• 呼叫设置当首选项更改值时，使用所有首选项。

setPersistenceLayer（设置持久层）理想情况下，应该在应用程序生命周期开始时，在将任何其他操作发送到首选项存储之前进行发送。

参数

• 持久层 工作包首选项持久性层：持久层。

退换商品

• 对象：Action对象。

切换

返回用于发出应切换首选项的信号的操作对象。

参数

• 范围 一串：首选范围（例如core/edit-post）。
• 名称 一串：首选项名称。

选择器

返回的对象上有以下选择器wp.data.select（“核心/首选项”）:

得到

返回一个布尔值，指示首选项对于特定范围是否处于活动状态。

参数

• 状态 对象：存储状态。
• 范围 一串：功能范围（例如核心/编辑-发布）。
• 名称 一串：功能的名称。

退换商品

• *：该功能是否已启用？

参与此包

这是古腾堡项目的一部分。该项目组织为单回购。它由多个独立的软件包组成，每个软件包都有特定的用途。此monorepo中的包发布到净现值法并由使用WordPress（文字出版社）以及其他软件项目。

要了解更多关于对这个包或古腾堡整体贡献的信息，请阅读该项目的主要内容贡献者指南.