WordPress 6.1 引入了新方法 用于扩展查询循环块。这是一个重要的里程碑,因为它至少在代码方面将很多功能掌握在插件开发人员的手中。扩展器不需要在核心WordPress中过滤现有功能,而不是构建自定义块。
查询循环块是从块中构建网站的主力军。它是显示帖子,页面和其他自定义帖子类型(CPTS)的内容的基础。
在WordPress 6.1之前,其主要用例是显示与PHP对应物相比,以前可能发生的有限子集:WP_Query
。这意味着开发人员,尤其是在处理CPT的数据时,通常是自行构建整个自定义块。
如今,扩展器可以建立一个坚实的基础,以输出几乎任何类型的内容,并以最小的代码为基础。6.1版的更改允许插件作者跳过块开发方面并扩展内置查询循环块。
可以使用这种方式的一些示例包括:
- 通过价格元字段显示产品网格。
- 商务目录按位置上市业务。
- 点对点筹款活动的排行榜。
- 通过评级来输出书评。
对于此次演练,您将学习如何解决该列表中的最后一项:列表书评帖子。从头到尾,您将构建一个WordPress插件。结果将是一个查询循环块变化,看起来与以下屏幕截图相似:
此简单教程中的基本方法也可以应用于更复杂的项目。
教程步骤
要求
除了一些基线JavaScript开发知识和对块开发的熟悉之外,您还应该在计算机上可用这些工具:
- 节点/NPM开发工具
- WordPress开发网站
- 代码编辑器
有关设置这些设置的更多信息,请访问 发展环境 块编辑手册中的指南。
设置内容
对于本教程,假设您有一个客户喜欢不时撰写图书评论,并希望在其网站上的各个地方(例如自定义页面上)炫耀最新评论。客户有一个定制类别,标题为“书评”和一些已经撰写的帖子。
在您的开发环境中重新创建这种情况。
首先,添加一个新的“书评”类别和 记下类别ID。您将稍后再需要。然后,创建至少三个分配给此类别的示例帖子,并给出每个帖子的特色图像。
插件设置
在您的wp-content/plugins
目录。命名类似book-reviews-grid
(确切的名称不是特别重要)。现在,添加具有此特定结构的以下文件:
book-reviews-grid
/index.php
/package.json
/src
/index.js
你可以改变index.php
无论您想要什么。它是您的插件的主要PHP文件。
PHP设置
在您的插件的主要PHP文件中,添加插件标头,并提供一些基本信息:
<?php
/**
* Plugin Name: Book Reviews Grid
* Version: 1.0.0
* Requires at least: 6.1
* Requires PHP: 7.4
*/
// Additional code goes here…
这将是您本教程所需的唯一PHP文件,所有PHP代码都将进入其中。
构建过程设置
首先,打开你的package.json
文件并添加start
脚本。这将用于构建过程。您可以添加其他字段,例如name
和description
如果你想。
{
"scripts": {
"start": "wp-scripts start"
}
}
本教程需要@wordpress/scripts
软件包,可以通过命令行安装:
npm install @wordpress/scripts --save-dev
设置所有设置后,在命令行程序中输入以下内容:
npm run start
除了必需的start
命令,您可以通过 @wordpress/脚本 包装并将它们添加到您的package.json
如果需要的话。
构建简单的查询循环变化
注册简单查询循环变化的过程(一个没有任何自定义查询变量集成)仅需要几十行代码。您必须导入registerBlockVariation
并使用它来注册变体。
JavaScript:构建变体
在你的顶部src/index.js
文件,添加以下代码行:
import { registerBlockVariation } from '@wordpress/blocks';
现在,您需要两个信息。首先,确定变体的唯一名称。book-reviews
现在将工作。所需的第二位数据是您之前在此演练中创建的“书评”类别的ID。
如下所示,将这两个值都分配给常数,并将其分配给常数:
const VARIATION_NAME = 'book-reviews';
const REVIEW_CATEGORY_ID = 8; // Assign custom category ID.
现在,是时候注册变体了。首先,添加一些基本属性,例如名称,标题等,如以下代码块所示:
registerBlockVariation( 'core/query', {
name: VARIATION_NAME,
title: 'Book Reviews',
icon: 'book',
description: 'Displays a list of book reviews.',
isActive: [ 'namespace' ],
// Other variation options...
} );
注册变体时,有两个必要的选项要设置core/query
堵塞:
- 这
name
属性应与您的唯一变体名称匹配。 - 这
isActive
属性应该是一个数组namespace
属性(您将在下一步中定义此属性)。
从这一点开始,变化大多是可自定义的,但是让我们一次浏览这一步骤,为变体添加新的选项。下一个要构建的部分是变体的属性。属性可以匹配查询循环块接受的任何内容。
一个额外必需的属性是namespace
。它必须匹配变体名称,以便WordPress能够检查它是否是活动变化。
对于本教程,这些变化显示了“书评”类别中的最新六篇文章。它在三列网格中还具有宽阔的布局。随意自定义您喜欢的选项。
registerBlockVariation( 'core/query', {
// ...Previous variation options.
attributes: {
namespace: VARIATION_NAME,
query: {
postType: 'post',
perPage: 6,
offset: 0,
taxQuery: {
category: [ REVIEW_CATEGORY_ID ]
}
},
align: 'wide',
displayLayout: {
type: 'flex',
columns: 3
}
},
// Other variation options...
} );
开发人员还可以选择通过设置哪些默认WordPress控件可用allowedControls
数组(默认情况下,显示所有控件)。这些在接口中显示为块选项。有关控件及其定义的完整列表,请访问 允许的控件部分 在块编辑手册中。
以下示例添加order
和author
控件:
registerBlockVariation( 'core/query', {
// ...Previous variation options.
allowedControls: [
'order',
'author'
],
// Other variation options...
} );
最后,您应该为变化添加一些内部块。第一个顶级块应该始终是core/post-template
。以下代码段使用没有自定义的核心邮政特色图像和帖子标题块,但可以随意添加其他块并为每个块设置默认选项。
registerBlockVariation( 'core/query', {
// ...Previous variation options.
innerBlocks: [
[
'core/post-template',
{},
[
[ 'core/post-featured-image' ],
[ 'core/post-title' ]
],
]
]
} );
有关可用选项的完整概述,请访问以下资源:
PHP:加载JavaScript
通过处理基本JavaScript,现在您必须加载JavaScript文件本身。构建过程将生成两个文件:
- build/index.js: 将加载的JavaScript文件。
- build/index.asset.php: 脚本的一系列依赖项和版本号。
以下代码段应添加到index.php
。如果存在并将脚本加载在编辑器中:它获取生成的资产文件:
add_action( 'enqueue_block_editor_assets', 'myplugin_assets' );
function myplugin_assets() {
// Get plugin directory and URL paths.
$path = untrailingslashit( __DIR__ );
$url = untrailingslashit( plugins_url( '', __FILE__ ) );
// Get auto-generated asset file.
$asset_file = "{$path}/build/index.asset.php";
// If the asset file exists, get its data and load the script.
if ( file_exists( $asset_file ) ) {
$asset = include $asset_file;
wp_enqueue_script(
'book-reviews-variation',
"{$url}/build/index.js",
$asset['dependencies'],
$asset['version'],
true
);
}
}
有了此代码,您应该能够通过Block Inserster或Slash命令添加“书评”变化(例如/book reviews
)在块编辑器中:
如果您的变化不需要对查询帖子进行任何自定义,则可以在教程的这一点上停止。
将后元数据整合到变体中
现在,让我们研究以现有代码为基础的更高级的方案。您将建立一个控制用户的控件,以根据元元密钥和价值对显示图书评论。
工作的关键方面是WordPress提供的过滤器钩子。一旦学习了如何使用它们,就可以将它们扩展到自定义的帖子类型和其他现实世界项目。
设置后元数据
您将需要一个元元密钥rating
具有元值之间1
和5
这是在书评类别中的一个或多个帖子中附加的。最简单的方法是使用 自定义字段 邮政编辑屏幕上的面板。
笔记: 如果您看不到自定义字段面板,你可以启用它 从 选项(⋮图标)>首选项>面板 编辑器中的菜单。
返回您的每本书评论帖子并添加评级值,如以下屏幕截图所示:
在一个现实世界项目中,您可能需要构建适当的表单字段,以便最终用户轻松选择星级评级。但是,这超出了本教程的范围。
JavaScript:添加块变体控件
要在自定义查询循环变化中添加额外的控件,您需要将一些其他模块导入到脚本中。将以下代码添加到您的顶部src/index.js
文件。在构建其余功能时,您将使用这些功能。
// ...Previous imports.
import { addFilter } from '@wordpress/hooks';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, SelectControl } from '@wordpress/components';
接下来,构建一个快速的助手功能,用于确定基于其道具的块是否与您的变化匹配。您将稍后在代码中使用它。大多数工作之所以完成,是因为您以前设置了一个变体名称常数和要检查的名称空间。
const isBookReviewsVariation = ( props ) => {
const {
attributes: { namespace }
} = props;
return namespace && namespace === VARIATION_NAME;
};
现在,是时候构建用于显示自定义块面板部分的组件了。您稍后可以在此处添加多个字段。目前,它将容纳一个表格字段,以选择星级评级。
以下代码使用SelectControl
组件创建下拉列表的下拉级别。这很容易成为无线电列表,按钮组或完全自定义的反应组件。它是由你决定。
此代码的重要部分是将星级评级值节省为props.attributes.query.starRating
。您将稍后需要修改帖子查询。
const BookReviewControls = ( { props: {
attributes,
setAttributes
} } ) => {
const { query } = attributes;
return (
<PanelBody title="Book Review">
<SelectControl
label="Rating"
value={ query.starRating }
options={ [
{ value: '', label: '' },
{ value: 1, label: "1 Star" },
{ value: 2, label: "2 Stars" },
{ value: 3, label: "3 Stars" },
{ value: 4, label: "4 Stars" },
{ value: 5, label: "5 Stars" }
] }
onChange={ ( value ) => {
setAttributes( {
query: {
...query,
starRating: value
}
} );
} }
/>
</PanelBody>
);
};
建立自定义面板部分并控制后,您必须过滤查询循环(core/query
)块以添加自定义控件。那是较早的地方isBookReviewsVariation
辅助功能进来。您将通过块的道具将其传递给它,以确定它是否是您的自定义变化。如果匹配,请添加您的控件。
export const withBookReviewControls = ( BlockEdit ) => ( props ) => {
return isBookReviewsVariation( props ) ? (
<>
<BlockEdit {...props} />
<InspectorControls>
<BookReviewControls props={props} />
</InspectorControls>
</>
) : (
<BlockEdit {...props} />
);
};
addFilter( 'editor.BlockEdit', 'core/query', withBookReviewControls );
在这一点上,您应该有一个可见的部分,标题为“书籍评论”,并在使用变化时,其中包含“评分”的“评分”部分,如以下屏幕截图所示:
此时选择评级不应更改查询帖子。还有几个过滤器可以添加以使其正常工作。
PHP:过滤查询帖子
您必须添加两个PHP过滤器,以便为编辑器和前端提供此功能。然后,您将有一个完整的查询循环变化,并随后集成。
第一个过滤器将继续 rest_{$post_type}_query
钩。因为您是使用“帖子”帖子类型构建的,所以挂钩名称变为rest_post_query
。
此过滤器将在该类型的每个查询上运行,因此您需要检查自定义查询参数(starRating
)在进行任何更改之前。您可以通过回调函数的$request
参数,提供了一个实例 WP_REST_Request
班级。使用它get_param()
检查自定义查询参数的方法。
如果是starRating
设置值,您只需要将元密钥传递并作为查询参数返回。为此,请将以下代码添加到插件的主要PHP文件中:
add_filter( 'rest_post_query', 'myplugin_rest_book_reviews', 10, 2 );
function myplugin_rest_book_reviews( $args, $request ) {
$rating = $request->get_param( 'starRating' );
if ( $rating ) {
$args['meta_key'] = 'rating';
$args['meta_value'] = absint( $rating );
}
return $args;
}
现在,在编辑器中测试您先前构建的评级控制。如以下屏幕截图所示,只查询具有所选额定值的帖子:
在编辑器中工作时,您还需要使用pre_render_block
挂钩在前端呈现块时运行一些自定义代码。然后,您需要在该回调的第二个过滤器中嵌套第二个过滤器query_loop_block_query_vars
使用匿名函数挂钩。这样做的原因是您需要访问分析的块属性。
如果听起来有些令人费解,那就是。理想情况下,将来将有一种稍微不复杂的方法。
add_filter( 'pre_render_block', 'myplugin_pre_render_block', 10, 2 );
function myplugin_pre_render_block( $pre_render, $parsed_block ) {
// Determine if this is the custom block variation.
if ( 'book-reviews' === $parsed_block['attrs']['namespace'] ) {
add_filter(
'query_loop_block_query_vars',
function( $query, $block ) use ( $parsed_block ) {
// Add rating meta key/value pair if queried.
if ( $parsed_block['attrs']['query']['starRating'] ) {
$query['meta_key'] = 'rating';
$query['meta_value'] = absint( $parsed_block['attrs']['query']['starRating'] );
}
return $query;
},
10,
2
);
}
return $pre_render;
}
现在,您应该在网站的前端具有相同的查询帖子,如编辑器所示。
有了这个基础,您可以将其扩展到其他项目。本质上,您可以使用一些过滤器和自定义控件来构建所需的任何类型的查询。尽管本教程似乎有点长,但总共包含的代码少于200行,与建立成熟的块相比,这是一个重大胜利。
您想到哪些类型的查询循环块变体?
道具 @BPH,@Mburridge,和 @WebCommsat 用于技术和编辑反馈。