ACF PRO 6.8.9 发布，WordPress 7.1 起默认使用 Blocks V3

Advanced Custom Fields PRO 6.8.9 现已推出。

本次发布更改了 ACF Blocks 的默认区块版本。从 6.8.9 开始，任何未明确声明版本的 ACF Block，在 WordPress 7.1 及更高版本中都将注册为 V3 区块。本文将解释更改原因、这对您的网站意味着什么，以及如果您需要更多时间迁移该怎么做。

WordPress 7.1 的变更

WordPress 7.1 对区块编辑器进行了重大更改：无论是区块主题还是经典主题，编辑画布现在默认在 iframe 中呈现。其目标是让编辑器预览尽可能贴近访客在前端看到的内容。

iframe 的工作方式是将编辑画布与 WordPress 管理后台隔离开来。其中只会加载您主题的脚本和样式。wp-admin 中的任何内容都不会跨越这一边界。

这正是 ACF Blocks V2（尤其是使用“edit”模式时）遇到问题的地方。

V2 为何在 iframe 编辑器中失效

V2 区块依赖加载于 wp-admin 中的 JavaScript 和 CSS 来提供区块编辑界面，包括 WordPress 核心库，如所见即所得编辑器和 jQuery UI 日期选择器，而 WordPress 自身已停止在 iframe 内加载这些库。此前，将 V2 区块插入编辑器会自动移除 iframe。在 WordPress 7.1 中，情况不再如此。iframe 会保留下来，而运行 V2 编辑所需的库也无法再在画布中使用。结果是，字段会被强制置于预览模式，只能通过狭窄的右侧边栏进行编辑。对于包含 Repeater、Flexible Content 或超过少量字段的区块而言，这会带来令人沮丧的体验。

坦白地说，V2 所实现的 edit 模式在区块编辑器中一直 somewhat 违背最佳实践。画布的设计初衷是预览区块在前端的样子。将 wp-admin 脚本注入该预览区域以提供完整的编辑界面，始终与 WordPress 核心的发展方向相悖。WordPress 7.1 正是这种矛盾变得无法回避的节点。

这不是 ACF 做出的决定，而是 WordPress 核心的变更，并且符合区块编辑器设计方式的长期发展方向。

受影响的用户

您的区块未设置明确版本。从 6.8.9 开始，这些区块在 WordPress 7.1 及更高版本中将自动以 V3 运行。无需更改代码，但您会发现编辑体验有所变化。

您的区块明确将 acf.blockVersion 或 acf_block_version 设置为 1 或 2。本次发布不会更改这些区块。它们将继续以 V2 运行，但会受到 WordPress 7.1 iframe 问题的影响。我们建议迁移到 V3。

您需要更多时间来迁移。请安装兼容性插件，以在规划迁移期间恢复 V2 行为；或者使用 acf/blocks/default_block_version 过滤器，在全局范围内保留之前的默认设置。这两种都是临时解决方案。

人们为何喜爱 V2 编辑模式

V2 的 edit 模式为内容编辑者提供了区块编辑器本身无法自然提供的功能：传统的数据录入体验。有些区块使用铅笔图标在字段表单和预览之间切换。还有许多区块更进一步，将区块永久锁定在编辑模式下，完全禁用预览，让编辑者始终只看到自己的 ACF 字段，而不会看到其他任何内容。

对于从经典编辑器迁移而来的团队，或是需要构建包含大量结构化字段的内容密集型模块的机构来说，这是一个经过深思熟虑的设计选择。内容编辑人员不需要考虑模块在前端呈现的样子。他们只需看到表单，填写内容，然后继续工作。既熟悉、快速，又可预测。

对于某些工作流程而言，这种体验确实很好。我们理解人们为何选择基于它构建。

问题在于，过去只能通过将 wp-admin 脚本直接注入模块画布来实现，而这与 WordPress 核心的发展方向发生了直接冲突。WordPress 7.1 终于让这一问题浮出水面。

V3 的编辑方式

默认情况下，V3 模块会在画布中显示预览。点击铅笔图标会打开扩展编辑器：这是一个位于模块预览旁侧的较大面板，为复杂的字段组、Repeaters 和 Flexible Content 提供了真正的编辑界面。其空间明显比 WordPress 7.1 中 V2 模块所缩减到的狭窄侧边栏更宽敞。

你也可以选择启用内联编辑，让编辑人员直接点击模块预览内的文本字段并就地输入，无需打开扩展编辑器。这是一种直观且可以说更好的编辑体验，可在区块编辑器内编辑字段数据。

V3 模块的无预览模式

V2 最常见的模式之一，是通过设置 mode: 'edit' 和 supports: { mode: false } 将模块永久锁定在编辑模式下。在 V3 中，这些设置此前会被忽略，这意味着模块始终会显示预览——对于复杂模块而言，预览可能会显示异常或内容过多。

6.8.9 通过两种方式修复了这个问题。

首先，带有旧版 V2 设置的 V3 模块现在会自动跳过渲染模板，并改为显示简洁的占位符：模块图标、标题，以及用于打开扩展编辑器的编辑按钮。

其次，对于原生的新 V3 模块，你现在可以在 block.json 中通过单个属性明确禁用预览渲染：

{
  "acf": {
    "renderPreview": false
  }
}

这为开发者提供了一种受支持且向后兼容的方式，可构建直接进入扩展编辑器而不显示预览的模块。无需任何变通方案。

对于许多编辑人员来说，一旦习惯之后，扩展编辑器实际上比 V2 的内联字段更舒适，尤其是处理复杂模块时。但这一过渡并不只是代码变更。对于已经构建了数百个网站、并培训了数百名客户使用 V2 编辑体验的机构和自由职业者来说，这会带来真实且重大的中断。现有客户需要重新接受培训。文档需要更新。支持请求也会随之增加。

我们并未将这一点视为一个微不足道的要求。

我们为何推荐 V3

V3 是唯一能在 WordPress 7.1 中正确运行、并且随着 WordPress 核心继续发展而持续正常工作的编辑体验。如果不采用最终将失效的变通方案，V2 编辑模式无法在 iframe 编辑器中恢复。

尽管如此，我们知道 V3 对内容编辑人员来说是一次重大转变。工作流程会发生变化，需要进行培训。这并非小事，我们也不会轻视这一点。

我们听到了你的声音：下面是一种变通方案

我们发布了一款官方兼容性插件，为团队提供更多迁移时间：

acf-blocks-v2-iframe-compatibility

这款插件在 WordPress 7.1 中恢复了 V2 的编辑行为。有几点重要提醒：

• 它是一座临时桥梁，而非长期解决方案
• 某些功能可能无法完美运行。这并不是一条完全受支持的路径
• 随着 WordPress 核心继续改进 iframe 编辑器，这种方式在未来版本中可能会停止工作

我们发布它，是因为希望为你提供一种在我们倾听反馈期间继续运行的方式，而不是因为我们认为继续使用 V2 是可持续的解决方案。

在此下载插件 zip 文件。

告诉我们你的需求

如果 V2 编辑模式对你或你的客户的工作至关重要，我们希望了解原因。你的内容编辑工作流程是什么样的？V3 需要做出哪些改变，才能让你的团队 realistically 迁移？

与我预约通话。我正在专门留出时间讨论这些工作流程。你的反馈将直接影响我们确定 V3 改进事项的优先级。

你也可以通过我们的支持渠道联系我们，或在 GitHub 上发起讨论。

如何迁移到 V3

如果你已准备好迁移，请参阅完整的 V3 迁移指南。

对于包含许多区块的网站，最快捷的方法是在你的主题或插件中添加以下单个过滤器：

add_filter( 'acf/blocks/default_block_version', function() {
    return 3;
});

在 block.json 中明确设置了 acf.blockVersion 的区块不受此过滤器影响，需要单独更新。

V3 区块需要 ACF PRO 6.6 或更高版本。V3 的内联编辑需要 ACF PRO 6.7 或更高版本。

请在下方查看发布说明。有关最新的 ACF 资讯，请在 X 上关注我们 @wp_acf。

更新日志

• 增强 – 通过 acf_register_block_type() 或 block.json 注册且未明确指定版本的 ACF 区块，现在在 WordPress 7.1 或更高版本中默认使用 v3。指定了版本的区块仍使用其声明的版本，默认值可通过 acf/blocks/default_block_version 过滤器自定义
• 增强 – ACF 区块 v3 现在支持在 block.json 中使用 renderPreview 选项。设置 "renderPreview": false 后，编辑器中会显示一个占位符，其中包含区块图标、标题和“编辑区块”按钮，而不是将区块模板作为实时预览呈现。该区块在前端仍会正常呈现，而将 "mode": "edit" 与 "supports": { "mode": false } 结合使用的旧版 v2 区块在升级到 v3 时会自动迁移
• 修复 – ACF 区块 V3 中可内联编辑的字段现在无需再次点击即可编辑
• 修复 – 单选按钮现在能在 ACF 管理界面中正确显示
• 修复 – 启用 Safe SVG 插件后，图像和图库字段不再拒绝上传 SVG

文章 ACF PRO 6.8.9：区块 V3 现已成为默认版本（并提供 V2 兼容插件）首发于 ACF。