设置组件在不同状态下的样式,适用于需要根据各种交互状态动态切换组件样式的场景,帮助开发者统一管理组件状态样式。
从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
从API version 11开始支持另一种写法attributeModifier,可根据开发者需要动态设置属性。
多态样式仅支持通用属性。如果多态样式不生效,则该属性可能为组件的私有属性,例如:fontColor、TextInput组件的backgroundColor等。此时,可以通过attributeModifier动态设置组件属性来解决此问题。
当前多态样式实现依赖于组件自定义节点的刷新机制。因Builder不具备独立的自定义父节点,无法直接触发刷新,致使多态样式无法直接在Builder中生效。解决方法是将多态样式封装至自定义组件内部,再将此组件置于@Builder中,以此来间接实现多态样式。示例代码可参考示例3(设置Builder多态样式)。
多态样式的焦点态只有在焦点激活态开启时生效。
如果组件同时处于多种状态,并且分别在各自的状态里设置了相同属性,那么最终生效样式由开发者设置顺序决定,后设置的样式生效。
stateStyles(value: StateStyles): T
设置组件不同状态的样式。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | StateStyles | 是 | 设置组件不同状态的样式。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件。 |
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| normal | any | 否 | 是 | 组件无状态时的样式。 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
| pressed | any | 否 | 是 | 组件按下状态的样式。 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
| disabled | any | 否 | 是 | 组件禁用状态的样式。 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
| focused | any | 否 | 是 | 组件获焦状态的样式。 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
| clicked | any | 否 | 是 | 组件点击状态的样式。 卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 |
| selected10+ | object | 否 | 是 | 组件选中状态的样式。 卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API version 11开始,该接口支持在元服务中使用。 模型约束: 此接口仅可在Stage模型下使用。 |
| hovered | object | 否 | 是 | 组件悬浮状态的样式。 起始版本: 26.0.0 卡片能力: 从API版本26.0.0开始,该接口支持在ArkTS卡片中使用。 元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。 模型约束: 此接口仅可在Stage模型下使用。 |
selected选中状态说明
pressed和clicked状态说明
该示例展示了stateStyles设置状态为hovered、pressed和disabled时Text组件的样式变化。
从API版本26.0.0开始,stateStyles新增hovered属性。
// xxx.ets
@Entry
@Component
struct StyleExample {
@State isEnable: boolean = true
@Styles
hoveredStyles(): void {
.backgroundColor('#12db70')
.borderRadius(10)
.borderStyle(BorderStyle.Dashed)
.borderWidth(2)
.borderColor('#33000000')
.width(120)
.height(30)
.opacity(1)
}
@Styles
pressedStyles(): void {
.backgroundColor('#ED6F21')
.borderRadius(10)
.borderStyle(BorderStyle.Dashed)
.borderWidth(2)
.borderColor('#33000000')
.width(120)
.height(30)
.opacity(1)
}
@Styles
disabledStyles(): void {
.backgroundColor('#E5E5E5')
.borderRadius(10)
.borderStyle(BorderStyle.Solid)
.borderWidth(2)
.borderColor('#2a4c1919')
.width(90)
.height(25)
.opacity(1)
}
@Styles
normalStyles(): void {
.backgroundColor('#0A59F7')
.borderRadius(10)
.borderStyle(BorderStyle.Solid)
.borderWidth(2)
.borderColor('#33000000')
.width(100)
.height(25)
.opacity(1)
}
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center }) {
Text('normal')
.fontSize(14)
.fontColor(Color.White)
.opacity(0.5)
// stateStyles设置组件无状态时的样式
.stateStyles({
normal: this.normalStyles,
})
.margin({ bottom: 20 })
.textAlign(TextAlign.Center)
Text('hovered')
.backgroundColor('#0A59F7')
.borderRadius(20)
.borderStyle(BorderStyle.Dotted)
.borderWidth(2)
.borderColor(Color.Red)
.width(100)
.height(25)
.opacity(1)
.fontSize(14)
.fontColor(Color.White)
// stateStyles设置组件鼠标悬浮状态时的样式
.stateStyles({
hovered: this.hoveredStyles,
})
.margin({ bottom: 20 })
.textAlign(TextAlign.Center)
Text('pressed')
.backgroundColor('#0A59F7')
.borderRadius(20)
.borderStyle(BorderStyle.Dotted)
.borderWidth(2)
.borderColor(Color.Red)
.width(100)
.height(25)
.opacity(1)
.fontSize(14)
.fontColor(Color.White)
// stateStyles设置组件按下状态时的样式
.stateStyles({
pressed: this.pressedStyles,
})
.margin({ bottom: 20 })
.textAlign(TextAlign.Center)
Text(this.isEnable ? 'effective' : 'disabled')
.backgroundColor('#0A59F7')
.borderRadius(20)
.borderStyle(BorderStyle.Solid)
.borderWidth(2)
.borderColor(Color.Gray)
.width(100)
.height(25)
.opacity(1)
.fontSize(14)
.fontColor(Color.White)
.enabled(this.isEnable)
// stateStyles设置组件禁用状态时的样式
.stateStyles({
disabled: this.disabledStyles,
})
.textAlign(TextAlign.Center)
Text('control disabled')
.onClick(() => {
this.isEnable = !this.isEnable;
console.info(`${this.isEnable}`);
})
}
.width(350).height(300)
}
} 
该示例展示了状态为selected时Radio组件的样式变化。
// xxx.ets
@Entry
@Component
struct Index {
@State isRadio1Selected: boolean = false
@State isRadio2Selected: boolean = false
@Styles
normalStyles(): void {
.backgroundColor('#E5E5E1')
}
@Styles
selectStyles(): void {
.backgroundColor('#ED6F21')
.borderWidth(2)
}
build() {
Flex({ direction: FlexDirection.Row, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
Column() {
Text('Radio1')
.fontSize(25)
Radio({ value: 'Radio1', group: 'radioGroup1' })
.checked(this.isRadio1Selected)
.height(50)
.width(50)
.borderWidth(0)
.borderRadius(30)
.onClick(() => {
this.isRadio1Selected = !this.isRadio1Selected;
})
.stateStyles({
normal: this.normalStyles,
selected: this.selectStyles,
})
}
.margin(30)
Column() {
Text('Radio2')
.fontSize(25)
Radio({ value: 'Radio2', group: 'radioGroup2' })
.checked($$this.isRadio2Selected)
.height(50)
.width(50)
.borderWidth(0)
.borderRadius(30)
.stateStyles({
normal: this.normalStyles,
selected: this.selectStyles,
})
}
.margin(30)
}.padding({ top: 30 })
}
} 
该示例展示了状态为pressed时@Builder中自定义组件的样式变化。
import { ComponentContent } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
@Component
struct Child {
build() {
Row()
.zIndex(10)
.width(200)
.height(200)
.stateStyles({
normal: {
.backgroundColor(Color.Blue)
},
pressed: {
.backgroundColor(Color.Black)
}
})
}
}
@Builder
function buildText() {
Child()
}
@Entry
@Component
struct Index {
private contentNode: ComponentContent<Object> =
new ComponentContent(this.getUIContext(), wrapBuilder(buildText));
build() {
Column() {
Button().margin({ top: 200 }).onClick(() => {
this.getUIContext()
.getPromptAction()
.openCustomDialog(this.contentNode)
.then(() => {
console.info('OpenCustomDialog complete.');
})
.catch((error: BusinessError) => {
let message = error.message;
let code = error.code;
console.error(`OpenCustomDialog args error code is ${code}, message is ${message}`);
});
})
}
.width('100%')
.height('100%')
}
} 