如何构建低侵入性Vaadin Web组件？CSS与向后兼容问题咨询

1. Vaadin及通用Web组件中CSS Parts的安全样式范围 #

• 优先使用组件官方文档明确声明的稳定CSS Parts：这类parts是组件作者承诺向后兼容的公开样式接口，你可以放心对其进行样式定制，只要不违背组件设计的核心逻辑，不会破坏后续版本的兼容性。
• 绝对避免依赖未公开的内部parts：未出现在文档中的parts属于组件实现细节，作者可能在任意版本中修改、移除，依赖它们会直接导致样式在版本更新后失效。
• 谨慎修改核心布局属性：对于负责组件内部布局的parts（比如avatar-group的布局容器part），不要随意修改display、flex-direction这类核心布局属性——即使组件暴露了这个part，这类属性是组件正常工作的基础，修改后很可能导致组件功能异常，且后续版本迭代中这类属性的变更概率极高。
• 留意Vaadin组件的part状态：Vaadin会标注parts是「稳定（Stable）」还是「实验性（Experimental）」，实验性parts可能在小版本中就发生变更，使用前要评估风险。

2. 构建高兼容性Web组件的最佳实践 #

• 隔离核心布局到Shadow DOM深层：不要把组件的核心布局容器（比如决定排列方式的flex容器）作为公开part暴露，而是将其放在Shadow DOM的内部层级，只暴露用户真正需要定制的视觉元素（比如avatar的图片、文字标签）。这样用户无法直接修改核心布局属性，从根源降低组件失效的概率。
• 明确区分公开与内部样式接口：只将需要用户自定义的元素设为CSS Parts，内部的辅助容器、状态提示元素等一律隐藏，不对外暴露样式接口。
• 使用CSS变量替代直接修改布局属性：给组件提供预设的CSS变量（比如--avatar-item-gap、--avatar-size）来控制布局和尺寸，而不是让用户直接修改内部容器的gap、width等属性。即使后续内部布局结构调整，CSS变量的接口可以保持稳定。
• 版本化样式接口：如果必须变更已公开的CSS Parts，要在大版本更新中进行，并提供详细的迁移指南，必要时可以保留旧的parts别名一段时间，给用户足够的过渡周期。
• 限制Parts的可修改属性：利用CSS的::part()的allowed-properties特性（部分浏览器已支持），限制用户能对某个part修改的属性，比如只允许修改颜色、字体，禁止修改display、position这类核心布局属性。
• 文档清晰标注风险：在组件文档中明确说明每个CSS Part的用途，以及修改哪些属性可能导致组件失效，提前给用户预警。

内容的提问来源于stack exchange，提问作者Daniel van Mil