automattic/jetpack-wp-js-data-sync

一个用于设置REST API和脚本本地化,以便将数据传递给JavaScript客户端的软件包。

安装量: 1,968

依赖项: 0

建议者: 0

安全: 0

星标: 2

关注者: 4

分支: 1

类型:jetpack-library

v0.5.0 2024-08-29 08:39 UTC

This package is auto-updated.

Last update: 2024-09-18 03:17:54 UTC


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(或更新版)许可。