README

WordPress 插件，用于增强编辑体验，包括一些常见的 Gutenberg 编辑器的自定义设置。

此插件的功能

此插件旨在根据编辑使用的 WordPress 主题调整 Gutenberg 编辑器的体验，并添加许多网站常用的功能。此插件添加的功能分为三类：块修改、编辑插件和核心增强。此插件还公开了一些全局函数，可以在主题模板中使用。

块

扩展块

以下块通常在注册钩子（blocks.registerBlockType）中扩展，以限制编辑器可用的选项数量。一些块还通过编辑生命周期钩子（通过 editor.BlockEdit 钩子）添加额外的类和结构到编辑器标记，以便能够使用 CSS 控制块设置的一些方面。

请注意，您可以通过使用 WordPress 的 blocks.registerBlockType 和 editor.BlockEdit 过滤器，在主题中继续扩展核心块的功能。

编辑插件

我们的主要 Gutenberg "插件" 为帖子主侧栏添加了两个面板：文章顶部面板和作者面板。

文章顶部面板

文章顶部面板控制与文章顶部相关的文章帖子元数据。这包括

顶部类型：顶部的外观和感觉，无论是纯文本还是网站宽度的特色图片
导航主题：当与深色背景图片顶部配对时，已深色主题的导航可能看起来是透明的。此选项允许更亮的导航主题
Overline：为您的文章选择一个主要类别，以允许在常见主题之间更好的再循环

作者面板

作者面板允许编辑器为作者署名分配多个作者。此过程从 帖子 下的 作者 部分开始，您可以在其中创建作者档案。

这些作者也充当您文章的分类法，因此代表作者自己的内容的存档页面会自动为您生成。

核心增强

为附件帖子添加一个 信用 字段。

模板函数

此插件公开了一些函数，可用于检索插件处理的相关值。有关可用函数的信息，请参阅主题 API 部分。

主题配置

默认情况下，激活插件后，此插件的所有功能都启用。但是，您可以通过添加到主题的配置文件来配置插件的功能（包括禁用某些功能）。

要设置配置文件，将 ups-editorial.php 文件添加到主题根目录，该文件返回一个包含相关配置选项的数组

<?php
/**
 * Configuration for the ups-editorial plugin.
 */

return array(
  'author_panel'         => true,
  'article_topper_panel' => true,
  'attachment_credit'    => true,
  'extended_blocks'      => array(
		'cover',
		'file',
		'gallery',
		'image-layout',
		'related-articles',
		'table',
		'video',
	),
  'enable_block_styles'  => array(),
);

配置

`author_panel`

允许类型： boolean

默认值： true

启用或禁用插件的作者分类法，以及包含添加和管理单个文章作者机制的Gutenberg编辑器面板。

`article_topper_panel`

允许类型： boolean

默认值： true

启用或禁用文章标题和Gutenberg面板字段的注册。

`attachment_credit`

允许类型： boolean

默认值： true

启用或禁用附件的credit字段的注册。

`extended_blocks`

允许的类型： 数组

默认值

array(
  'cover',
  'file',
  'gallery',
  'image-layout',
  'related-articles',
  'table',
  'video',
)

由插件扩展的块列表。要禁用某个块的扩展，请从该数组中排除它。

`enable_block_styles`

允许的类型： 数组

默认值： array()

WordPress核心为一些核心块包含样式选项。默认情况下，此插件删除了这些样式选项，但可以使用此参数重新启用特定块的内核样式选项。以下块具有可以通过此参数重新启用的内核样式：button、image、quote、separator、table。

主题 API

有一些全局可用的函数可以由您的主题使用来检索由本插件功能定义的数据。这些函数在插件目录根部的Template.php文件中定义，并位于Upstatement\Editorial命名空间下。

建议您的主题通过function_exists检查来实现这些函数，以防止插件禁用时出现未定义的错误。例如

if ( function_exists( 'Upstatement\Editorial\get_post_authors' ) ) {
  $authors = \Upstatement\Editorial\get_post_authors();
  ...

`get_post_authors`

get_post_authors( WP_Post $post = null, string $field = null) : array | null

获取文章的作者列表。

参数

post

要获取作者的帖子。留空以使用当前的全局帖子。

field

要为每个作者返回的字段。这可以是WP_Term对象的任何属性。留空以返回整个WP_Term对象。

返回一个包含作者数据的数组。如果field为空，则这将是一个WP_Term对象的数组。如果指定了field，则这将是一个该字段值的数组。

`get_post_overline`

get_post_overline( WP_Post $post = null ) : WP_Term | null

获取文章的横幅类别。

参数

post

要获取横幅的帖子。留空以使用当前的全局帖子。

返回横幅类别标识为横幅的WP_Term对象，如果没有设置则返回null。

故障排除

"我已经更新了编辑侧边的内容，但它没有出现在预览中。"

这是Wordpress Gutenberg的一个已知问题，其中文章元数据只有在按下更新按钮后才会保存。我们目前正在跟踪主要问题，在WordPress/gutenberg#14900，但在那之前，您可以尝试以下步骤之一

在更新侧边栏内容后，按下更新按钮，然后按下预览按钮。
按两次预览按钮。有时元数据只在每隔一个预览中可用。
在预览窗口中尝试强制刷新（在Google Chrome中为command+shift+R）。

块验证和恢复

在更改现有或新组件的已保存标记时，您很可能会遇到块验证问题。

此错误发生在最后保存的块的标记与在编辑器中加载时块的标记不匹配。

如果此错误是故意的，则绕过问题的最简单方法是

在块的右上角按下三点。
选择尝试块恢复选项。这将根据最新版本的保存函数重新渲染块标记。
更新帖子以保存最新的块标记。

如果错误是非故意的，您的控制台将是确定发生了什么错误的最佳位置。它可能看起来像这样

Block validation: Block validation failed for `ups/image` Content generated by `save` function:

<figure class="wp-block-image">
  <img src="/good-image.png" alt="A good image" />
  <figcaption>This is the caption</figcaption>
  <cite>This is a new citation</cite>
</figure>

Content retrieved from post body:

<figure class="wp-block-image">
  <img src="/good-image.png" alt="A good image" />
  <figcaption>This is the caption</figcaption>
</figure>

在上述情况下，在块已经保存到帖子后，在标记中添加了一个新的 cite 元素。此时，您可以（1）选择 尝试块恢复 选项来更新标记，（2）删除并重新创建块，或者（3）将保存功能回滚以删除 cite 元素。

本地开发

要修改此插件，您可以下载此存储库并将其添加到任何运行的 WordPress 实例的 plugins/ 目录中。您还需要执行一些设置步骤，以确保您拥有所有构建依赖项。

要开始本地工作，您需要在您的机器上准备以下内容

nvm 来管理此项目运行的 Node 版本。
composer 来管理 PHP 依赖项和自动加载。

安装以上内容后，您可以按照以下步骤进行设置

确保您正在运行预期的 Node 版本
```
nvm install
```
安装 Node 依赖项
```
npm install
```
安装 composer 依赖项并生成自动加载器
```
composer install
```
监控插件文件的更改
```
npm run start
```

您可以使用以下脚本在任何时间构建静态前端资产

npm run build

资源

在开发此插件期间，我们发现以下资源很有用

upstatement / ups-editorial-wp-plugin

维护者

详细信息

README

目录

此插件的功能

块

扩展块

编辑插件

文章顶部面板

作者面板

核心增强

模板函数

主题配置

配置

`author_panel`

`article_topper_panel`

`attachment_credit`

`extended_blocks`

`enable_block_styles`

主题 API

`get_post_authors`

参数

返回

`get_post_overline`

参数

返回

故障排除

"我已经更新了编辑侧边的内容，但它没有出现在预览中。"

块验证和恢复

本地开发

资源

upstatement / ups-editorial-wp-plugin

维护者

详细信息

README

目录

此插件的功能

块

扩展块

编辑插件

文章顶部面板

作者面板

核心增强

模板函数

主题配置

配置

author_panel

article_topper_panel

attachment_credit

extended_blocks

enable_block_styles

主题 API

get_post_authors

参数

返回

get_post_overline

参数

返回

故障排除

"我已经更新了编辑侧边的内 容，但它没有出现在预览中。"

块验证和恢复

本地开发

资源

`author_panel`

`article_topper_panel`

`attachment_credit`

`extended_blocks`

`enable_block_styles`

`get_post_authors`

`get_post_overline`

"我已经更新了编辑侧边的内容，但它没有出现在预览中。"