automattic / jetpack-wp-js-data-sync
一个用于设置REST API和脚本本地化,以便将数据传递给JavaScript客户端的软件包。
Requires
- php: >=7.0
- automattic/jetpack-schema: ^0.1.1
Requires (Dev)
- automattic/jetpack-changelogger: ^4.2.6
- automattic/wordbless: dev-master
- yoast/phpunit-polyfills: ^1.1.1
Suggests
- automattic/jetpack-autoloader: Allow for better interoperability with other plugins that use this package.
README
调试
WP JS DataSync会监听ds-debug-disable
GET参数来禁用某些DataSync值。
要禁用特定的DataSync值,请将?ds-debug-disable=<entry-key>
添加到URL。要禁用所有数据同步值,请将?ds-debug-disable=all
添加到URL。
调试示例
如果您的仪表板URL是https://example.com/wp-admin/admin.php?page=example
,并且您想禁用widget_status
值,您将导航到https://example.com/wp-admin/admin.php?page=example?ds-debug-disable=widget_status
。
过时文档
WP JS Data Sync是一个库,旨在帮助在WordPress和后台仪表板中的JavaScript之间同步数据。
这有助于创建一种简化的方式,将数据从WordPress后端传递到JavaScript,并且
- 明确说明可用的选项
- 确保任何必要的转换/验证/清理操作在可预测的时间执行
- 在页面加载时以结构化方式将数据传递到前端
- 自动生成REST API CRUD端点,供前端JavaScript使用
- 为每个注册条目自动设置nonce
- 与前端库(如Zod)集成,以提供类型安全的数据同步
此软件包目前与@jetpack/js-packages/svelte-data-sync-client
软件包一起使用,但将来可以扩展以与其他库一起工作。
使用概述
将软件包集成到您的插件后,新条目的典型设置如下所示
// Register the entries in the plugin: plugin_name_register_entry( 'widget_status', Schema::as_boolean() ); plugin_name_register_entry( 'widget_title', Schema::as_string() ); // Somewhere, where the data is needed, get the data: $status = plugin_name_get_entry( 'widget_status' ); $title = plugin_name_get_entry( 'widget_title' );
这将通过wp_localize_script
将必要的数据传递到admin-page脚本
// The data is available in the `window.plugin_name` global variable. window.plugin_name = { rest_api: { nonce: '1234567890', value: 'https://example.com/wp-json', }, widget_status: { value: true, nonce: '1234567890', }, widget_title: { value: 'My Widget', nonce: '1234567890', }, widget_text: { value: 'This is my widget', nonce: '1234567890', } }
还将创建一个可以用于更新数据的REST API端点
// GET, POST: /wp-json/plugin-name/widget-status
// POST: /wp-json/plugin-name/widget-status/set
// POST, DELETE: /wp-json/plugin-name/widget-status/delete
要更新数据,您可以提交一个fetch请求,并传递WordPress REST API nonce和特定条目的nonce
// Update the widget title: const req = fetch( 'https://example.com/wp-json/plugin-name/widget-status/set', { method: 'POST', headers: { 'X-WP-Nonce': window.plugin_name.rest_api.nonce, 'X-Jetpack-WP-JS-Sync-Nonce': window.plugin_name.widget_status.nonce, }, body: JSON.stringify( { 'JSON': 'This is a title', } ), } ); const response = await req.json();
响应将如下所示
{ "status": "success", "JSON": "This is a title", }
为了便于在Svelte中使用,有一个@jetpack/js-packages/svelte-data-sync-client
软件包,它提供了一个Svelte存储,可以用于与数据交互。
设置
步骤1:初始化仪表板的数据同步
Data_Sync
类负责初始化并简化Admin仪表板的设置。
初始化数据同步并传递有关admin环境的数据。这只需要在每个$namespace
中做一次,并将附加所有必要的钩子。
function plugin_name_initialize_datasync() { $data_sync = Data_Sync::get_instance( JETPACK_BOOST_DATASYNC_NAMESPACE ); // attach_to_plugin( $script_handle, $plugin_page_hook ); $data_sync->attach_to_plugin( 'plugin-name-admin', 'jetpack_page_plugin-name' ); } // This only needs to happen in the Admin Dashboard: add_action( 'admin_init', 'plugin_name_initialize_datasync' );
步骤2:注册条目
现在我们已设置好了两个处理器,我们可以将它们注册到Data Sync注册表中。
一个简单示例
$registry = Registry::get_instance( 'jetpack_favorites' ); $registry->register( 'enabled', Schema::as_boolean() );
一个更复杂的示例
默认存储是使用Data_Sync_Option
类实现的wp_options
,但有时您可能想要自定义它。
以下是一个示例,说明如何使Data Sync使用WordPress帖子而不是WP选项
class Favorite_Posts implements Entry_Can_Get { public function get() { $posts = array_map( 'get_post', $value ); return array_filter( $posts, function( $post ) { return $post instanceof WP_Post; } ); return $posts; } }
步骤3:使用
现在条目已注册,就像在使用部分中一样,您可以通过REST API或条目对象与数据交互。
// GET, POST: /wp-json/jetpack-favorites/enabled
// POST: /wp-json/jetpack-favorites/enabled/set
// POST, DELETE: /wp-json/jetpack-favorites/enabled/delete
// GET: /wp-json/jetpack-favorites/favorite-posts
或通过PHP中的条目对象更改值
$entry = Registry::get_instance( 'jetpack_favorites' )->get_entry( 'enabled' ); $entry->set( true );
提供给$entry->set()
的值在保存之前将始终由模式进行验证。
实用工具
如果您需要在多个地方使用这些数据,设置辅助函数可能会让您使用起来更方便。
function jetpack_favorites() { return Registry::get_instance( 'jetpack_favorites' ); } function jetpack_favorites_get( $key ) { $entry = jetpack_favorites()->get_entry( $key ); return $entry->get(); } function jetpack_favorites_set( $key, $value ) { $entry = jetpack_favorites()->get_entry( $key ); return $entry->set( $value ); }
在您的WordPress插件中使用此包
如果您计划在WordPress插件中使用此包,我们建议您使用Jetpack Autoloader作为自动加载器。这将允许与其他使用此包的插件实现最大兼容性。
安全
需要报告安全漏洞?请访问https://automattic.com/security/或直接访问我们的安全漏洞赏金网站https://hackerone.com/automattic。
许可协议
WP JS Data Sync遵循GNU通用公共许可证v2(或更新版)许可。