first commit

2025-10-22 01:33:45 +08:00
commit 2080fa3878
251 changed files with 47081 additions and 0 deletions
--- a/how-to-guides/widgets/README.md
+++ b/how-to-guides/widgets/README.md
@@ -0,0 +1,9 @@
+# 小工具
+
+Gutenberg插件将WP管理后台中的小工具编辑器界面替换为基于WordPress区块编辑器的全新界面。
+
+**目录**
+
+- [小工具区块编辑器概述](/docs/how-to-guides/widgets/overview.md)
+- [恢复旧版小工具编辑器](/docs/how-to-guides/widgets/opting-out.md)
+- [确保与旧版小工具区块的兼容性](/docs/how-to-guides/widgets/legacy-widget-block.md)
--- a/how-to-guides/widgets/legacy-widget-block.md
+++ b/how-to-guides/widgets/legacy-widget-block.md
@@ -0,0 +1,188 @@
+# 关于传统小工具区块
+
+传统小工具区块允许用户添加、编辑和预览由插件注册的第三方小工具，以及使用经典小工具编辑器添加的小工具。
+
+可通过区块插入器添加传统小工具区块，并从该区块的下拉菜单中选择小工具来添加第三方小工具。
+
+也可通过在区块插入器中搜索小工具名称并选择该小工具来添加第三方小工具。系统将插入一个传统小工具区块的变体。
+
+## 与传统小工具区块的兼容性
+
+### `widget-added` 事件
+
+传统小工具区块将以类似于定制器的方式显示小工具的表单，因此与大多数第三方小工具兼容。
+
+如果小工具在其表单中使用 JavaScript，则必须在 `document` 上触发 `'widget-added'` jQuery 事件后，将事件添加到 DOM 中。
+
+例如，当“更改密码”复选框被勾选时，小工具可能希望显示一个“密码”字段。
+
+```js
+( function ( $ ) {
+	$( document ).on( 'widget-added', function ( $event, $control ) {
+		$control.find( '.change-password' ).on( 'change', function () {
+			var isChecked = $( this ).prop( 'checked' );
+			$control.find( '.password' ).toggleClass( 'hidden', ! isChecked );
+		} );
+	} );
+} )( jQuery );
+```
+
+请注意，所有小工具的事件处理程序都在 `widget-added` 回调中添加。
+
+### 显示“无预览可用”
+
+当未选择传统小工具区块时，该区块将显示小工具的预览。
+
+当小工具的 `widget()` 函数未呈现任何内容或仅呈现空的 HTML 元素时，传统小工具区块会自动显示“无预览可用”的消息。
+
+小工具可以通过在不应显示预览时从 `widget()` 提前返回来利用这一点。
+
+```php
+class ExampleWidget extends WP_Widget {
+	...
+	public function widget( $instance ) {
+		if ( ! isset( $instance['name'] ) ) {
+			// 名称为必填项，如果没有则什么都不显示。
+			return;
+		}
+		?>
+		<h3>名称：<?php echo esc_html( $instance['name'] ); ?></h3>
+		...
+		<?php
+	}
+	...
+}
+```
+
+### 允许迁移到区块
+
+您可以允许用户轻松将包含特定小工具的传统小工具区块迁移到一个或多个区块。这使得插件作者可以逐步淘汰他们的小工具，转而使用更直观且可以在更多地方使用的区块。
+
+以下步骤展示了如何实现这一点。
+
+#### 1) 在 REST API 中显示小工具的实例
+
+首先，我们需要告诉 WordPress 允许在 REST API 中显示您的小工具的实例数组。
+
+如果满足以下条件，则可以安全地执行此操作：
+
+-   您知道小工具在 `$instance` 中存储的所有值都可以用 JSON 表示；并且
+-   您知道小工具没有在 `$instance` 中存储任何应对具有站点定制权限的用户隐藏的私有数据。
+
+如果这样做是安全的，则在注册小工具时包含一个名为 `show_instance_in_rest` 的小工具选项，并将其值设置为 `true`。
+
+```php
+class ExampleWidget extends WP_Widget {
+	...
+	/**
+	 * 设置小工具
+	 */
+	public function __construct() {
+		$widget_ops = array(
+			// ...其他选项
+			'show_instance_in_rest' => true,
+			// ...其他选项
+		);
+		parent::__construct( 'example_widget', 'ExampleWidget', $widget_ops );
+	}
+	...
+}
+```
+
+这允许区块编辑器和其他 REST API 客户端通过访问 REST API 响应中的 `instance.raw` 来查看您的小工具的实例数组。
+
+请注意，[WordPress 5.8.0 之前的版本允许您通过在扩展 `WP_Widget` 的类中将 `$show_instance_in_rest` 设置为 `true`](https://core.trac.wordpress.org/ticket/53332) 来启用此功能。
+
+```php
+class ExampleWidget extends WP_Widget {
+	...
+	public $show_instance_in_rest = true;
+	...
+}
+```
+
+现在已不推荐使用此方法，建议改用小工具选项方法。
+
+#### 2) 添加区块转换
+
+现在，我们可以定义一个[区块转换](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-transforms/)，告诉区块编辑器用什么替换包含您小工具的传统小工具区块。
+
+这是通过向区块定义中添加 JavaScript 代码来实现的。在此示例中，我们定义了一个转换，将 ID 为 `'example_widget'` 的小工具转换为名称为 `'example/block'` 的区块。
+
+```js
+transforms: {
+	from: [
+		{
+			type: 'block',
+			blocks: [ 'core/legacy-widget' ],
+			isMatch: ( { idBase, instance } ) => {
+				if ( ! instance?.raw ) {
+					// 如果原始实例未在 REST API 中显示，则无法转换。
+					return false;
+				}
+				return idBase === 'example_widget';
+			},
+			transform: ( { instance } ) => {
+				return createBlock( 'example/block', {
+					name: instance.raw.name,
+				} );
+			},
+		},
+	]
+},
+```
+
+#### 3) 在传统小工具区块中隐藏小工具
+
+最后，我们可以告诉传统小工具区块在“选择小工具”下拉列表和区块插入器中隐藏您的小工具。这鼓励用户使用替换您小工具的区块。
+
+可以使用 `widget_types_to_hide_from_legacy_widget_block` 过滤器来实现这一点。
+
+```php
+function hide_example_widget( $widget_types ) {
+	$widget_types[] = 'example_widget';
+	return $widget_types;
+}
+add_filter( 'widget_types_to_hide_from_legacy_widget_block', 'hide_example_widget' );
+```
+
+## 在其他区块编辑器中使用传统小工具区块（高级）
+
+您可以选择允许在其他区块编辑器（例如 WordPress 文章编辑器）中使用传统小工具区块。默认情况下，此功能未启用。
+
+首先，确保页面上加载了传统小工具所需的任何样式和脚本。一种便捷的方法是手动执行用户浏览小工具 WP 管理屏幕时通常运行的所有钩子。
+
+```php
+add_action( 'admin_print_styles', function() {
+	if ( get_current_screen()->is_block_editor() ) {
+		do_action( 'admin_print_styles-widgets.php' );
+	}
+} );
+add_action( 'admin_print_scripts', function() {
+	if ( get_current_screen()->is_block_editor() ) {
+		do_action( 'load-widgets.php' );
+		do_action( 'widgets.php' );
+		do_action( 'sidebar_admin_setup' );
+		do_action( 'admin_print_scripts-widgets.php' );
+	}
+} );
+add_action( 'admin_print_footer_scripts', function() {
+	if ( get_current_screen()->is_block_editor() ) {
+		do_action( 'admin_print_footer_scripts-widgets.php' );
+	}
+} );
+add_action( 'admin_footer', function() {
+	if ( get_current_screen()->is_block_editor() ) {
+		do_action( 'admin_footer-widgets.php' );
+	}
+} );
+```
+
+然后，使用 `@wordpress/widgets` 包中定义的 `registerLegacyWidgetBlock` 注册传统小工具区块。
+
+```php
+add_action( 'enqueue_block_editor_assets', function() {
+	wp_enqueue_script( 'wp-widgets' );
+	wp_add_inline_script( 'wp-widgets', 'wp.widgets.registerLegacyWidgetBlock()' );
+} );
+```
--- a/how-to-guides/widgets/opting-out.md
+++ b/how-to-guides/widgets/opting-out.md
@@ -0,0 +1,44 @@
+# 恢复经典小工具编辑器
+
+有多种方法可以禁用新的小工具区块编辑器。
+
+## 使用 `remove_theme_support`
+
+主题可以通过调用 `remove_theme_support( 'widgets-block-editor' )` 来禁用小工具区块编辑器。
+
+例如，主题可以在 `functions.php` 文件中添加以下 PHP 代码：
+
+```php
+function example_theme_support() {
+	remove_theme_support( 'widgets-block-editor' );
+}
+add_action( 'after_setup_theme', 'example_theme_support' );
+```
+
+## 使用经典小工具插件
+
+最终用户可以通过安装并激活[经典小工具插件](https://wordpress.org/plugins/classic-widgets/)来禁用小工具区块编辑器。
+
+安装此插件后，可以通过停用和激活插件来切换小工具区块编辑器的开关状态。
+
+## 使用过滤器
+
+`use_widgets_block_editor` 过滤器用于控制是否启用小工具区块编辑器。
+
+例如，网站管理员可以在 Must-Use 插件中添加以下 PHP 代码来禁用小工具区块编辑器：
+
+```php
+add_filter( 'use_widgets_block_editor', '__return_false' );
+```
+
+对于更高级的用法，您可以提供自定义函数。以下示例展示了如何为特定用户禁用小工具区块编辑器：
+
+```php
+function example_use_widgets_block_editor( $use_widgets_block_editor ) {
+	if ( 123 === get_current_user_id() ) {
+		return false;
+	}
+	return $use_widgets_block_editor;
+}
+add_filter( 'use_widgets_block_editor', 'example_use_widgets_block_editor' );
+```
--- a/how-to-guides/widgets/overview.md
+++ b/how-to-guides/widgets/overview.md
@@ -0,0 +1,31 @@
+# 小工具区块编辑器概述
+
+## 小工具区块编辑器
+
+全新小工具编辑器是WordPress的一项功能升级，它将小工具区域升级为支持区块与小工具并存使用。这项功能通过大家熟悉的WordPress区块编辑器，提供了全新小工具管理体验。
+
+您可以通过访问外观→小工具或外观→自定义→小工具并选择小工具区域，来使用全新小工具编辑器。
+
+小工具区块编辑器允许您通过独立编辑器或自定义器，将区块和小工具插入当前启用主题定义的任意[小工具区域或侧边栏](https://developer.wordpress.org/themes/functionality/sidebars/)。
+
+### 自定义器小工具区块编辑器
+
+全新小工具编辑器同时取代了自定义器中的小工具版块，采用基于区块的全新编辑器。
+
+您可以通过访问外观→自定义，选择小工具，然后选择小工具区域来使用自定义器小工具区块编辑器。
+
+通过自定义器使用全新小工具编辑器不仅支持将区块和小工具插入选定的小工具区域，还能利用编辑器右侧的实时预览功能，以及所有其他自定义器专属功能（如变更排程与共享）。
+
+## 兼容性
+
+在新版小工具编辑器推出前已添加到小工具区域的传统小工具，将通过传统小工具区块继续正常工作。
+
+传统小工具区块作为兼容机制，允许我们在基于区块的全新小工具编辑器中编辑和预览传统小工具的变更。
+
+通过插件注册的第三方小工具仍可通过添加和设置传统小工具区块，插入到小工具区域中。
+
+小工具编辑器使用用户不可见的底层“区块”小工具来存储区块数据。这意味着插件和主题将继续正常工作，且停用小工具区块编辑器不会造成任何数据丢失。
+
+主题可通过`remove_theme_support( 'widgets-block-editor' )`代码禁用小工具区块编辑器。
+
+用户可通过安装[经典小工具插件](https://wordpress.org/plugins/classic-widgets/)来禁用小工具区块编辑器。