# 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)。