# class样式隔离策略 ## 背景 uni-app x中,有3种class样式 - 全局样式:在app.uvue里引入的class - 页面样式:页面中的style节点下的class - 组件样式:组件中的style节点下的class 这3者的影响关系,引用和覆盖,就是class样式隔离策略。 - 引用 指的是否能引用到某个class,比如组件里是否可以引用到页面中的class、全局的class。 - 覆盖 指的是同名时,谁能覆盖谁。比如全局的class中有一个classA,页面中也有一个classA、组件中也有一个classA,同名了,那么到底谁的优先级更高。 在实际开发中,有的组件是自己开发的、有的是引入三方组件,不同场景下隔离需求也不一样。 对于组件作者,大多不希望外部的class影响自身的样式,导致自己的组件不正常。 但有的组件作者,没有给组件使用者提供恰当的组件样式自定义方式,导致依赖被外部覆盖class来定制组件样式。 有些插件作者开发的不是组件,而是页面模板,尤其是基于dialogPage的页面插件,也同样存在如何让插件使用者自定义插件内样式的问题。 这是一个有点复杂的多边关系,需要一个明确的默认策略,并提供自定义方案。 在HBuilderX 5.0以前,这个关系并没有梳理清楚,web、各家小程序各有各的策略。 从HBuilderX 5.0起,全平台统一了样式隔离策略。**这可能会造成一定的向下兼容问题,开发者需要注意。** ## HBuilderX 5.0以前的策略 - web * 全局影响所有 * 页面、组件、父子组件之间隔离,互不影响 * 可以使用v-deep/deep向下穿透样式。 - 微信小程序和App * 全局影响所有 * 页面影响组件。父组件不影响子组件。 * 不支持v-deep * 同权重选择器下,优先级从低到高依次为:全局样式 < 页面样式 < 组件样式 ## HBuilderX 5.0+ 全平台统一样式隔离策略2.0 uni-app x 5.0起,提供了 `样式隔离策略2.0` 蒸汽模式仅支持`样式隔离策略2.0` VDOM 模式,考虑到向下兼容问题,目前没有废弃老版样式隔离策略,暂时默认是老策略。需要显式开启2.0策略。 ### VDOM 模式的开启方式 在manifest.json源码视图中设置:`manifest.json -> uni-app-x -> styleIsolationVersion: "2"`,可以开启`样式隔离策略2.0` ```json { "name": "Hello uni-app x", "appid": "__UNI__HelloUniAppX", "versionName": "2.0.0", "versionCode": 20000, "uni-app-x": { "styleIsolationVersion":"2" } } ``` 推荐插件作者在自己的项目下打开样式隔离策略2.0,尽快完成插件适配。主流插件作者陆续改造完毕后,HBuilderX将再次升级,调整为 VDOM 模式也默认使用样式隔离策略2.0,并逐步废弃老版样式隔离策略。 样式隔离策略2.0的详细介绍如下: ### 默认策略 - 全局影响页面 * 页面可以引用全局class,如果有同名class则合并,优先级页面>全局。 * 组件不可以引用全局class。 - 页面、组件、父子组件之间隔离,互不影响。 - 组件根样式传递依然生效,不受样式隔离策略影响 * 如果组件是单根节点,组件父层使用时给组件上设置class和style,会作用到组件的根节点。 * 如果组件是多根节点,父层使用时设置的class和style如何分配,需要组件内部写代码分配这些样式传递给哪些元素。 ### 自定义方式 #### isolated配置是否隔离 虽然有默认策略,但页面和组件,均支持通过配置样式隔离策略,单独声明自己是否允许被外部影响。 在` ``` - 选项式示例 推荐开发者尽快升级选项式为组合式,但样式隔离策略2.0在 VDOM 模式下也支持选项式写法。 ```vue ``` 本文所指的页面,不区分普通页面还是dialogPage。 本策略调整,会对插件市场的组件使用造成较大影响。 如果组件作者,希望保持向下兼容,即兼容HBuilderX 5.0以前的样式方案。可以在组件内配置app-and-page,允许全局和页面进行同名class合并。 但注意即便配置了app-and-page,只是尽可能减少向下兼容,和原来也有少许差异,即原本web下页面不能影响组件,配置app-and-page后会被影响。 #### external-class 当组件隔离后,不受外部class影响,那么组件的样式定制,就需要一套新的完善方案。 组件的根样式,可以通过父层使用组件时传入style或class来影响。 但很多组件有嵌套子组件,这些子组件也有开放给外部使用者来自定义样式的需求。 有一种方式是把子组件的样式,封装成组件属性。但这种属性封装有较多弊端: 1. 封装很多属性,组件作者麻烦。封装少了,组件使用者不够用 2. 属性太多导致组件性能不佳,初始化速度慢 3. 属性无法使用css变量,很多主题样式依赖css变量 在其他平台,有各自的解决方案: - 在web component中,默认也是样式隔离,但设计了一套::part伪元素方案来影响组件的子组件样式。 - 微信小程序提供的方案是external-class,通过组件属性名称修改组件内部子组件样式。 不过这2套方案无法跨到对方的平台。 uni-app x提供了一套跨平台的新方案。它的写法类似微信小程序的external-class,也是通过组件属性修改组件内部子组件样式。但为了跨平台,逻辑又与微信的实现有差异。 在过去的uni-app中,一直有一个用法,比如input组件的placeholder-class属性,传入一个class名称,可以修改input组件内部的placeholder的样式。 现在这套机制开放出来,所有组件作者都可以使用。 ##### external-class:外部影响组件子元素的方案 HBuilderX 5.0+,提供了可跨全平台的external-class,即组件把必要的子组件的样式暴露出去,外部可以传入一个class进行覆盖。相比属性封装,这样更优雅且高性能。 举个例子,假使有一个组件switch开关,它内部有2层结构,根view和圆球view。 根view的样式可以被父层直接设置的class和style影响,那么圆球view可以暴露一个 thumb-class 的扩展class被外部影响。 Switch组件示例源码: ```vue ``` 有了这样的组件,那么使用时在组件上写一个thumb-class属性,就可以定义组件的子组件样式: ```vue ``` 上面的代码,会让这个Switch组件的圆球变成红色。 以上只是举例,实际的switch组件要比上述例子复杂。可以参考Switch组件的[源码](https://gitcode.com/dcloud/uni-component/tree/alpha/uni_modules/uni-form) defineOptions中配置externalClasses,从HBuilderX5.0起支持。 总结下使用external-class需要做的事情: - 对于组件作者: 1. 给组件定义一个props属性,比如xxxClass 2. 给组件的子元素上绑定一个动态Class,值为xxxClass属性,比如 :class="xxxClass" 3. 在script中注册externalClasses,让编译器把外部使用者设置的样式编入组件内可生效,即`defineOptions({externalClasses: ['xxx-class']})` - 对于组件使用者: 1. 在组件属性上使用 xxx-class="yyy" 2. 在style里或全局里定义名为yyy的class 在HBuilderX 5.0之前,开发者会发现不写这个配置,在非web平台,也可以生效。 这是因为非web平台在HBuilderX 5.0之前,会默认把页面样式合并到组件中,也就是组件在非web平台默认不隔离,可以引用页面class。 从HBuilderX 5.0起,组件样式默认隔离,如果组件不配置`app`或`app-and-page`,就只能通过注册externalClasses来实现外部样式的影响。 **注意事项:** - 由于全局样式是最低优先级,如果传递给组件externalClasses的class是在全局App.uvue中定义的,且期望覆盖组件内部自身class的部分样式,需要给指定的css属性增加`!important;`。 - 为兼容小程序平台的组件规范,`externalClasses` 必须在组件定义阶段以静态字面量方式声明,且其内容需要在编译时可确定;不支持通过变量、表达式计算、函数返回值等方式动态生成。 ##### externalClasses 属性值的兼容性说明 @external-classes-compatibility HBuilderX 5.36+,组件使用者传入的外部样式类属性值,在组件内获取时由字符串数组调整为空格分隔的字符串。 直接使用该属性值进行 class 绑定不受影响,多个类名仍可使用 `:class="xxxClass"` 绑定,也可与组件内部类名通过数组绑定,例如 `:class="['inner-class', xxxClass]"`。 如果组件代码将该属性值当作数组使用,例如调用 `join()`、`map()` 等数组方法,需要改为按字符串处理。 ##### 组件避免外部过度干扰样式 如果组件作者有些样式并不想被外部自定义,那么可以写在组件的内联style中。由于class的优先级低于style,所以内联style永远生效(除非class中的样式定义为important)。 还是以Switch组件举例,假使组件源码中圆球view的style写了`border-width: 2px`,那么外部使用者无法改变圆球view的边框粗细。 ```vue ``` - 关于external-style的说明 除了external-class,其实组件作者也可以提供external-style。 此时可作为组件属性直接使用,无需在defineOptions中注册externalClasses。 external-style是内联字符串,不受样式隔离策略影响,它永远生效。所以在HBuilderX 5.0之前也是生效的。 但external-style有个需要注意的问题,这种方式会导致子组件所有样式都能被外部影响。 组件作者难以控制哪部分样式不允许被外部修改。可能出现使用者使用不当导致组件变形。 ```vue ``` ## 注意 再次提醒,以上介绍的styleIsolation、external-class等内容,均属于样式隔离策略2.0的内容。VDOM 模式的应用未开启 `manifest.json->uni-app-x->styleIsolationVersion: "2"` 是不会生效的。 默认策略下,父组件的样式不会影响子组件。但在web下子组件的根节点依然可能会受父组件的影响,所以需要尽可能避免在子组件的根节点加父组件的样式。 ### page 选择器与 CSS 变量继承 @page-css-variables 在 App.uvue 中通过 `page` 选择器定义的 CSS 变量,需要先作用于页面节点,再由页面内的子元素继承。例如: ```vue ``` 如果页面配置了 `styleIsolation: 'isolated'`,上述 `page` 规则不会作用于当前页面。页面及其内部组件没有另行定义 `--app-text-color` 时,使用 `var(--app-text-color)` 就无法获取该变量;如果指定了回退值,则使用回退值。变量定义在 `@media` 中时也遵循相同规则。 即使内部组件配置了 `styleIsolation: 'app-and-page'`,也不会改变所在页面的隔离策略。组件可以引用全局和页面的 class,但这不会使 App.uvue 中的 `page` 规则重新作用于该页面,因此无法恢复从页面继承的变量。这属于符合隔离语义的行为。 如果需要使用 App.uvue 中 `page` 选择器定义的变量,可以将页面的 `styleIsolation` 设置为 `app`(页面默认值)。如果需要保留页面隔离,则可以在当前页面或组件内部定义所需变量。CSS 变量的用法详见 [自定义 CSS 变量](./function.md#customvar)。