# HarmonyOS开发方案样式复用的两种策略

> 📌 **核心要点**：@Extend用于扩展原生组件属性，@Styles用于定义可复用的样式集合，两者各有适用场景
> 🎯 **适用版本**：HarmonyOS 5.0+ | API 12+
> 🔗 **官方文档**：[@Extend装饰器](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-extend-V5)

## 一、动机哦

写过UI的都知道，样式重复是代码膨胀的重灾区。比如你设计了一个主色调为绿色的按钮，结果代码里到处都是：

```arkts
Button('按钮1')
  .backgroundColor('#4CAF50')
  .fontColor('#FFFFFF')
  .borderRadius(8)

Button('按钮2')
  .backgroundColor('#4CAF50')
  .fontColor('#FFFFFF')
  .borderRadius(8)

// ...重复一百遍
```

你可能会想，把这些样式抽成一个函数不就行了？确实可以，但ArkUI提供了更优雅的方案：`@Extend`和`@Styles`。它们专门为样式复用设计，语法更简洁，类型检查更严格，还能配合IDE的智能提示使用。

## 二、看看

### 2.1 @Extend的工作机制

`@Extend`装饰的函数，用于**扩展原生组件的属性方法**。它只能装饰全局函数，并且函数名就是扩展后的方法名。

```mermaid
graph TD
    A[定义@Extend函数]:::primary --> B[指定目标组件类型]:::info
    B --> C[在函数内调用组件属性]:::info
    C --> D[编译时生成扩展方法]:::warning
    D --> E[组件可直接调用扩展方法]:::primary
    E --> F[样式自动应用]:::primary
    
    classDef primary fill:#4CAF50,stroke:#388E3C,color:#fff
    classDef warning fill:#FF9800,stroke:#F57C00,color:#fff
    classDef info fill:#2196F3,stroke:#1976D2,color:#fff
```

### 2.2 @Styles的工作机制

`@Styles`装饰的函数，用于**定义可复用的样式集合**。它可以在组件内部定义（成员Styles），也可以在组件外部定义（全局Styles）。

```arkts
// 全局Styles
@Styles function globalStyles() {
  .backgroundColor('#FFFFFF')
  .borderRadius(8)
  .padding(10)
}

@Component
struct Demo {
  // 成员Styles
  @Styles memberStyles() {
    .backgroundColor('#F5F5F5')
    .borderRadius(12)
  }

  build() {
    Column() {
      Text('全局样式')
        .globalStyles()  // 使用全局Styles

      Text('成员样式')
        .memberStyles()  // 使用成员Styles
    }
  }
}
```

### 2.3 两者的核心区别

| 特性         | @Extend          | @Styles          |
| ------------ | ---------------- | ---------------- |
| 定义位置     | 仅全局           | 全局或组件内     |
| 目标组件     | 指定单一组件类型 | 任意组件         |
| 参数支持     | ✅ 支持参数       | ❌ 不支持参数     |
| 访问组件状态 | ❌ 不可以         | ✅ 成员Styles可以 |
| 使用方式     | `.extendName()`  | `.stylesName()`  |

## 三、代码实战

### 3.1 基础用法：按钮样式扩展

使用`@Extend`为Button组件定义统一样式。

```arkts
// 按钮样式扩展 - @Extend基础用法

// 主按钮样式
@Extend(Button)
function primaryButton() {
  .backgroundColor('#4CAF50')
  .fontColor('#FFFFFF')
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .height(48)
  .borderRadius(24)
  .shadow({
    radius: 8,
    color: '#334CAF50',
    offsetX: 0,
    offsetY: 4
  })
}

// 次按钮样式
@Extend(Button)
function secondaryButton() {
  .backgroundColor('#FFFFFF')
  .fontColor('#333333')
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .height(48)
  .borderRadius(24)
  .border({ width: 1, color: '#E0E0E0' })
}

// 危险按钮样式
@Extend(Button)
function dangerButton() {
  .backgroundColor('#F44336')
  .fontColor('#FFFFFF')
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .height(48)
  .borderRadius(24)
}

// 禁用按钮样式
@Extend(Button)
function disabledButton() {
  .backgroundColor('#E0E0E0')
  .fontColor('#999999')
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .height(48)
  .borderRadius(24)
  .enabled(false)
}

// 使用扩展样式的页面
@Entry
@Component
struct ButtonExtendDemo {
  @State isDisabled: boolean = false

  build() {
    Column({ space: 20 }) {
      Text('按钮样式扩展演示')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)

      // 使用@Extend定义的样式
      Button('主按钮')
        .primaryButton()
        .onClick(() => {
          console.info('主按钮点击')
        })

      Button('次按钮')
        .secondaryButton()
        .onClick(() => {
          console.info('次按钮点击')
        })

      Button('危险操作')
        .dangerButton()
        .onClick(() => {
          console.info('危险按钮点击')
        })

      Button('禁用按钮')
        .disabledButton()

      // 切换禁用状态
      Button(this.isDisabled ? '启用' : '禁用')
        .primaryButton()
        .onClick(() => {
          this.isDisabled = !this.isDisabled
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .padding(30)
    .backgroundColor('#F5F5F5')
  }
}
```

### 3.2 进阶用法：带参数的@Extend

`@Extend`支持参数传递，实现更灵活的样式定制。

```arkts
// 带参数的样式扩展 - @Extend进阶用法

// 自定义颜色按钮
@Extend(Button)
function colorButton(bgColor: ResourceColor, textColor: ResourceColor = '#FFFFFF') {
  .backgroundColor(bgColor)
  .fontColor(textColor)
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .height(48)
  .borderRadius(24)
}

// 自定义尺寸按钮
@Extend(Button)
function sizeButton(width: number, height: number = 48) {
  .width(width)
  .height(height)
  .fontSize(14)
  .borderRadius(height / 2)
}

// 带边框的按钮
@Extend(Button)
function borderedButton(borderColor: ResourceColor, bgColor: ResourceColor = '#FFFFFF') {
  .backgroundColor(bgColor)
  .fontColor(borderColor)
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .height(48)
  .borderRadius(24)
  .border({ width: 2, color: borderColor })
}

// 文本样式扩展
@Extend(Text)
function styledText(fontSize: number, fontColor: ResourceColor, weight: FontWeight = FontWeight.Normal) {
  .fontSize(fontSize)
  .fontColor(fontColor)
  .fontWeight(weight)
  .maxLines(2)
  .textOverflow({ overflow: TextOverflow.Ellipsis })
}

// 使用带参数的Extend
@Entry
@Component
struct ParamExtendDemo {
  private colors: string[] = ['#4CAF50', '#2196F3', '#FF9800', '#E91E63', '#9C27B0']

  build() {
    Column({ space: 20 }) {
      Text('带参数的样式扩展')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)

      // 不同颜色的按钮
      Text('颜色定制:')
        .styledText(16, '#666')

      Row({ space: 10 }) {
        ForEach(this.colors, (color: string) => {
          Button('按钮')
            .colorButton(color)
        })
      }

      // 不同尺寸的按钮
      Text('尺寸定制:')
        .styledText(16, '#666')

      Row({ space: 10 }) {
        Button('小')
          .sizeButton(60, 32)

        Button('中')
          .sizeButton(100, 44)

        Button('大')
          .sizeButton(150, 56)
      }

      // 边框样式
      Text('边框样式:')
        .styledText(16, '#666')

      Row({ space: 10 }) {
        Button('绿色边框')
          .borderedButton('#4CAF50')

        Button('蓝色边框')
          .borderedButton('#2196F3')

        Button('红色边框')
          .borderedButton('#F44336')
      }

      // 文本样式
      Text('标题文本')
        .styledText(24, '#333333', FontWeight.Bold)

      Text('正文文本，这是一段比较长的内容，用来测试文本溢出效果')
        .styledText(14, '#666')
        .width(200)
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#F5F5F5')
  }
}
```

### 3.3 @Styles完整示例：卡片样式系统

使用`@Styles`构建完整的卡片样式系统，展示全局Styles和成员Styles的配合使用。

```arkts
// 卡片样式系统 - @Styles完整示例

// 全局基础样式
@Styles function cardBase() {
  .backgroundColor('#FFFFFF')
  .borderRadius(12)
  .shadow({
    radius: 8,
    color: '#1A000000',
    offsetX: 0,
    offsetY: 4
  })
}

@Styles function paddingMedium() {
  .padding(16)
}

@Styles function paddingLarge() {
  .padding(24)
}

// 文本样式
@Styles function titleText() {
  .fontSize(18)
  .fontWeight(FontWeight.Bold)
  .fontColor('#333333')
}

@Styles function subtitleText() {
  .fontSize(14)
  .fontColor('#666666')
}

@Styles function captionText() {
  .fontSize(12)
  .fontColor('#999999')
}

// 卡片组件
@Component
struct Card {
  @Prop title: string = ''
  @Prop subtitle: string = ''
  @Prop type: 'default' | 'highlight' | 'warning' = 'default'

  // 成员样式 - 根据类型动态设置
  @Styles cardStyle() {
    .cardBase()
    .paddingMedium()
    .border({
      width: this.type === 'default' ? 0 : 2,
      color: this.getBorderColor()
    })
  }

  private getBorderColor(): ResourceColor {
    switch (this.type) {
      case 'highlight':
        return '#4CAF50'
      case 'warning':
        return '#FF9800'
      default:
        return '#E0E0E0'
    }
  }

  @Builder
  CardContent() {
    Column({ space: 8 }) {
      Text(this.title)
        .titleText()

      if (this.subtitle) {
        Text(this.subtitle)
          .subtitleText()
      }
    }
    .alignItems(HorizontalAlign.Start)
  }

  build() {
    Column() {
      this.CardContent()
    }
    .cardStyle()
    .width('100%')
  }
}

// 列表项样式
@Styles function listItemStyle() {
  .backgroundColor('#FFFFFF')
  .borderRadius(8)
  .padding(12)
}

// 使用样式系统的页面
@Entry
@Component
struct StylesSystemDemo {
  @State cards: Array<{ title: string, subtitle: string, type: 'default' | 'highlight' | 'warning' }> = [
    { title: '默认卡片', subtitle: '这是默认样式的卡片', type: 'default' },
    { title: '高亮卡片', subtitle: '这是高亮样式的卡片', type: 'highlight' },
    { title: '警告卡片', subtitle: '这是警告样式的卡片', type: 'warning' }
  ]

  @State listItems: string[] = ['列表项一', '列表项二', '列表项三']

  build() {
    Scroll() {
      Column({ space: 20 }) {
        Text('样式系统演示')
          .fontSize(28)
          .fontWeight(FontWeight.Bold)
          .titleText()

        // 卡片区域
        Text('卡片样式')
          .subtitleText()

        ForEach(this.cards, (card: { title: string, subtitle: string, type: 'default' | 'highlight' | 'warning' }) => {
          Card({ title: card.title, subtitle: card.subtitle, type: card.type })
        })

        // 列表区域
        Text('列表样式')
          .subtitleText()

        Column({ space: 10 }) {
          ForEach(this.listItems, (item: string, index: number) => {
            Row() {
              Text(`${index + 1}`)
                .width(30)
                .height(30)
                .fontSize(14)
                .fontColor('#FFFFFF')
                .backgroundColor('#4CAF50')
                .borderRadius(15)
                .textAlign(TextAlign.Center)

              Text(item)
                .layoutWeight(1)
                .margin({ left: 10 })
                .subtitleText()
            }
            .listItemStyle()
            .width('100%')
          })
        }

        // 说明文本
        Column({ space: 5 }) {
          Text('样式复用说明')
            .titleText()

          Text('@Extend: 扩展原生组件，支持参数')
            .captionText()

          Text('@Styles: 定义样式集合，可访问组件状态')
            .captionText()
        }
        .cardBase()
        .paddingLarge()
        .width('100%')
        .alignItems(HorizontalAlign.Start)
      }
      .width('100%')
      .padding(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}
```

## 四、踩坑与注意事项

### 4.1 @Extend只能装饰全局函数

`@Extend`不支持在组件内部定义，这限制了它的灵活性。

```arkts
// ❌ 错误：@Extend不能定义在组件内
@Component
struct BadDemo {
  @Extend(Button)  // 编译错误！
  function myButton() {
    .backgroundColor('#4CAF50')
  }

  build() {
    Column() {
      Button('按钮')
        .myButton()
    }
  }
}

// ✅ 正确：@Extend定义在全局
@Extend(Button)
function myButton() {
  .backgroundColor('#4CAF50')
}

@Component
struct GoodDemo {
  build() {
    Column() {
      Button('按钮')
        .myButton()
    }
  }
}
```

### 4.2 @Extend必须指定组件类型

`@Extend`装饰的函数只能用于指定类型的组件。

```arkts
@Extend(Button)
function buttonStyle() {
  .backgroundColor('#4CAF50')
}

@Entry
@Component
struct TypeLimitDemo {
  build() {
    Column({ space: 10 }) {
      // ✅ 正确：Button可以使用
      Button('按钮')
        .buttonStyle()

      // ❌ 错误：Text不能使用Button的Extend
      // Text('文本')
      //   .buttonStyle()  // 编译错误！
    }
  }
}
```

### 4.3 @Styles不支持参数

`@Styles`装饰的函数不能有参数，需要动态样式时使用`@Extend`或成员Styles。

```arkts
// ❌ 错误：@Styles不支持参数
@Styles function coloredStyle(color: string) {  // 编译错误！
  .backgroundColor(color)
}

// ✅ 正确方案一：使用@Extend
@Extend(Column)
function coloredColumn(color: string) {
  .backgroundColor(color)
}

// ✅ 正确方案二：使用成员Styles + 组件状态
@Component
struct DynamicStyleDemo {
  @State bgColor: string = '#4CAF50'

  @Styles dynamicStyle() {
    .backgroundColor(this.bgColor)  // 可以访问组件状态
  }

  build() {
    Column() {
      Text('内容')
    }
    .dynamicStyle()
    .onClick(() => {
      this.bgColor = '#2196F3'  // 状态变化会触发样式更新
    })
  }
}
```

### 4.4 样式覆盖顺序

多个样式同时应用时，后应用的会覆盖先应用的。

```arkts
@Styles function baseStyle() {
  .backgroundColor('#4CAF50')
  .fontSize(16)
}

@Styles function overrideStyle() {
  .backgroundColor('#F44336')  // 会覆盖baseStyle的颜色
}

@Entry
@Component
struct OverrideDemo {
  build() {
    Column({ space: 10 }) {
      // 最终颜色是红色（overrideStyle覆盖了baseStyle）
      Button('按钮')
        .baseStyle()
        .overrideStyle()

      // 最终颜色是绿色（顺序相反）
      Button('按钮')
        .overrideStyle()
        .baseStyle()
    }
  }
}
```

### 4.5 成员Styles访问状态的限制

成员Styles可以访问组件状态，但不能在Styles内修改状态。

```arkts
@Component
struct StateAccessDemo {
  @State count: number = 0

  // ✅ 正确：可以读取状态
  @Styles counterStyle() {
    .backgroundColor(this.count > 5 ? '#4CAF50' : '#FF9800')
  }

  // ❌ 错误：不能在Styles内修改状态
  // @Styles badStyle() {
  //   .onClick(() => {
  //     this.count++  // 编译错误！
  //   })
  // }

  build() {
    Column() {
      Text(`${this.count}`)
        .counterStyle()
        .onClick(() => {
          this.count++  // 在外部修改
        })
    }
  }
}
```

## 五、HarmonyOS 6适配说明

### 5.1 API增强

HarmonyOS 6对`@Extend`和`@Styles`进行了以下增强：

1. **@Extend支持多组件类型**：一个Extend可以应用于多种组件
2. **@Styles支持泛型约束**：可以约束Styles适用的组件类型
3. **样式组合优化**：多个样式组合时性能更好

### 5.2 行为变更

| 行为            | HarmonyOS 5 | HarmonyOS 6      |
| --------------- | ----------- | ---------------- |
| @Extend组件类型 | 单一类型    | 支持多类型       |
| @Styles默认值   | 不支持      | 支持默认参数     |
| 样式优先级      | 后者优先    | 可显式指定优先级 |

### 5.3 适配代码示例

```arkts
// HarmonyOS 6新增特性

// 多组件类型的Extend
@Extend(Button, Text)  // 同时应用于Button和Text
function commonStyle() {
  .backgroundColor('#4CAF50')
  .fontColor('#FFFFFF')
  .borderRadius(8)
}

// 带泛型约束的Styles
@Styles<T extends CommonAttribute>
function genericStyle() {
  .backgroundColor('#F5F5F5')
  .borderRadius(12)
}

@Entry
@Component
struct HarmonyOS6Styles {
  @State priority: number = 1

  build() {
    Column({ space: 20 }) {
      Text('HarmonyOS 6样式新特性')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)

      // 多组件Extend
      Button('按钮')
        .commonStyle()

      Text('文本')
        .commonStyle()
        .padding(10)

      // 泛型Styles
      Column() {
        Text('内容')
      }
      .genericStyle()
      .padding(20)
    }
    .width('100%')
    .padding(20)
  }
}
```

## 六、总结

| 维度     | 评价  |
| -------- | ----- |
| 学习难度 | ⭐⭐⭐   |
| 使用频率 | ⭐⭐⭐⭐⭐ |
| 重要程度 | ⭐⭐⭐⭐  |

`@Extend`和`@Styles`是ArkUI样式复用的两大利器。`@Extend`适合扩展特定组件的属性方法，支持参数传递，灵活性高；`@Styles`适合定义通用的样式集合，可以在组件内定义并访问组件状态。

使用建议：

- 需要参数化样式时，使用`@Extend`
- 需要访问组件状态时，使用成员`@Styles`
- 全局通用样式，使用全局`@Styles`
- 特定组件的样式扩展，使用`@Extend`
- 注意样式覆盖顺序，后应用的优先

两者配合使用，可以构建出简洁、可维护的样式系统。下一篇我们讲自定义组件的事件回调机制。

📌 核心要点：@Extend用于扩展原生组件属性，@Styles用于定义可复用的样式集合，两者各有适用场景 🎯 适用版本：HarmonyOS 5.0+ | API 12+ 🔗 官方文档：@Extend装饰器

HarmonyOS开发方案样式复用的两种策略

前端

开发工具

客户端

HarmonyOS开发中@Extend和@Styles是样式复用的核心方案。@Extend用于扩展原生组件属性，支持参数传递；@Styles定义可复用样式集合，可访问组件状态。两者配合能构建高效UI样式系统，提升开发效率，适用于HarmonyOS5.0+版本。

代码解释

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

HarmonyOS开发方案样式复用的两种策略-腾讯云开发者社区-腾讯云

HarmonyOS开发方案样式复用的两种策略

HarmonyOS开发方案样式复用的两种策略

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐