古腾堡块废弃处理：在不破坏内容的情况下更新

摘要

更新古腾堡块通常会破坏使用旧版本的现有文章。本文向您展示如何使用 block.json 中的 deprecated 属性来保持向后兼容性。您将学习捕获当前块标记、定义一个或多个废弃版本以及正确映射属性的精确步骤。我们将涵盖静态块和动态块，并附有实用示例。本文还反驳了废弃总是最佳方法的假设，讨论了何时彻底分离可能更好。通过本文，您将能够自信地更新您的块，而不会破坏用户的内容。

变更断连的场景

六个月前，您发布了一个自定义评价块。它输出一个简单的 <div>，包含引用和作者姓名。现在您的客户想要一个新设计：作者应出现在引用上方，并使用不同的 CSS 类。您更新了块的 save 函数和 render_callback。您在新文章上测试——看起来很棒。然后您导航到使用该块的旧文章。灾难：引用文本不见了，作者位置错误，样式也乱了。您刚刚破坏了使用该块的每个页面。

这是古腾堡块开发中典型的“破坏性变更”问题。块本质上是数据结构与标记的结合。当您更改标记时，编辑器无法自动将旧内容映射到新结构。结果要么是验证错误（块变得无效），要么更糟——块渲染不正确却无提示的损坏。

什么是块废弃处理？

块废弃处理是古腾堡内置的处理版本变更的机制。通过在块的 block.json 中定义一个 deprecated 数组，您告诉编辑器：“如果您遇到匹配这些旧版本之一的块，将其转换为当前版本。”每个废弃条目指定先前的 attributes、supports 和 save 函数（或 render_callback）。当编辑器加载旧块时，它会按顺序遍历废弃数组并应用第一个匹配的转换。

这个功能通常未被充分利用，因为开发人员假设他们永远不需要更改块的标记。但在实际项目中，需求会演变。如果您跳过废弃处理，您要么迫使用户删除并重新插入块（糟糕的体验），要么维护两个单独的块版本（混乱）。官方 WordPress 开发者手册在块编辑器手册中涵盖了这一点，但缺乏实际演练。

第一步：捕获当前状态

在进行任何更改之前，记录确切的 save 输出（或动态块的 render_callback）以及块当前使用的 attributes。将其视为拍照。对于静态块，保存 save 函数返回的 JSX。对于动态块，保存 render_callback 生成的 PHP 标记。

在插件中创建一个名为 deprecated.js（或类似名称）的新文件，并将旧的 save 函数存储在其中。或者，将废弃版本直接保留在块的主 JavaScript 文件中。关键是精确地保留代码，就像块首次部署时一样。

第二步：定义您的废弃版本

在您的 block.json 中，添加一个 deprecated 数组。每个条目是一个对象，可以包含：

• attributes（对象）：先前的属性定义。
• supports（对象）：任何已更改的先前支持设置。
• save（函数或字符串）：先前的保存函数。对于仅 JavaScript 的块，您将导入旧函数。对于 PHP 渲染的动态块，您可以使用 migrate 和 render_callback 代替。
• migrate（函数）：将旧属性映射到新属性的函数（可选）。

示例：

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

注意：block.json 中的 save 函数通常用 JavaScript 定义。如果您使用外部脚本，则需要将其排队并引用函数名称。或者，您可以将函数内联为字符串（尽管对于复杂块不建议这样做）。

第三步：映射属性

通常，您不仅更改标记，还更改属性名称或来源。例如，您可能从将作者存储为纯字符串切换到富文本字段。在这种情况下，使用 migrate 属性将旧属性转换为新属性。

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

如果您不提供 migrate 函数，编辑器将简单地将旧属性直接传递给新块。如果属性名称更改，这可能会导致错误。

第四步：用真实内容测试

定义废弃版本后，彻底测试。创建新文章，插入旧块（您可以通过粘贴现有文章的序列化块代码来模拟），并验证它是否转换为新版本且没有验证错误。还要测试编辑和保存转换后的块。如果有多个废弃版本，请重复操作。

对于动态块，过程类似但稍有不同：动态块的 save 函数通常返回 null（块通过 PHP 渲染）。在废弃条目中，您可以将 save 设置为切换到动态渲染之前使用的先前静态标记，或者使用 PHP 中的 render_callback 处理新旧属性结构。这更复杂但可行。

注意事项与权衡

废弃处理功能强大，但也有缺点。每个废弃版本都会为您的插件增加代码。随着时间的推移，您可能会得到一串五六个很少使用但必须维护的旧版本。WordPress 核心团队建议至少保留两个版本，但超过这个数量，如果受影响的文章数量很少，您可以考虑彻底分离。

另一个细微差别：废弃条目的顺序很重要。编辑器从索引 0 向上遍历数组并使用第一个匹配项。如果两个废弃版本相似，可能会应用错误的版本。始终首先列出最新的废弃版本（直接先于当前版本的版本）。

最后，废弃处理不处理使用全站样式更改（例如通过 theme.json）编辑的内容。如果您的块的外观依赖于已经更改的全局样式，废弃处理不会为此进行调整。您可能需要添加一个迁移脚本，在保存时或通过插件更新钩子运行。

何时废弃处理不是答案

大多数教程认为废弃处理是强制性的。实际上，在某些情况下，彻底分离更好。如果您的块是新的并且只用在少数文章中，手动更新那几个实例可能比编写和测试废弃代码更快。同样，如果块的基础数据模型根本不同（例如，您将两个块合并为一个），废弃处理可能不够灵活。在这种情况下，编写一个一次性迁移脚本，在插件更新时运行，将旧块转换为新格式。

另一个反观点：废弃处理不应替代良好的设计。如果您预计经常更改，请从一开始就考虑版本化设计块——例如，通过存储 version 属性并使用条件渲染。这种方法在超越基本块中讨论过，比废弃处理更轻量，但需要远见。

结论

块废弃处理是任何认真的古腾堡开发者的必备工具。它允许您在不破坏用户内容的情况下发展您的块。关键步骤是：捕获当前状态，在 block.json 中定义废弃版本，如果需要则映射属性，并用真实内容测试。但请记住，废弃处理带有维护成本。有时彻底分离或版本化块设计更实用。战略性地使用废弃处理，而不是自动地，您的块将在多次更新中保持稳健。

要更广泛地了解构建可维护的插件，请参阅构建稳健的 WordPress 插件。如果您是块开发新手，超越基本块将帮助您入门。