如何在含Shadow DOM的Vaadin应用中全局自定义所有滚动条样式

核心实现逻辑 #

完全不需要为每个Web组件的Shadow DOM单独维护滚动条样式，借助浏览器的原生规则和Vaadin的全局样式能力，就能实现一次定义、全应用所有滚动容器（包括Shadow DOM内部的）通用的效果：

• 早前旧版本Chromium浏览器之所以出现全局滚动条样式无法作用于Shadow DOM的问题，是因为当时严格限制了::-webkit-scrollbar选择器的作用域，只允许样式在所属的DOM树内生效，不做跨Shadow边界的继承。
• 现在主流的Chromium内核版本（Chrome 111+、Edge 111+）已经调整了规则，把滚动条作为元素本身的渲染附属UI，根节点定义的滚动条样式会自动穿透所有层级的Shadow DOM边界，应用到内部的滚动容器上。
• Firefox支持的scrollbar-width、scrollbar-color属性从推出开始就原生支持跨Shadow DOM的样式继承，不需要额外处理。

具体实现步骤 #

1. 在Vaadin项目的frontend目录下创建全局滚动条样式文件（比如frontend/styles/global-scrollbar.css）
2. 将滚动条配置写入该文件，参考如下代码：

   :root {
     /* Firefox 兼容配置，原生支持跨Shadow DOM继承 */
     scrollbar-width: thin;
     scrollbar-color: #888 #f1f1f1;
   }
   
   /* Chromium 内核自定义滚动条配置，Chrome 111+ 自动跨Shadow DOM生效 */
   ::-webkit-scrollbar {
     width: 8px;
     height: 8px;
   }
   
   ::-webkit-scrollbar-track {
     background: #f1f1f1;
     border-radius: 4px;
   }
   
   ::-webkit-scrollbar-thumb {
     background: #888;
     border-radius: 4px;
   }
   
   ::-webkit-scrollbar-thumb:hover {
     background: #555;
   }
   

3. 在应用的根布局类上通过@CssImport注解将该全局样式引入，确保样式被直接注入到文档最外层的<head>标签中，而不是嵌套在某个组件的局部作用域内：

   @CssImport(value = "./styles/global-scrollbar.css")
   public class MainLayout extends AppLayout {
       // 布局逻辑
   }
   

旧版本浏览器兼容方案 #

如果你的应用需要支持Chrome 111以下的旧版本，也不需要逐个为组件添加Shadow DOM样式，只需要实现一次通用的自动注入逻辑即可：

• 监听Vaadin应用的组件挂载、Shadow Root创建事件
• 将同一份滚动条样式内容，自动注入到每个新创建的Shadow Root内部
• 所有Shadow Root共享同一份样式源，后续调整滚动条样式只需要修改一次源文件，全应用自动同步生效，没有重复维护的成本。

落地注意事项 #

• 务必将滚动条样式放在项目级的全局样式文件中，通过根布局类引入，确保样式直接注入到文档最外层的<head>标签里，不要嵌在某个组件的局部样式作用域内，否则样式会被限制在局部DOM树中无法全局生效。
• 不需要额外编写::deep、::part这类穿透选择器，现代浏览器的滚动条样式穿透是自动完成的。
• Vaadin内置组件（比如vaadin-grid、vaadin-rich-text-editor、支持滚动的文本域）内部的滚动容器，在上述配置下会自动应用全局样式，不需要做额外适配。

内容的提问来源于stack exchange，提问作者Robert P