目录
Create-Block软件包是一个省钱的工具,可让您通过一个命令快速,始终如一地为您的项目创建自定义块。从本质上讲,它实际上只有一件事。它接收一些值,处理这些值,然后在其中插入的那些值生成文件。
实际上,Create-Block工具依赖于模板来告诉它在哪里可以找到所需的文件,其中应该插入处理的值,并定义所需的任何默认值。
默认模板提供了用于创建简单块的标准配置。 当您开始创建外部项目模板时,Create Block的真正力量就会显而易见。
外部项目模板提供的控制水平是不可能通过的 交互式模式 或者 可用命令行选项 通过允许对脚手架文件的各个方面进行精细的控制。
模板可以通过--template
标志和模板可以托管 npmjs.com 就像 新互动性API的入门指南:
npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template
也可以通过将路径传递到模板所在的目录,也可以在本地引用模板:
npx @wordpress/create-block@latest custom-template-block –template ./path/to/files
这不仅是创建和测试模板的好方法,而且还利用它们在无法与整个社区共享的项目中。
设置
要使用Create-Block工具,您需要安装node.js。为此,请参阅 有关设置Node.js开发工具的官方文档。
安装节点后,克隆 随附的存储库 本文:
git clone https://github.com/wptrainingteam/external-project-template.git
然后进入目录:
cd external-project-template
该项目的内容应该像这样:
所有模板文件和配置将存储在my-template
目录。 它在根目录内部,因此您可以在同一位置轻松测试模板。
配置将存储在index.js
文件和实际的模板文件(一点点信息)将存储在files
目录及其子目录。目录名称并不重要,您可以将其称为任何您想要的。重要的是,我们将用于插件的文件分开,并阻止所得插件的部分。
定义模板
模板由两个部分组成:index.js
包含配置对象和胡须模板的文件将用作工具创建的每个新插件或块的模式。
胡子 是无逻辑模板语法。它可用于HTML,配置文件,源代码 – 任何东西。它通过使用哈希或对象中提供的值在模板中扩展标签来工作。
配置
这index.js
文件包含一个单个对象,该对象被导出并用作模板的配置。这里有六个可用的属性可在此处使用,您可以在 文档。
因为这是node.js,您将使用 commonjs 模块而不是 ES模块 您会在大多数现代的WordPress JavaScript项目中看到的。
首先导出一个空对象并导入稍后您会使用的助手。
将以下内容添加到index.js
您之前创建的文件:
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {};
定义文件位置
接下来,您需要告诉模板它可以在哪里找到所需的文件。存储库包含一个files
带有两个内部目录的目录plugin
文件和block
文件。 您可以使用pluginTemplatesPath
和blockTemplatesPath
分别。
现在就这样做:
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {
pluginTemplatesPath: join(__dirname, "files/plugin"),
blockTemplatesPath: join(__dirname, "files/block"),
};
在这一点上,您要指向空目录,但这还可以。您将稍后定义这些目录的内容。
还有另一个称为 assetsPath
这用于不应处理的静态资产,例如图像或字体。您没有使用此属性,但值得一提,您可以在 文档。
默认值
大多数配置设置将使用此对象设置。它允许模板作者访问可以为大量属性设置默认值。
而所有属性都添加到defaultValues
对象,它们在概念上分为三个组:项目,插件标头和块元数据。阅读有关所有属性的更多信息 文档。
就个人而言,我喜欢使用 更漂亮 在我本地的设置中。当我保存文件时,我的VSCODE配置为格式化我的JavaScript,并且通常将其添加到package.json
在我的项目中文件。当运行创建块工具时,package.json
文件将自动为脚手架插件创建。有几个默认值可自定义软件包,但是它们具有非常具体的用途,例如定义依赖项,脚本和WP-env/脚本集成。这defaultValues.customPackageJSON
被用作允许模板作者扩展的全部捕捉package.json
如所须。
将以下内容添加到index.js
文件:
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {
defaultValues: {
customPackageJSON: {
prettier: "@wordpress/prettier-config",
},
},
pluginTemplatesPath: join(__dirname, "files/plugin"),
blockTemplatesPath: join(__dirname, "files/block"),
};
运行时,这会添加"prettier": "@wordpress/prettier-config",
到创建的软件包。
接下来,您将添加默认值 namespace
,version
,和description
。请记住,这些是默认仍然可以使用适当标志覆盖的值。
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {
defaultValues: {
version: "1.0.0",
namespace: "developer-blog",
description:
"A plugin created by the create-block tool using a custom external project template.",
customPackageJSON: {
prettier: "@wordpress/prettier-config",
},
},
pluginTemplatesPath: join(__dirname, "files/plugin"),
blockTemplatesPath: join(__dirname, "files/block"),
};
变体
变体 是创建模板变体的非常强大的方法。这些与特定的模板相关联,并通过--variant
旗帜。例如,默认主题都具有static
和dynamic
变体。每个变体都会产生不同的文件集。
变体包含自己的一组defaultValues
结合并覆盖了主要的。这允许模板作者更改配置的一部分,以适合特定变体的需求。
您的模板将包含两个变体:dynamic
,和interactive
。前者产生一个简单的动态块,而后者产生一个动态块,该块利用WordPress 6.5的新交互性API。
每个变体是下方的对象variants
包含要结合的特定值的属性defaultValues
。
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {
defaultValues: {
version: "1.0.0",
namespace: "developer-blog",
description:
"A plugin created by the create-block tool using a custom external project template.",
render: "file:./render.php",
customPackageJSON: {
prettier: "@wordpress/prettier-config",
},
},
variants: {
dynamic: {},
interactive: {},
},
pluginTemplatesPath: join(__dirname, "files/plugin"),
blockTemplatesPath: join(__dirname, "files/block"),
};
通常,第一个变体是空的(在您的情况下,dynamic
)由于被用作默认值,不应--variant
传递给命令。从哲学的角度来看,这很有意义defaultValues
应该是创建插件所需的所有值。
接下来,将自定义添加到interactive
变体:
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {
defaultValues: {
version: "1.0.0",
namespace: "developer-blog",
description:
"A plugin created by the create-block tool using a custom external project template.",
render: "file:./render.php",
customPackageJSON: {
prettier: "@wordpress/prettier-config",
},
},
variants: {
dynamic: {},
interactive: {
viewScriptModule: "file:./view.js",
customScripts: {
build: "wp-scripts build --experimental-modules",
start: "wp-scripts start --experimental-modules",
},
supports: {
interactive: true,
},
},
},
pluginTemplatesPath: join(__dirname, "files/plugin"),
blockTemplatesPath: join(__dirname, "files/block"),
};
这个变体添加了viewScriptModule
属性和集合 supports.interactive
到true
在block.json
。此外,它改变了build
和`start
脚本在package.json
。这些更改都是为了启用交互性API所需的,这超出了本文的范围。
了解有关互动性API的更多信息 官方文件。
胡子模板
胡须模板被用作模式,以创建生成插件所需的各种文件。它们分为两种类型:插件和块。
插件文件
插件文件被输出到生成插件的根部,例如主插件PHP文件,readme.txt
,和composer.json
。
块文件
这些是将在插件内输出的文件src
目录。这是输出插件文件的地方,例如block.json
,index.js
,edit.js
,和render.php
。
无论类型如何,每个模板都必须具有.mustache
扩大。如果没有,则创建块工具将忽略文件。
模板变量
看着files/plugin
目录,您将看到五个文件.mustache
扩大:
- .editorConfig.mustache
- .eslintrc.mustache
- .gitignore.mustache
- readme.txt.mustache
- $ slug.php.mustache
这些文件中的每一个都将添加到插件的根目录中,而没有.mustache
扩大。您可能想知道为什么最后一个文件有$slug
以其名字。如果您看着它的内部或readme.txt.mustache
,您可能还想知道这个奇怪的符号是什么:
<?php
/**
* Plugin Name: {{title}}
*/
这些项目是胡须模板变量,被用户传递的模板定义的值替换,或者是根据其他值派生的。
例如,如果您运行以下命令:
npx @wordpress/create-block my-example-template-block --template ./my-template
$slug.php.mustache
会成为my-example-template-block.php
和{{title}}
变量将被替换My Example Template Block
,这是从传递给工具的sl子产生的。
这些是可在任何被值替换的模板中使用的变量:
- {{namespace}},
- {{namespacesnakecase}}
- {{namespacePascalcase}}
- {{{slug}}
- {{{slugpascalcase}}
- {{{slugsnakecase}}
- {{标题}}
- {{描述}}
- {{作者}}
- {{pluginuri}}
- {{执照}}
- {{{plichuri}}
- {{domainpath}}
- {{updateuri}}
- {{版本}}
- {{TextDomain}}
还有其他与您之前定义的变体相关的其他变量。每个人都变成一个 布尔变量 这表明变体的选定状态。在您的模板中,将定义两个:{{isDynamicVariant}
} 和{{isInteractiveVariant}}
。如果--variant interactive
通过,然后{{isInteractiveVariant}}
将true
和{{isDynamicVariant}}
将是错误的。如果不--variant
通过或将值设置为dynamic
,然后将发生相反的情况。
这是一个功能强大的功能,使模板作者能够根据这些变量有条件地输出文件中的内容。小胡子通过使用以下格式支持条件模板变量:
{{#VariableVar}}
If VariableVar is true, then this content is output
{{/VariableVar}}
在两种情况下,这非常有帮助:
首先是当您只需要给定变体的文件时。在您的模板中,有一个view.js.mustache
仅在使用时才需要的文件interactive
变体。立即打开该文件,您将看到以下代码:
/**
* WordPress dependencies
*/
import { store } from '@wordpress/interactivity';
store( '{{slug}}', {
state: {},
actions: {},
callbacks: {},
} );
运行以下命令生成动态块:
npx @wordpress/create-block my-example-template-block --template ./my-template
请注意,该文件是生成的,这不是所需的结果。将条件标签添加到模板中以检查是否{{isInteractiveVariant}
} 活跃:
{{#isInteractiveVariant}}
/**
* WordPress dependencies
*/
import { store } from '@wordpress/interactivity';
store( '{{slug}}', {
state: {},
actions: {},
callbacks: {},
} );
{{/isInteractiveVariant}}
再次运行命令,您会看到该文件未输出,因为条件没有验证为true,并且创建了一个空文件。Create-Block工具足够聪明,可以检查以确保任何文件具有内容,如果没有,则不会将文件写入文件系统。
当文件的内容基于变体不同时,会发生另一种情况。在我们的情况下,Render.php文件将根据变体具有略有不同的内容,但某些内容始终输出。
<?php
/**
* PHP file to use when rendering the block type on the server to show on the front end.
*
* The following variables are exposed to the file:
* $attributes (array): The block attributes.
* $content (string): The block default content.
* $block (WP_Block): The block instance.
*
* @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
*/
{{#isInteractiveVariant}}
// Define some global state
wp_interactivity_state(
'{{slug}}',
array()
);
// Define some context.
$context = array();
?>
<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>
data-wp-interactive="{{slug}}"
<?php echo wp_interactivity_data_wp_context( $context ); ?>
>
<?php esc_html_e( '{{title}} – hello from an interactive block!', '{{textdomain}}' ); ?>
</p>
{{/isInteractiveVariant}}
{{#isDynamicVariant}}
?>
<p <?php echo wp_kses_data( get_block_wrapper_attributes() ); ?>>
<?php esc_html_e( '{{title}} – hello from a dynamic block!', '{{textdomain}}' ); ?>
</p>
{{/isDynamicVariant}}
上面的模板将始终具有显示文件顶部的内容,但是基于Active的变体,它将输出不同的内容。
变压器
这transformer
财产是defaultValues
但是有特殊用途。它接受一个函数,该函数允许模板作者访问由Create-Block工具创建的所有变量,然后返回修改后的值。
更新index.js
文件以下文件:
/**
* Dependencies
*/
const { join } = require("path");
module.exports = {
defaultValues: {
transformer: (view) => {
console.log(view);
return view;
},
version: "1.0.0",
namespace: "developer-blog",
description:
"A plugin created by the create-block tool using a custom external project template.",
render: "file:./render.php",
customPackageJSON: {
prettier: "@wordpress/prettier-config",
},
},
variants: {
dynamic: {},
interactive: {
viewScriptModule: "file:./view.js",
customScripts: {
build: "wp-scripts build --experimental-modules",
start: "wp-scripts start --experimental-modules",
},
supports: {
interactive: true,
},
},
},
pluginTemplatesPath: join(__dirname, "files/plugin"),
blockTemplatesPath: join(__dirname, "files/block"),
};
再次运行此命令:
npx @wordpress/create-block my-example-template-block --template ./my-template
在您的终端中,您会看到一个包含所有可以访问的变量的大对象。
{
'$schema': 'https://schemas.wp.org/trunk/block.json',
apiVersion: 3,
plugin: true,
namespace: 'developer-blog',
slug: 'my-example-template-block',
title: 'My Example Template Block',
description: 'A plugin created by the create-block tool using a custom external project template.',
dashicon: undefined,
category: 'widgets',
attributes: undefined,
supports: undefined,
author: 'The WordPress Contributors',
pluginURI: undefined,
license: 'GPL-2.0-or-later',
licenseURI: 'https://www.gnu.org/licenses/gpl-2.0.html',
domainPath: undefined,
updateURI: undefined,
version: '1.0.0',
wpScripts: true,
wpEnv: false,
npmDependencies: [],
npmDevDependencies: undefined,
customScripts: {},
folderName: './src',
editorScript: 'file:./index.js',
editorStyle: 'file:./index.css',
style: 'file:./style-index.css',
viewStyle: undefined,
render: 'file:./render.php',
viewScriptModule: undefined,
viewScript: undefined,
variantVars: { isDynamicVariant: true, isInteractiveVariant: false },
customPackageJSON: { prettier: '@wordpress/prettier-config' },
customBlockJSON: undefined,
example: undefined,
textdomain: 'my-example-template-block'
}
您可能需要访问和修改这些原因有很多。例如,块开发示例repo使用它添加 对sl,标题和其他一些项目产生的价值。
另一个用例是创建模板变量,这些变量不受创建障碍的本质支持。在模板中,您提供了一种使用WordPress 6.5中发布的Interactivity API的变体。在这种情况下,设置 至少需要插件标题 需要WordPress 6.5。没有容易可用的defaultValue
您可以覆盖,因此您将自己添加并在模板中使用它。
首先,更新Requires at least header
在$slug.php.mustache
使用以下内容:
* Requires at least: {{requiresAtLeast}}
这是您通过变压器函数介绍的新变量。
接下来,在配置中更新变压器功能以有条件地检查变体并返回适当的版本编号以设置标题值。
transformer: (view) => {
const {
variantVars: { isInteractiveVariant },
} = view;
return {
...view,
requiresAtLeast: isInteractiveVariant ? "6.5" : "6.1",
};
},
此代码返回视图对象并将新模板变量添加到其中。
运行以下命令:
npx @wordpress/create-block my-example-template-block --template ./my-template --variant interactive
my-example-template-block.php现在将读取如下:
* Requires at least: 6.5
恭喜!现在,您有一个可行的自定义外部项目模板。尝试添加自己的新变体。
如果您想分享任何模板,请将它们添加到下面的评论中。
道具 @Greenshady,@BPH 和 @Dansoschin 提供反馈并审查此帖子。