HarmonyOS6 clickEffect 通用属性使用指南

文章目录

- [1. 核心特性](#1. 核心特性)
- [2. clickEffect 完整参数说明](#2. clickEffect 完整参数说明)
- - [2.1 基础语法](#2.1 基础语法)
  - [2.2 ClickEffectOptions 配置项](#2.2 ClickEffectOptions 配置项)
  - [2.3 ClickEffectLevel 枚举说明](#2.3 ClickEffectLevel 枚举说明)
- [3. 官方示例代码解析](#3. 官方示例代码解析)
- - [3.1 代码结构说明](#3.1 代码结构说明)
  - [3.2 关键代码解析](#3.2 关键代码解析)
  - - [3.2.1 Switch 类型 Toggle（轻量点击反馈）](#3.2.1 Switch 类型 Toggle（轻量点击反馈）)
    - [3.2.2 Checkbox 类型 Toggle（中度点击反馈）](#3.2.2 Checkbox 类型 Toggle（中度点击反馈）)
    - [3.2.3 Button 类型 Toggle（重度点击反馈）](#3.2.3 Button 类型 Toggle（重度点击反馈）)
- 总结

本文结合 HarmonyOS 官方 Toggle 组件示例代码，详细讲解 clickEffect 的语法、参数及在不同 Toggle 类型中的实战用法，严格对齐华为官方文档规范。

1. 核心特性

特性	说明
适用版本	HarmonyOS API 10+（Stage 模型）
支持组件	Toggle、Button、Text、Image、List 等可点击组件
核心能力	自定义点击反馈强度、缩放比例，实现轻/中/重三种点击效果
最佳实践	结合 Toggle 组件（Switch/Checkbox/Button 类型）适配不同交互场景
无侵入性	不影响组件原有功能，仅增强点击视觉反馈

2. clickEffect 完整参数说明

2.1 基础语法

typescript 复制代码

clickEffect(value: ClickEffectOptions)

2.2 ClickEffectOptions 配置项

参数名	类型	取值范围	说明
level	ClickEffectLevel	LIGHT / MIDDLE / HEAVY	点击反馈强度（核心参数） - LIGHT：轻度反馈（最弱，适合开关类组件） - MIDDLE：中度反馈（适中，适合选择类组件） - HEAVY：重度反馈（最强，适合按钮类组件）
scale	number	0~1	点击时的缩放比例，默认值 1（无缩放）；值越小，点击时组件缩小越明显

2.3 ClickEffectLevel 枚举说明

枚举值	视觉反馈强度	适用场景
ClickEffectLevel.LIGHT	轻度（微弱的按压/高亮效果）	Switch 开关、轻量交互组件
ClickEffectLevel.MIDDLE	中度（明显的按压反馈）	Checkbox 复选框、列表项
ClickEffectLevel.HEAVY	重度（强烈的按压+缩放效果）	Button 按钮、核心操作组件

3. 官方示例代码解析

3.1 代码结构说明

以下为 HarmonyOS 官方提供的 Toggle 组件结合 clickEffect 的完整示例，覆盖 Switch、Checkbox、Button 三种 Toggle 类型，展示不同强度的点击反馈配置：

typescript 复制代码

@Entry
@Component
struct ToggleExample {
  build() {
    Column({ space: 10 }) {
      Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
        Toggle({ type: ToggleType.Switch, isOn: false })
          .clickEffect({ level: ClickEffectLevel.LIGHT })
          .selectedColor('#007DFF')
          .switchPointColor('#FFFFFF')
          .onChange((isOn: boolean) => {
            console.info('Component status:' + isOn);
          })

        Toggle({ type: ToggleType.Switch, isOn: true })
          .clickEffect({ level: ClickEffectLevel.LIGHT, scale: 0.5 })
          .selectedColor('#007DFF')
          .switchPointColor('#FFFFFF')
          .onChange((isOn: boolean) => {
            console.info('Component status:' + isOn);
          })
      }

      Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%')
      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
        Toggle({ type: ToggleType.Checkbox, isOn: false })
          .clickEffect({ level: ClickEffectLevel.MIDDLE })
          .size({ width: 20, height: 20 })
          .selectedColor('#007DFF')
          .onChange((isOn: boolean) => {
            console.info('Component status:' + isOn);
          })

        Toggle({ type: ToggleType.Checkbox, isOn: true })
          .clickEffect({ level: ClickEffectLevel.MIDDLE, scale: 0.5 })
          .size({ width: 20, height: 20 })
          .selectedColor('#007DFF')
          .onChange((isOn: boolean) => {
            console.info('Component status:' + isOn);
          })
      }

      Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%')
      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
        Toggle({ type: ToggleType.Button, isOn: false }) {
          Text('status button').fontColor('#182431').fontSize(12)
        }.width(106)
        .clickEffect({ level: ClickEffectLevel.HEAVY })
        .selectedColor('rgba(0,125,255,0.20)')
        .onChange((isOn: boolean) => {
          console.info('Component status:' + isOn);
        })

        Toggle({ type: ToggleType.Button, isOn: true }) {
          Text('status button').fontColor('#182431').fontSize(12)
        }.width(106)
        .clickEffect({ level: ClickEffectLevel.HEAVY, scale: 0.5 })
        .selectedColor('rgba(0,125,255,0.20)')
        .onChange((isOn: boolean) => {
          console.info('Component status:' + isOn);
        })
      }
    }.width('100%').padding(24)
  }
}

代码运行时，当鼠标点击的时候，整体会相应的减小，点击完毕大小回弹：

3.2 关键代码解析

3.2.1 Switch 类型 Toggle（轻量点击反馈）

typescript 复制代码

Toggle({ type: ToggleType.Switch, isOn: false })
  .clickEffect({ level: ClickEffectLevel.LIGHT }) // 轻度反馈，适配开关类组件
Toggle({ type: ToggleType.Switch, isOn: true })
  .clickEffect({ level: ClickEffectLevel.LIGHT, scale: 0.5 }) // 轻度反馈+点击缩放0.5倍

设计逻辑 ：Switch 作为轻量交互组件，选择 LIGHT 级别反馈，避免过度干扰视觉；可选 scale 参数增强点击感知（缩放至原尺寸的 50%）。
配套属性 ：selectedColor 定义开关开启态颜色，switchPointColor 定义开关滑块颜色，与点击反馈形成统一视觉风格。

3.2.2 Checkbox 类型 Toggle（中度点击反馈）

typescript 复制代码

Toggle({ type: ToggleType.Checkbox, isOn: false })
  .clickEffect({ level: ClickEffectLevel.MIDDLE }) // 中度反馈，适配选择类组件
Toggle({ type: ToggleType.Checkbox, isOn: true })
  .clickEffect({ level: ClickEffectLevel.MIDDLE, scale: 0.5 }) // 中度反馈+点击缩放0.5倍

设计逻辑 ：Checkbox 作为选择类组件，需要明显的点击反馈，选择 MIDDLE 级别；通过 size 固定组件尺寸（20×20），确保缩放效果一致。
交互优化：点击时的中度按压反馈+缩放，让用户清晰感知选择状态变化。

3.2.3 Button 类型 Toggle（重度点击反馈）

typescript 复制代码

Toggle({ type: ToggleType.Button, isOn: false })
  .clickEffect({ level: ClickEffectLevel.HEAVY }) // 重度反馈，适配按钮类组件
Toggle({ type: ToggleType.Button, isOn: true })
  .clickEffect({ level: ClickEffectLevel.HEAVY, scale: 0.5 }) // 重度反馈+点击缩放0.5倍

设计逻辑 ：Button 作为核心操作组件，需要强烈的点击反馈，选择 HEAVY 级别；通过 width 固定按钮宽度（106px），selectedColor 定义选中态背景色（半透明蓝色）。
体验提升：重度按压+缩放效果，模拟真实物理按钮的按压感，强化操作确认感。

总结

clickEffect 是 HarmonyOS API 10+ 提升交互体验的核心属性，通过 level 和 scale 可灵活控制点击反馈效果。
官方示例针对 Switch/Checkbox/Button 三种 Toggle 类型，适配了轻/中/重三种反馈强度，符合交互设计最佳实践。
使用时需注意 API 版本兼容性，为组件固定尺寸可确保缩放效果一致。
该属性可复用至所有可点击组件，是实现统一、自然点击反馈的关键手段。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！