鸿蒙 ArkUI 开发踩坑笔记：@Styles 为什么会报 CommonAttribute 错误？

在鸿蒙 ArkUI（声明式 UI）开发中，为了减少 UI 代码冗余，我们经常会把公共样式提取出来。但如果你尝试像下面这样提取文本样式：

// ❌ 错误写法
@Styles
commonStyle() {
  .fontSize(12)
  .fontColor("#aaa")
}

编译器会直接飘红并抛出错误：Property 'fontSize' does not exist on type 'CommonAttribute'. <ArkTSCheck>。

报错原因：通用属性与特有属性的隔离

在 ArkUI 的设计中，组件的属性被严格划分了界限。@Styles 装饰器只能用于提取所有组件都通用的属性（CommonAttribute）。

• 通用属性：比如宽高（width / height）、边距（margin / padding）、背景色（backgroundColor）等，这些是任何组件挂载后都能使用的。

• 特有属性：而 .fontSize() 和 .fontColor() 属于 Text 等文本类组件的专属属性，并不属于通用大类。

当你在 @Styles 中写 .fontSize() 时，编译器在通用属性池里找不到这个方法，就会报出类型不匹配的错误。

解决方案：使用 @Extend

想要复用特定组件（如 Text）的专属样式，正确的做法是使用 @Extend 装饰器。它专门用于扩展原生组件的样式，不仅支持该组件的所有特有属性，还能传递参数，比 @Styles 更加灵活。

// ✅ 正确写法
// 注意：@Extend 必须定义在全局（即组件的 struct 外部）
@Extend(Text) function textStyle(size: number = 12) {
  .fontSize(size)
  .fontColor("#aaa")
}

@Entry
@Component
struct MyComponent {
  build() {
    Column({ space: 10 }) {
      Text("这是复用了默认样式的文本")
        .textStyle() // 直接调用，使用默认字体大小12
      
      Text("这是支持传参的文本")
        .textStyle(14) // 传入参数，字体大小变为14
    }
  }
}

避坑总结：@Styles 与 @Extend 的核心区别

日常开发中，只要记住以下这张对比表，就能避免 99% 的样式复用报错：