title: "向后兼容性" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Code - Contributors - Repos

向后兼容性

历史上，WordPress 一直以保持跨版本向后兼容性而闻名。Gutenberg 在其生产环境的公共 API 中尽可能遵循这一原则。在极少数情况下，破坏向后兼容性不可避免，此时应遵循以下原则：

• 应尽可能将破坏范围限制在 API 的小部分区域内。
• 应通过开发说明向第三方开发者尽可能清晰地记录变更。

什么构成生产环境公共 API

Gutenberg 代码库由两种不同类型的包组成：

• 生产环境包：这些包作为 WordPress 脚本发布（例如：wp-components、wp-editor...）。
• 开发环境包：这些包由开发者工具组成，可供第三方开发者用于检查、测试、格式化和构建他们的主题和插件（例如：@wordpress/scripts、@wordpress/env...）。通常，这些包在第三方项目中作为 npm 依赖项使用。

向后兼容性保证仅适用于生产环境包，因为更新是通过 WordPress 升级进行的。

生产环境包使用 wp 全局变量向第三方开发者提供 API。这些 API 可以是 JavaScript 函数、变量和 React 组件。

如何保持 JavaScript 函数的向后兼容性

• 函数名称不应更改。
• 函数参数的顺序不应更改。
• 函数的返回值类型不应更改。
• 如果保证所有先前的调用仍然可行，则可以修改参数（新增参数、修改语义）。

如何保持 React 组件的向后兼容性

• 组件名称不应更改。
• 组件的属性不应被移除。
• 应继续支持现有的属性值。如果组件接受一个函数作为属性，我们可以更新组件以接受同一属性的新类型，但这不应破坏现有用法。
• 允许添加新属性。
• 只有在确保不破坏先前上下文契约的前提下，才能添加或移除 React Context 依赖。

如何保持区块的向后兼容性

• 当编辑器加载时，现有区块的使用不应中断或被标记为无效。
• 应确保现有区块的样式保持不变。
• 应尽可能限制标记更改，但如果某个区块需要更改其保存的标记，导致先前版本无效，则应添加该区块的弃用版本。

类名与 DOM 更新

React 组件树内部使用的类名和 DOM 节点不被视为公共 API 的一部分，因此可能被修改。

修改这些内容需谨慎，因为它们可能影响第三方代码的样式和行为（即使第三方代码本不应依赖这些内容）。尽可能保留原有类名和节点。若无法保留，请记录变更并编写开发说明。

弃用说明

随着项目发展，现有 API 的缺陷会被发现，或者需要更新以支持新功能。出现这种情况时，我们会尽力确保现有 API 不被破坏，并构建新的替代 API。

为了鼓励第三方开发者采用新 API，我们可以使用 deprecated 辅助工具来显示说明弃用的消息，并在旧 API 被使用时推荐替代方案。

请明确说明功能何时被弃用。使用辅助方法的 since 和 plugin 选项。

示例：

deprecated( 'wp.components.ClipboardButton', {
    since: '10.3',
    plugin: 'Gutenberg',
    alternative: 'wp.compose.useCopyToClipboard',
} );

开发说明

开发说明是在 WordPress 发布前于 make/core 站点发布的文章，旨在向第三方开发者通报开发者 API 的重要变更，这些变更可能包括：

• 新增 API。
• 可能影响现有插件和主题的现有 API 变更（例如：类名更改等）。
• 不可避免的向后兼容性破坏，附原因说明和迁移流程。
• 重要的弃用（即使未造成破坏），附原因说明和迁移流程。

开发者说明工作流程

• 在开发拉取请求时若发现需要编写开发者说明，请为该 PR 添加 Needs Dev Note 标签。
• 如有可能，请在 PR 中添加评论说明为何需要开发者说明。
• 当即将发布的 WordPress 版本首个测试版发布后，请检查该版本中已合并且带有 Needs Dev Note 标签的 PR 列表。
• 针对每个此类 PR 撰写开发者说明，并与 WordPress 版本负责人协调发布事宜。
• 当 PR 的开发者说明发布后，请移除该 PR 的 Needs Dev Note 标签。