wp-env 来创建本地 WordPress 开发环境。不过，您也可以自由使用任何满足上述前提条件的开发环境。
wp-env，请改为使用终端导航到本地 WordPress 安装中的 plugins/ 文件夹，然后运行以下命令。
--variant=dynamic 标志。这告诉 create-block 你想要搭建一个动态渲染的区块。在本教程后面，你将了解动态和静态渲染，并为此区块添加静态渲染。
save.js 文件。在本教程后续部分，您将把这个文件添加到插件中以启用静态渲染，敬请关注。
viewBox 参数。
{ __( 'Copyright Date Block – hello from the editor!', 'copyright-date-block-demo' ) }
); } ``` 它看起来比实际要复杂一些。 - [`useBlockProps()`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#block-wrapper-props) 会输出编辑器所需的、包含在[区块包装器](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/#the-edit-components-markup)中的所有必要 CSS 类和样式，这包括你之前添加的区块支持所提供的样式 - [`__()`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/) 用于文本字符串的国际化© { currentYear }
); } ``` 保存 `edit.js` 文件并刷新编辑器。你现在将看到版权符号 (©) 后面跟着当前年份。  ### 更新 render.php 虽然区块在编辑器中运行正常，但前端仍显示默认的区块消息。要解决此问题，请打开 [`render.php`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block/#render-php) 文件，您将看到以下内容。 ```php>
``` 类似于编辑器中的 `useBlockProps()` 函数，[`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/) 会在[区块包装器](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/#the-server-side-render-markup)中输出所有必要的 CSS 类和样式。只需更新内容部分即可。 您可以使用 `date( "Y" )` 在 PHP 中获取当前年份，更新后的 `render.php` 应如下所示。 ```php>©
``` 保存文件并确认区块在编辑器和前端均正确显示。 ### 清理工作 使用 `create-block` 包搭建区块时，可能会包含不需要的文件。在本教程中，该区块不使用样式表或前端 JavaScript。请通过以下操作清理插件的 `src/` 文件夹。 1. 在 `edit.js` 文件中，移除导入 `editor.scss` 的代码行 2. 在 `index.js` 文件中，移除导入 `style.scss` 的代码行 3. 删除 editor.scss、style.scss 和 view.js 文件 最后，确保没有未保存的更改，然后终止 `npm run start` 命令。运行 `npm run build` 以优化代码并使其可用于生产环境。 您已经构建了一个功能完整的 WordPress 区块，但不要就此止步。在接下来的章节中，我们将添加功能并启用静态渲染。 ## 添加区块属性 您构建的版权日期区块显示当前年份，但如果还想展示起始年份呢？  此功能需要用户在区块的某个位置输入起始年份，同时还应具备启用/禁用该功能的开关。 您可以通过多种方式实现此功能，但都需要使用[区块属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)。属性允许您为区块存储自定义数据，这些数据可用于修改区块的标记。 为实现起始年份功能，您需要一个属性来存储起始年份，另一个属性则用于告知 WordPress 是否应显示起始年份。 ### 更新 block.json 区块属性通常在 [`block.json`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#data-storage-in-the-block-with-attributes) 文件中定义。因此，请打开该文件，并在 `example` 属性后添加以下部分。 ```json "example": {}, "attributes": { "showStartingYear": { "type": "boolean" }, "startingYear": { "type": "string" } }, ``` 定义属性时必须指明 `type`。在本例中，`showStartingYear` 应为 true 或 false，因此其类型设为 `boolean`。而 `startingYear` 只是一个字符串。 保存文件后，您现在可以继续处理编辑器部分。 ### 更新 edit.js 文件 打开 `edit.js` 文件。你需要完成两项任务。 - 添加一个用户界面，允许用户输入起始年份、切换功能开关，并将这些设置存储为属性。 - 更新区块，使其能根据定义的属性显示正确的内容。 #### 添加用户界面 在本教程的前面部分，您添加了区块支持，这些支持会在区块的设置侧边栏中自动创建颜色和排版面板。您可以使用 `InspectorControls` 组件创建自己的自定义面板。 ##### 检查器控件 `InspectorControls` 属于 [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) 包，因此你可以通过在第 14 行添加组件名称将其导入到 `edit.js` 文件中。结果应如下所示。 ```js import { InspectorControls, useBlockProps } from '@wordpress/block-editor'; ``` 接下来，更新 Edit 函数，使其返回当前块内容和一个包含文本 "Testing" 的 `InspectorControls` 组件。你可以将所有内容包裹在一个 [Fragment](https://react.dev/reference/react/Fragment) (`<>`) 中，以确保正确的 JSX 语法。结果应如下所示。 ```js export default function Edit() { const currentYear = new Date().getFullYear().toString(); return ( <>© { currentYear }
); } ``` 保存文件并刷新编辑器。选择块时，你应该会在设置侧边栏中看到 "Testing" 消息。  ##### 组件与面板 现在，让我们使用更多核心组件来添加自定义面板和起始年份功能的用户界面。你需要从 [`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) 包中导入 [`PanelBody`](https://developer.wordpress.org/block-editor/reference-guides/components/panel/#panelbody)、[`TextControl`](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/) 和 [`ToggleControl`](https://developer.wordpress.org/block-editor/reference-guides/components/toggle-control/)。 在 `edit.js` 文件的其他导入语句下方添加以下行。 ```js import { PanelBody, TextControl, ToggleControl } from '@wordpress/components'; ``` 然后将 "Testing" 消息包裹在 `PanelBody` 组件中，并将 `title` 参数设置为 "Settings"。更多参数选项请参考[组件文档](https://developer.wordpress.org/block-editor/reference-guides/components/panel/#panelbody)。 ```js export default function Edit() { const currentYear = new Date().getFullYear().toString(); return ( <>© { currentYear }
); } ``` 保存文件并刷新编辑器。你现在应该能看到新的设置面板。  ##### 文本控件 下一步是将“Testing”消息替换为允许用户设置 `startingYear` 属性的 `TextControl` 组件。但在执行此操作之前，必须在 `Edit()` 函数中包含两个参数。 - `attributes` 是一个包含区块所有属性的对象 - `setAttributes` 是一个允许更新属性值的函数 包含这些参数后，你就可以获取 `showStartingYear` 和 `startingYear` 属性。 将 `Edit()` 函数的顶部更新为如下所示。 ```js export default function Edit( { attributes, setAttributes } ) { const { showStartingYear, startingYear } = attributes; ... ```Edit() 函数顶部添加 console.log( attributes );。这在构建和测试自定义区块时非常有用。
© { currentYear }
); } ```value 属性的值为 startingYear || ''。符号 || 被称为 逻辑或（逻辑析取）运算符。这可以防止当 startingYear 为空时在 React 中出现警告。详情请参阅 受控与非受控组件。
© { currentYear }
); } ``` 保存文件并刷新编辑器。确认点击切换开关会显示文本输入框，并且当你更新页面时，切换开关保持激活状态。  #### 更新区块内容 到目前为止，你已经创建了用于添加起始年份和更新相关区块属性的用户界面。现在你需要实际更新编辑器中的区块内容。 让我们创建一个名为 `displayDate` 的新变量。当 `showStartingYear` 为 `true` 且用户提供了 `startingYear` 时，`displayDate` 应包含 `startingYear` 和 `currentYear`，两者之间用破折号分隔。否则，只显示 `currentYear`。 代码应大致如下所示。 ```js let displayDate; if ( showStartingYear && startingYear ) { displayDate = startingYear + '–' + currentYear; } else { displayDate = currentYear; } ```let 声明变量时，意味着该变量后续可能会被重新赋值。使用 const 声明变量则意味着该变量永远不会改变。你可以使用 const 重写这段代码。这只是个人偏好的问题。
© { displayDate }
); } ``` 保存文件并刷新编辑器。确认当你在设置面板中进行更改时，区块内容能正确更新。  ### 更新 render.php 虽然编辑器看起来很棒，但起始年份功能尚未添加到前端。让我们通过更新 `render.php` 文件来解决这个问题。 首先添加一个名为 `$display_date` 的变量，并复制你在上面 `Edit()` 函数中所做的操作。 这个变量应该显示 `startingYear` 属性和 `$current_year` 变量的值，用破折号分隔；如果 `showStartingYear` 属性为 `false`，则只显示 `$current_year`。在 render.php 中暴露了三个变量，你可以使用它们来自定义块的输出：
$attributes（数组）：块属性。$content（字符串）：块的默认内容。$block（WP_Block）：块实例。> ©
``` 保存文件，并确认正确的块内容现在出现在你网站的前端。 你现在已经成功构建了一个动态渲染的自定义块，它利用了块支持、核心 WordPress 组件和自定义属性。在许多情况下，对于一个显示版权日期并具有一些额外功能的块来说，这已经足够了。 然而，在下一节中，你将向该块添加静态渲染。这个练习将说明块数据是如何存储在 WordPress 中的，并提供一个后备方案，以防此插件被意外禁用。 ## 添加静态渲染 区块可以采用动态渲染、静态渲染或两者结合的方式。目前构建的区块采用动态渲染，其区块标记和关联属性存储在数据库中，但 HTML 输出结果不存储。 静态渲染区块始终将区块标记、属性和输出结果存储在数据库中。区块也可以在数据库中存储静态输出，同时在前端通过动态方式进行增强，实现两种方法的结合。 如果在编辑器中切换到代码编辑器，会看到以下内容： ```html ``` 将此与静态渲染区块（如段落区块）进行比较： ```htmlThis is a test.
``` 段落的 HTML 存储在文章内容中并保存到数据库。 您可以在[基础文档](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/)中了解更多关于动态和静态渲染的信息。虽然大多数区块采用动态或静态渲染，但您可以构建同时使用两种方法的区块。 ### 为何要添加静态渲染？ 当您为动态渲染区块添加静态渲染时，`render.php` 文件仍将控制前端的输出，但区块的 HTML 内容将被保存到数据库中。这意味着即使插件从网站中移除，内容也将得以保留。以这个版权日期区块为例，内容将恢复为一个自定义 HTML 区块，您可以轻松地将其转换为段落区块。  虽然并非所有情况都需要，但为动态渲染区块添加静态渲染可以在插件意外禁用时提供有用的回退方案。 此外，考虑一种情况：区块标记包含在区块模式或主题模板中。如果用户安装该主题或使用该模式时未安装版权日期区块，他们将收到区块不可用的通知，但内容仍会显示。 添加静态渲染也是探索区块内容在 WordPress 中如何存储和渲染的良好方式。 ### 添加保存函数 首先在 `src/` 文件夹中添加一个名为 `save.js` 的新文件。在此文件中添加以下内容。 ```js import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ({ 'Copyright Date Block – hello from the saved content!' }
); } ``` 这应该看起来与原始的 `edit.js` 文件类似，你可以参考[块包装器](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/#the-save-components-markup)文档获取更多信息。 接下来，在 `index.js` 文件中导入这个 `save()` 函数，并在 `registerBlockType()` 函数中添加一个 save 属性。以下是更新后文件的简化视图。 ```js import save from './save'; ... registerBlockType( metadata.name, { icon: calendarIcon, edit: Edit, save } ); ```save 而不是 save: save。
Copyright Date Block – hello from the saved content!
``` 在使用静态渲染构建块时，经常会遇到块验证错误，这没关系。`save()` 函数的输出必须与文章内容中的 HTML 完全匹配，这可能会在你添加功能时变得不同步。只要在完全完成块构建后没有验证错误，一切就都准备好了。 ### 更新 save.js 接下来，让我们更新 `save()` 函数的输出以显示正确的内容。首先复制 `edit.js` 中使用的方法。 1. 向函数添加 `attributes` 参数 2. 定义 `showStartingYear` 和 `startingYear` 变量 3. 定义一个 `currentYear` 变量 4. 根据 `currentYear`、`showStartingYear` 和 `startingYear` 的值定义一个 `displayDate` 变量 结果应如下所示。 ```js export default function save( { attributes } ) { const { showStartingYear, startingYear } = attributes; const currentYear = new Date().getFullYear().toString(); let displayDate; if ( showStartingYear && startingYear ) { displayDate = startingYear + '–' + currentYear; } else { displayDate = currentYear; } return (© { displayDate }
); } ``` 保存文件并刷新编辑器。点击“尝试恢复块”并更新页面。检查代码编辑器，块标记现在应如下所示。 ```html© 2017–2023
``` 此时，您可能认为已经完成了。块内容现在已作为 HTML 保存在数据库中，并且前端输出是动态渲染的。然而，仍有一些问题需要解决。 考虑这样一种情况：用户在 2023 年将块添加到页面，然后在 2024 年返回编辑该页面。前端将按预期更新，但在编辑器中会出现块验证错误。`save()` 函数知道现在是 2024 年，但数据库中保存的块内容仍然显示 2023 年。 让我们在下一节中解决这个问题。 ### 处理静态渲染区块中的动态内容 通常，您应避免在静态渲染区块中使用动态内容。这也是为什么在提及动态渲染时会使用“动态”一词的部分原因。 尽管如此，在本教程中，您将结合使用两种渲染方法，并且只需添加少量代码，即可在年份变化时避免任何区块验证错误。 问题的根源在于 `currentYear` 变量是在 `save()` 函数中动态设置的。相反，这应是一个函数内的静态变量，可以通过添加一个属性来解决。 #### 添加新属性 打开 `block.json` 文件，添加一个名为 `fallbackCurrentYear` 的新属性，类型为 `string`。此时文件的 `attributes` 部分应如下所示。 ```json "attributes": { "fallbackCurrentYear": { "type": "string" }, "showStartingYear": { "type": "boolean" }, "startingYear": { "type": "string" } }, ``` 接下来，打开 `save.js` 文件，使用新的 `fallbackCurrentYear` 属性替代 `currentYear`。更新后的 `save()` 函数应如下所示。 ```js export default function save( { attributes } ) { const { fallbackCurrentYear, showStartingYear, startingYear } = attributes; let displayDate; if ( showStartingYear && startingYear ) { displayDate = startingYear + '–' + fallbackCurrentYear; } else { displayDate = fallbackCurrentYear; } return (© { displayDate }
); } ``` 现在，如果 `fallbackCurrentYear` 未定义会发生什么？ 之前 `currentYear` 是在函数内部定义的，因此即使 `showStartingYear` 和 `startingYear` 未定义，`save()` 函数也始终有内容可返回。 与其只返回版权符号，不如添加一个条件：如果 `fallbackCurrentYear` 未设置，则返回 `null`。通常，在数据库中不保存 HTML 比保存不完整的数据更好。 最终的 `save()` 函数应如下所示。 ```js export default function save( { attributes } ) { const { fallbackCurrentYear, showStartingYear, startingYear } = attributes; if ( ! fallbackCurrentYear ) { return null; } let displayDate; if ( showStartingYear && startingYear ) { displayDate = startingYear + '–' + fallbackCurrentYear; } else { displayDate = fallbackCurrentYear; } return (© { displayDate }
); } ``` 保存 `block.json` 和 `save.js` 这两个文件；您无需再进行任何更改。 #### 在 edit.js 中设置属性 `save()` 函数现在使用了新的 `fallbackCurrentYear`，因此需要在某个地方设置它。让我们使用 `Edit()` 函数。 打开 `edit.js` 文件，首先在 `Edit()` 函数顶部与其他属性一起定义 `fallbackCurrentYear` 变量。接下来，查看函数中发生了什么。 当区块在编辑器中加载时，会定义 `currentYear` 变量。然后函数使用这个变量来设置区块的内容。 现在，如果 `fallbackCurrentYear` 属性尚未设置，让我们在区块加载时将其设置为 `currentYear`。 ```js if ( currentYear !== fallbackCurrentYear ) { setAttributes( { fallbackCurrentYear: currentYear } ); } ``` 这可以工作，但可以通过确保此代码仅在区块初始化时运行一次来改进。为此，你可以使用 [`useEffect`](https://react.dev/reference/react/useEffect) React 钩子。有关如何使用此钩子的更多信息，请参阅 React 文档。 首先，使用以下代码导入 `useEffect`。 ```js import { useEffect } from 'react'; ``` 然后将上面的 `setAttribute()` 代码包装在 `useEffect` 中，并将此代码放在 `Edit()` 函数中的 `currentYear` 定义之后。结果应如下所示。 ```js export default function Edit( { attributes, setAttributes } ) { const { fallbackCurrentYear, showStartingYear, startingYear } = attributes; // 获取当前年份并确保它是字符串。 const currentYear = new Date().getFullYear().toString(); // 当区块加载时，如果 fallbackCurrentYear 属性尚未设置， // 则将其设置为当前年份。 useEffect( () => { if ( currentYear !== fallbackCurrentYear ) { setAttributes( { fallbackCurrentYear: currentYear } ); } }, [ currentYear, fallbackCurrentYear, setAttributes ] ); ... ``` 当区块在编辑器中初始化时，`fallbackCurrentYear` 属性将立即被设置。然后这个值将可供 `save()` 函数使用，并且将显示正确的区块内容而不会出现区块验证错误。 唯一需要注意的是年份变化的情况。如果一个版权日期区块在 2023 年添加到页面，然后在 2024 年编辑，`fallbackCurrentYear` 属性将不再等于 `currentYear`，并且该属性将自动更新为 `2024`。这将更新 `save()` 函数返回的 HTML。 你不会得到任何区块验证错误，但编辑器会检测到页面已发生更改，并提示你进行更新。 #### Optimizing render.php The final step is to optimize the `render.php` file. If the `currentYear` and the `fallbackCurrentYear` attribute are the same, then there is no need to dynamically create the block content. It is already saved in the database and is available in the `render.php` file via the `$content` variable. Therefore, update the file to render the generated content if `currentYear` and `fallbackCurrentYear` do not match. ```php $current_year = date( "Y" ); // Determine which content to display. if ( isset( $attributes['fallbackCurrentYear'] ) && $attributes['fallbackCurrentYear'] === $current_year ) { // The current year is the same as the fallback, so use the block content saved in the database (by the save.js function). $block_content = $content; } else { // The current year is different from the fallback, so render the updated block content. if ( ! empty( $attributes['startingYear'] ) && ! empty( $attributes['showStartingYear'] ) ) { $display_date = $attributes['startingYear'] . '–' . $current_year; } else { $display_date = $current_year; } $block_content = '© ' . esc_html( $display_date ) . '
'; } echo wp_kses_post( $block_content ); ``` That's it! You now have a block that utilizes both dynamic and static rendering. ## 总结 恭喜你完成本教程并构建了自己的版权日期区块。通过这段学习旅程，你已经掌握了 WordPress 区块开发的基础知识，现在可以开始构建自己的区块了。 作为最终参考，本教程的完整代码可在 GitHub 上的 [Block Development Examples](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3) 仓库中找到。 现在，无论你是想精进技能、挑战更高级的项目，还是希望紧跟 WordPress 的最新趋势，以下资源都将帮助你提升区块开发能力： - [区块开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/) - [区块开发基础](https://developer.wordpress.org/block-editor/getting-started/fundamentals/) - [WordPress 开发者博客](https://developer.wordpress.org/news/) - [区块开发示例](https://github.com/WordPress/block-development-examples) | GitHub 仓库 请记住，每位专家都曾是初学者。持续学习、不断尝试，最重要的是，享受使用 WordPress 构建的乐趣。