外部项目模板-WordPress区块编辑器手册-果果开发

您是否正在寻找一种共享项目配置的方法？可以创建一个托管在 npm 上或位于本地目录中的外部项目模板。这些 npm 包可以提供自定义的 .mustache 文件，用于替换工具中为 WordPress 插件和/或区块包含的默认文件。还可以覆盖在脚手架过程中使用的默认配置值。

项目模板配置

必须提供包的入口文件（默认为 index.js），该文件需返回一个配置对象。有几个选项允许自定义脚手架过程。

pluginTemplatesPath

此可选字段允许覆盖与WordPress 插件外壳相关的文件模板。路径指向以 .mustache 扩展名结尾的模板文件所在位置（也支持嵌套文件夹）。如果未设置，工具将使用其自身的模板集。

示例：

const { join } = require( 'path' );

module.exports = {
    pluginTemplatesPath: join( __dirname, 'plugin-templates' ),
};

blockTemplatesPath

此可选字段允许覆盖与单个区块相关的文件模板。路径指向以 .mustache 扩展名结尾的模板文件所在位置（也支持嵌套文件夹）。如果未设置，工具将使用其自身的模板集。

示例：

const { join } = require( 'path' );

module.exports = {
    blockTemplatesPath: join( __dirname, 'block-templates' ),
};

assetsPath

当您的模板构建使用静态资源（如图片或字体）且不应被处理的 WordPress 插件时，此设置非常有用。它提供了指向资源所在位置的 path。它们将被复制到生成的插件中的 assets 子文件夹中。

示例：

const { join } = require( 'path' );

module.exports = {
    assetsPath: join( __dirname, 'plugin-assets' ),
};

defaultValues

可以使用 defaultValues 字段来覆盖默认的模板配置。

示例：

module.exports = {
    defaultValues: {
        slug: 'my-fantastic-block',
        title: 'My fantastic block',
        dashicon: 'palmtree',
        version: '1.2.3',
    },
};

以下可配置变量与模板文件一起使用。模板作者可以更改默认值，以便在用户未提供数据时使用。

项目：

wpScripts（默认值：true）– 启用与 @wordpress/scripts 包的集成，并将常用脚本添加到 package.json 中。
wpEnv（默认值：false）– 启用与 @wordpress/env 包的集成，并将 env 脚本添加到 package.json 中。
customScripts（默认值：{}）– 要添加到 package.json 的自定义脚本列表。它还允许覆盖默认脚本。
npmDependencies（默认值：[]）– 要在项目中安装的远程 npm 包列表，当启用 wpScripts 时使用 npm install 安装。
npmDevDependencies（默认值：[]）– 要在项目中安装的远程 npm 包列表，当启用 wpScripts 时使用 npm install --save-dev 安装。
customPackageJSON（无默认值）– 允许定义生成的 package.json 文件的附加属性。

插件头部和 readme 字段（了解有关头部要求和readmes的更多信息）：

pluginURI（无默认值）– 插件的主页。
version（默认值：'0.1.0'）– 插件的当前版本号。
requiresAtLeast（默认值：'6.8'）– 插件能够运行的最低 WordPress 版本。
requiresPHP（默认值：'7.4'）– 与此插件配合使用所需的最低 PHP 版本。
testedUpTo（默认值：'6.8'）– 已对该插件进行测试的最高 WordPress 版本。
author（默认值：'The WordPress Contributors'）– 插件作者的名字。
license（默认值：'GPL-2.0-or-later'）– 插件许可证的简称。
licenseURI（默认值：'https://www.gnu.org/licenses/gpl-2.0.html'）– 指向许可证全文的链接。
domainPath（无默认值）– 翻译的自定义域路径（更多信息）。
updateURI:（无默认值）– 插件的自定义更新 URI（相关开发说明）。

区块元数据（了解更多）：

folderName（默认值：src）– block.json 文件和从 blockTemplatesPath 设置中设置的文件夹中包含的区块模板生成的其他可选区块文件的位置。
$schema（默认值：`https://schemas.wp.org/trunk/block.json`）– 用于区块验证的模式 URL。
apiVersion（默认值：2）– 区块 API 版本（相关开发说明）。
slug（无默认值）– 用于在区块名称中进行标识的区块别名。
namespace（默认值：'create-block'）– 区块名称的内部命名空间。
title（无默认值）– 区块的显示标题。
description（无默认值）– 区块的简短描述。
dashicon（无默认值）– 一个图标属性，使识别区块变得更加容易（可用值）。
category（默认值：'widgets'）– 区块被分组到各个类别中，以帮助用户浏览和发现它们。核心提供的类别有 text、media、design、widgets、theme 和 embed。
textdomain（默认为 slug 值）– 用于使字符串可翻译的文本文档（更多信息）。
attributes（无默认值）– 区块属性（更多详细信息）。
supports（无默认值）– 可选的区块扩展支持功能（更多详细信息）。
editorScript（默认值：'file:./index.js'）– 编辑器脚本定义。
editorStyle（默认值：'file:./index.css'）– 编辑器样式定义。
style（默认值：'file:./style-index.css'）– 前端和编辑器样式定义。
render（无默认值）– 在服务器上呈现区块类型之前在 front end 展示之前使用的 PHP 文件的路径。
customBlockJSON（无默认值）– 允许定义生成的 block.json 文件的附加属性。
transformer（默认值：( view ) => view）– 接收由 create-block 工具生成的所有变量并返回一个值对象的函数。此函数提供修改现有值和添加新变量的能力。

transformer 示例

此示例向 slug 变量添加了一个生成的值。

transformer: ( view ) => {
    const hex = getRandomHexCode();
      return {
         ...view,
         slug: `${ view.slug }-${ hex }`,
      };
},

此示例创建了一个新的自定义变量，可以在关联的 mustache 模板中用作 {{customVariable}}

transformer: ( view ) => {
      return {
         ...view,
         customVariable: `Custom Value`,
      };
},

variants

变体用于为模板创建变体。变体可以通过提供自己的值来覆盖任何 defaultValues。

module.exports = {
    defaultValues: {
        slug: 'my-fantastic-block',
        title: 'My fantastic block',
        dashicon: 'palmtree',
        version: '1.2.3',
    },
    variants: {
        primary: {},
        secondary: {
            title: 'My fantastic block - secondary variant',
        },
    },
};

变体通过 --variant 标志访问，例如 --variant secondary。

如果未提供变体，则使用第一个定义的变体（如果有的话）。

为变体创建 Mustache 变量，可用于在文件中条件性地输出内容。格式为 {{isVARIANT_NAMEVariant}}。

{{#isPrimaryVariant}}
仅当传递 `--variant primary` 时才会渲染此内容。
{{/isPrimaryVariant}}

{{#isSecondaryVariant}}
仅当传递 `--variant secondary` 时才会渲染此内容。
{{/isSecondaryVariant}}

变体还可以通过定义 pluginTemplatesPath、blockTemplatesPath 或 assetsPath 来定义自己的文件。如果定义了这些路径，它们将覆盖项目模板中定义的路径。如果某个变体不需要模板定义的某些文件，可以将 null 传递给相应的变量以跳过生成这些文件。

module.exports = {
    defaultValues: {
        slug: 'my-fantastic-block',
        title: 'My fantastic block',
        dashicon: 'palmtree',
        version: '1.2.3',
    },
    variants: {
        primary: {},
        secondary: {
            title: 'My fantastic block - secondary variant',
            blockTemplatesPath: join(
                __dirname,
                'custom-path',
                'block-templates'
            ),
            assetsPath: null, // 即使主模板定义了资产文件，也不会生成任何资产文件。
        },
    },
};