docs

docs/how-to-guides/notices/README.md

@@ -0,0 +1,82 @@
+# 通知
+
+通知是显示在管理页面顶部附近的信息性用户界面元素。WordPress核心程序、主题和插件都使用通知来指示操作结果，或吸引用户关注必要信息。
+
+在经典编辑器中，挂接到`admin_notices`操作的通知可以渲染任意HTML内容。而在区块编辑器中，通知则受限于更规范的API。
+
+## 经典编辑器中的通知
+
+在经典编辑器中，"文章草稿已更新"通知的示例如下：
+
+![经典编辑器中的文章草稿更新通知](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/notices/classic-editor-notice.png)
+
+生成等效的"文章草稿已更新"通知需要如下代码：
+
+```php
+/**
+ * 挂接到'admin_notices'操作来渲染
+ * 通用HTML通知。
+ */
+function myguten_admin_notice() {
+	$screen = get_current_screen();
+	// 仅在文章编辑器中显示此通知。
+	if ( ! $screen || 'post' !== $screen->base ) {
+		return;
+	}
+	// 渲染通知的HTML内容。
+	wp_admin_notice(
+		sprintf( __( '文章草稿已更新。<a href="%s" target="_blank">预览文章</a>' ), get_preview_post_link() ),
+		array(
+			'type'        => 'success',
+			'dismissible' => true,
+		)
+	);
+};
+add_action( 'admin_notices', 'myguten_admin_notice' );
+```
+
+重要的是，`admin_notices`钩子允许开发者渲染任意HTML内容。这样做的主要优势是开发者拥有极大的灵活性。关键劣势在于，任意HTML使得通知功能的后续迭代更加困难（甚至不可能），因为迭代需要兼容各种任意HTML。这就是区块编辑器采用规范API的原因。
+
+## 区块编辑器中的通知
+
+在区块编辑器中，"文章已发布"通知的示例如下：
+
+![区块编辑器中的文章发布通知](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/how-to-guides/notices/block-editor-notice.png)
+
+生成等效的"文章已发布"通知需要如下代码：
+
+```js
+( function ( wp ) {
+	wp.data.dispatch( 'core/notices' ).createNotice(
+		'success', // 可选类型：success, info, warning, error
+		'文章已发布。', // 显示的文本内容
+		{
+			isDismissible: true, // 用户是否可关闭该通知
+			// 用户可执行的操作
+			actions: [
+				{
+					url: '#',
+					label: '查看文章',
+				},
+			],
+		}
+	);
+} )( window.wp );
+```
+
+当在JavaScript应用程序生命周期中生成通知时，您应该使用此_通知数据API_。
+
+为了更好地理解上述具体代码示例：
+
+-   `wp`是WordPress的全局窗口变量
+-   `wp.data`是区块编辑器提供的用于访问数据存储的对象
+-   `wp.data.dispatch('core/notices')`访问由通知包注册到区块编辑器数据存储的功能
+-   `createNotice()`是通知包提供的用于注册新通知的函数。区块编辑器通过读取通知数据存储来了解需要显示哪些通知
+
+请查看[_在编辑器中加载资源_](/docs/how-to-guides/enqueueing-assets-in-the-editor.md)教程，了解如何将自定义JavaScript加载到区块编辑器中的基础知识。
+
+## 了解更多
+
+区块编辑器提供完整的API用于生成通知。官方文档是了解功能可能性的绝佳资源。
+
+要获取可用操作和选择器的完整列表，请参阅[通知数据手册](/docs/reference-guides/data/data-core-notices.md)页面。