温馨提示:本篇博客的详细代码已发布到 git : https://gitcode.com/nutpi/HarmonyosNext 可以下载运行哦!

HarmonyOS NEXT 跑马灯组件详解(三):MarqueeSection基础结构

效果演示

1. 组件概述

MarqueeSection是一个实现文本滚动效果的自定义组件,主要用于显示超出显示区域的文本内容。

1.1 基本结构

@Component
export struct MarqueeSection {
  // 构建器参数
  @BuilderParam marqueeTextBuilder: () => void;
  
  // 动画配置
  marqueeAnimationModifier: MarqueeAnimationModifier;
  
  // 滚动配置
  marqueeScrollModifier: MarqueeScrollModifier;
}

2. 属性详解

2.1 构建器参数

@Builder
defaultMarqueeBuilder() {
    Text('')
}

@BuilderParam marqueeTextBuilder: () => void = this.defaultMarqueeBuilder;
  • @Builder:声明一个自定义构建函数
  • @BuilderParam:声明一个构建器参数
  • defaultMarqueeBuilder:默认的构建器实现

2.2 状态属性

// 文本偏移量
@State ticketCheckTextOffset: number = 0;

// 文本宽度
@State ticketCheckTextWidth: number = 0;

// 滚动区域宽度
@State ticketCheckScrollWidth: number = 0;

2.3 其他属性

// 滚动计数
count: number = 1;

// 定时器句柄
timer: number = -1;

3. 配置对象

3.1 动画配置

marqueeAnimationModifier: MarqueeAnimationModifier = new MarqueeAnimationModifier();

包含:

  • 动画持续时间
  • 播放速度
  • 播放模式
  • 延迟时间

3.2 滚动配置

marqueeScrollModifier: MarqueeScrollModifier = new MarqueeScrollModifier();

包含:

  • 滚动区域宽度
  • 文本间距

4. 生命周期处理

aboutToAppear(): void {
    // 清除定时器
    clearTimeout(this.timer);
}

5. 关键知识点

  1. 装饰器使用

    • @Component:声明自定义组件
    • @BuilderParam:声明构建器参数
    • @State:声明状态变量
  2. 默认值处理

    • 为构建器参数提供默认实现
    • 配置对象使用默认构造
  3. 状态管理

    • 使用@State管理动态数据
    • 确保状态变化触发视图更新
  4. 生命周期

    • aboutToAppear:组件即将出现
    • 资源清理和初始化

6. 使用示例

6.1 基本使用

MarqueeSection({
  marqueeTextBuilder: () => {
    Text('滚动文本内容')
      .fontSize(16)
      .fontColor('#333333')
  },
  marqueeAnimationModifier: new MarqueeAnimationModifier(),
  marqueeScrollModifier: new MarqueeScrollModifier()
})

6.2 自定义配置

MarqueeSection({
  marqueeTextBuilder: () => {
    Row() {
      Text('自定义内容')
      Image('icon.png')
    }
  },
  marqueeAnimationModifier: new MarqueeAnimationModifier(
    -1,    // 无限循环
    5000,  // 5秒一次
    1.5    // 1.5倍速
  ),
  marqueeScrollModifier: new MarqueeScrollModifier(
    '80%',  // 宽度
    20      // 间距
  )
})

7. 注意事项

  1. 构建器参数

    • 必须提供有效的构建函数
    • 考虑性能影响
    • 保持视图简洁
  2. 状态管理

    • 合理使用状态变量
    • 避免不必要的状态更新
    • 注意状态依赖关系
  3. 配置对象

    • 提供合理的默认值
    • 验证配置参数
    • 考虑边界情况

通过以上详细讲解,你应该能够理解MarqueeSection组件的基本结构和配置方式。这为后续深入理解组件的动画实现和滚动逻辑打下了基础。


全栈若城
1 声望1 粉丝