前端UI组件【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址https://gitcode.com/gh_mirrors/ha/handsontable点击查看免费下载本篇技术指南围绕 Handsontable 仓库中的破坏性变更Breaking Changes策略展开它既是 monorepo 全仓统一的工程约束也是维护者与 AI Agent 在改动公共 API 时必须遵守的操作手册。通过本文你将掌握什么变更会被判定为破坏性变更、如何区分 Legacy保留与 Deprecated弃用两种兼容策略、一次规范弃用流程的完整检查清单以及为什么把any回调参数收窄为具名类型在 TypeScript 下几乎必然破坏构建。文中的结论均可在 .ai/BREAKING-CHANGES.md 及其引用的源码console.ts、constants.ts、core.ts中逐一验证。核心原则能不加破坏就不加破坏破坏性变更策略是整个 monorepo 中最重要的单一约束。仓库根目录的 AGENTS.md 中设有精简版的 Breaking changes policy 章节该章节总是随上下文加载而 .ai/BREAKING-CHANGES.md 是它的完整参考。策略的第一句话直接给出态度Agents must try to avoid introducing breaking changes.Existing customers depend on API stability.也就是说默认动作是避免引入破坏性变更——现有客户依赖 API 稳定性。当某个解决方案确实需要破坏性变更时必须在方案描述中用加粗明确标注state it inbold让评审者一眼看到风险点。这一原则的实际效果贯穿整个代码库Handsontable 的公共 API 面方法、配置选项、hooks在设计时就要为长期稳定负责任何改动都要先评估它是否属于下表中的破坏性类型。什么算破坏性变更文档用一张决策表界定了四类破坏性变更每一类都给出了为什么破坏和应该怎么做变更类型为什么破坏应该怎么做重命名 Handsontable 生成的 CSS 类破坏客户自定义样式表在 DOM 中保留旧类名并添加测试验证旧名称仍然生效重命名 API方法、配置选项、hooks破坏客户集成保留旧 API 继续工作内部把旧调用翻译到新 APILegacy API 不输出控制台警告修改 API 签名或行为破坏客户集成让被弃用的 API 一直工作到下一个大版本弃用 API 输出一次控制台警告移除 hooks 或配置选项客户可能毫无察觉把 hook 加入 constants.ts 的REMOVED_HOOKS或把选项加入 core.ts 的REMOVED_OPTIONS让使用者在配置时看到警告其中有一条被单独标为 严格禁止修改默认设置值Changing a default setting value。文档称之为 really bad 级别的破坏性变更无论什么理由都不得更改默认值——因为默认值一旦变化所有未显式配置该项的既有客户都会在无感知的情况下改变行为属于最隐蔽的破坏方式。移除 hook / 选项的运行时警告机制移除 hooks 或配置选项之所以单独列出是因为这种变更最容易被客户忽略——代码不会立刻报错客户往往要等到某个功能悄悄失效才发现。因此仓库实现了两套使用即警告的机制Hook 侧REMOVED_HOOKS是一个Mapstring, string键是 hook 名值是其被移除的版本号。从源码看当前登记的有modifyRow、modifyCol、unmodifyRow、unmodifyCol、skipLengthCache、hiddenColumn、hiddenRow均在 8.0.0 移除以及persistentStateSave、persistentStateLoad、persistentStateReset17.0.0 移除见 constants.ts。当用户通过Hooks.add()注册这些 hook 时index.ts 会输出一条模板化警告指出该 hook 在哪个版本被移除并附上 release notes 链接供查阅迁移路径// 实际输出形式由 REMOVED_MESSAGE 模板生成 // The plugin hook modifyRow was removed in Handsontable 8.0.0. // Please consult release notes https://github.com/handsontable/handsontable/releases/tag/8.0.0 // to learn about the migration path.注意此警告不带Deprecated:前缀——被移除的 API 不是已弃用而是已经不存在了措辞必须直说。同时它是通过普通warn()在每次add()时输出详见 handsontable/.ai/HOOKS.md 中 Removed and deprecated hooks 一节。选项侧REMOVED_OPTIONS是一个对象数组每个条目包含name选项名、version移除版本、migrationUrl迁移文档地址。warnAboutRemovedOptions会同时扫描顶层 settings、columns数组和cell数组三个作用域一旦发现被移除的选项被使用就通过removedWarnOnce输出一次警告例如// 实际输出形式 // The persistentState setting was removed in Handsontable 17.0.0 and is ignored. // See https://handsontable.com/docs/javascript-data-grid/changelog-17/ for the migration path.与 hook 警告不同选项警告遵循一次规则removedWarnOnce而非deprecatedWarnOnce即每个页面只输出一次。实现细节见 core.ts 的warnAboutRemovedOptions与 console.ts 的removedWarnOnce。窄化any回调参数为何必然破坏构建文档对修改 API 签名这一行做了专门的展开如果一个公共选项或 hook 的回调把参数声明为any或者通过...args: any[]吸收参数不能贸然把它收窄为具名类型——这会在三个相互独立的轴上破坏客户构建。该结论在 DEV-2620 中通过tsc对sanitizer选项做了实际验证。轴破坏什么报错赋值逆变Assignment contravariance在strictFunctionTypes下函数类型属性对参数做逆变检查消费者把回调参数标注得比你声明的更窄会被拒绝。方法语法opt?(a, b): R不受此限制可通过此轴TS2322调用参数个数Call arity在 rest 参数前声明一个具名参数会抬高选项的最小调用参数个数消费者按旧参数个数调用时失败。与方法/属性语法无关两种形式都会破坏TS2555可选性Optionality把参数声明为可选可以解决 arity 轴但参数类型会变成T \| undefined任何把它当确定值使用的消费者函数体都会失败TS2345 / TS18048关键认知有三点可赋值性与可调用性是两套独立的检查——只做赋值回调的类型测试抓不到 arity 轴的问题DEV-2620 实测过多种签名形状函数类型属性、方法语法、可选参数、重载、带标签元组的 rest...args: [b?: T, ...rest: any[]]、rest 联合[] | [b: T, ...rest: any[]]没有任何一种能同时通过三个轴。文档明确这是被测量的集合而非不存在任何可行签名的证明零破坏的正规路线保持回调签名原样不动把联合类型导出为具名类型让消费者在自己的参数上按需选择使用。这样从构造上就不会破坏任何现有调用。只有当声明全新的回调没有存量用户时才值得考虑使用方法语法。Legacy 与 Deprecated两种兼容策略的分界线很多项目把旧 API 还在笼统称为弃用但 Handsontable 的策略对两种状态做了严格区分状态含义行为测试要求Legacy旧 API 与新 API 永久并存一直可用不输出任何控制台警告旧功能集可能被冻结测试必须验证旧名称持续可用Deprecated旧 API 工作到下一个大版本之后被移除输出一次性控制台警告测试必须验证旧名称在被移除前一直可用从 console.ts 的实现可以看出两者的工程区别deprecatedWarnOnce打印的消息带Deprecated:前缀而removedWarnOnce不带。两者共享同一个warnOncePerKey去重逻辑——printedDeprecations是一个模块级Set同一个 key 每个页面只警告一次与网格实例数量无关这正是弃用策略承诺的one-time warning。一个值得注意的实现细节warnOncePerKey只在console对象可用时记录 key。如果第一次调用时console不存在如某些 IE 场景不会消耗该 key后续调用仍能正常警告——避免首次静默烧掉整页警告的坑。测试弃用警告的正确姿势由于printedDeprecations是模块全局状态且生产环境从不重置任何断言警告只输出一次的测试都依赖执行顺序——如果别的 spec 先打印了同一个 key 的警告你的断言会静默通过其实是假通过。因此必须在beforeEach中调用_resetDeprecationWarnings()清空记录该函数在 console.ts 中标记为 test-onlyprivate。import { _resetDeprecationWarnings } from handsontable/src/helpers/console; beforeEach(() { _resetDeprecationWarnings(); });弃用公共 API 的六步检查清单当确实需要弃用一个公共 API 时以下六步必须在同一个 PR中完成缺一不可1. JSDoc 标注写完整的deprecated标签格式为deprecated Since X.Y.Z. reason. It will be removed in next major. Use replacement instead.——绝不允许裸写deprecated因为 API 文档会把该文本渲染成警告框缺失原因与替代方案会让使用者无所适从。2. 运行时警告方法、选项、helpers调用 console.ts 的deprecatedWarnOnce(Owner.name, message)。类型无法在运行时发出警告因此对纯类型层面的弃用JSDoc 标签已经足够。3. 测试保留一个证明旧 API 仍然可用的测试以及一个证明警告只打印一次的测试。后者必须在beforeEach中调用_resetDeprecationWarnings()理由见上文。4. 文档在 deprecation-policy.md 的 List of current deprecations 表格中新增一行如果该版本发布了迁移指南minor 版本通常没有还要在迁移指南中加入对应步骤。从该文档当前内容可以看到真实案例例如Handsontable.helper.sanitize()自 18.0 弃用、预计 19.0 移除替代方案是sanitizer选项saveManualRowHeights()/loadManualRowHeights()ManualRowResize同样是 18.0 弃用、19.0 移除。5. Changelog新增.changelogs/PR.json其中type: deprecated。6. 移除只能在下一个大版本且至少 3 个月后进行——删除代码、把文档行移到 Removed in version N.0、新增type: removed, breaking: true的 changelog 条目、并补充迁移步骤。// .changelogs/PR.json 的示例结构 { type: deprecated, breaking: false }什么不算破坏性变更内部命名空间边界并非所有改动都值得启动弃用流程。策略明确凡未列入公共 API 参考文档的 JavaScript API 变更例如不影响 DOM 或 CSS 的内部 Walkontable 代码不视为破坏性变更只需在 release notes 中注明。Handsontable.helper与Handsontable.dom属于内部命名空间这两个命名空间在 API 参考中没有页面——docs/content/api/sidebar.js 既没有 helpers 条目也没有 DOM 条目也没有任何机制为它们生成文档。它们由 handsontable/src/index.ts 中的一段循环在运行时填充把HELPERS和DOM列表helpers/array、helpers/function、helpers/dom/element等中每个模块的导出全部复制到全局对象上跳过以下划线_开头的名字base.ts用相同的typeof import(...)交集方式为它们提供类型。由此推出一个工程结论向这些模块新增一个导出会自动出现在全局对象上属于纯增量不是破坏性变更——不需要 changelog 条目、不需要文档页、不需要弃用周期。_前缀的唯一作用是让运行时复制跳过该名字如helpers/mixed.ts中的_injectProductInfo和_getLicenseState但类型仍会列出它——所以前缀只是把它从对象上隐藏而不是从 TypeScript 中隐藏。不过有两个成员打破了这条规则属于例外而非模式Handsontable.dom.empty()—— 出现在一份指南的 cell-renderer 示例中Handsontable.helper.sanitize()—— 在弃用策略表中有对应行18.0 弃用、19.0 移除。凡是被指南教给用户的成员实践中就是公共 API理应获得完整的弃用周期。而移除或重命名这两个命名空间中其他任何成员依然属于需要权衡判断的动作而非免费操作——它们被打进 bundle应用确实会用到。实践建议把兼容策略写进日常开发综合上述策略与源码实现可以把 Handsontable 的破坏性变更治理浓缩为几条可操作的原则改动前先分类对照四类破坏性变更表格判断你的改动属于哪一类如果只是给内部模块加导出直接提交即可含_前缀的除外。默认保留旧 API重命名 API 时让旧 API 继续工作内部做翻译层不要为 Legacy API 加警告加警告的是 Deprecated API。绝不动默认值这是唯一的硬性红线。弃用要成套提交JSDoc、运行时警告、双测试、文档表、changelog 五项在同一 PR 完成移除则要等到下一大版本并走完整移除流程。窄化any回调参数前先验证DEV-2620 已经证明常见签名形状无法同时通过逆变、arity、可选性三轴检查优先采用导出具名联合类型 消费者按需选择的零破坏路线。测试假通过陷阱任何断言警告只输出一次的 spec 都必须在beforeEach调用_resetDeprecationWarnings()否则会因模块全局状态而静默假通过。这套策略的价值在于它把不破坏客户从口号落实为可执行的检查表与可验证的运行时机制让每个贡献者无论是人还是 AI Agent都能在提交前自行判断改动的影响面并通过REMOVED_HOOKS、REMOVED_OPTIONS、deprecatedWarnOnce等机制把兼容性保障内建到运行时与测试体系之中。相关源码与文档可继续参阅 handsontable/src/core/hooks/constants.ts、handsontable/src/core.ts、handsontable/.ai/HOOKS.md 以及 docs/content/guides/upgrade-and-migration/deprecation-policy/deprecation-policy.md。赞分享前端UI组件【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址https://gitcode.com/gh_mirrors/ha/handsontable点击查看免费下载相关推荐pytest 向后兼容性政策全解读从弃用警告到真正的破坏性变更pytest 向后兼容性政策全解读从弃用警告到真正的破坏性变更 本文系统梳理 pytest 官方 backwards compatibility.rst ht测试开发工具CuPy API 兼容性策略全解版本管理、弃用流程与向后兼容边界CuPy API 兼容性策略全解版本管理、弃用流程与向后兼容边界 导读 本文以 CuPy 官方兼容性策略文档 docs/source/user_guide/科学计算高性能计算Prototool破坏性变更检测确保API向后兼容性的10个技巧在Protocol Buffers API开发中 Prototool破坏性变更检测 是维护API稳定性的关键工具。作为Protocol Buffers的多功能开发工具上一篇al-baka-llama3-8b-experimental高级应用终极提示词工程与阿拉伯语对话优化指南下一篇探索高效动画新境界jQueryAnimate-Enhanced插件深度解读创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考