【共创季稿事节】HarmonyOS 6.1 API23新特性实战：Marquee跑马灯组件进阶用法
承接上篇《基于ArkTS的状态管理机制深度解析》，本文基于已调通的 DevEco Studio 6.1 + API23 环境，实测 Marquee 组件在 HarmonyOS 6.1 中的三项增强，并给出可直接复用的电商长标题场景代码。
一、前言：从"环境地狱"爬出来后的第一份实测
前两周卡在 SDK Lock 和 API 12/23 双环境切换的兼容坑里，差点以为赶不上共创季稿事节。昨天终于把 DevEco Studio 6.1 + Compile SDK 6.1.0 (API 23) 的环境调通，第一时间翻了官方 API23 更新日志，发现Marquee 组件的优化非常克制且实用——不是堆参数，而是精准戳中旧版的三个痛点。
之前做电商类 Demo 时，长商品标题溢出屏幕是常态，旧版本 Marquee 没法自定义首尾间距，两段文本衔接像"连体婴"，也没有原生点击暂停，交互很僵硬。这次实测下来，新特性的适配成本极低（改 2 行代码），效果提升却很明显，特意整理成实操文，给同样在踩 API23 坑的新手朋友。
二、API23 Marquee 新特性拆解（对照旧版）
翻官方 API23 变更日志，Marquee 这次动了三个点，咱们逐个对：
特性 | 旧版（API 12 及以下） | API23 新增强 | 适用场景 |
|---|---|---|---|
首尾间距 | 无，文本首尾硬接 | 新增 | 电商标题、通知栏，避免衔接生硬 |
滚动速度 | 只能靠 | 新增 | 不同屏幕尺寸精准控速 |
交互 | 需自己写定时器暂停 | 原生支持 | 点击标题暂停查看、再次点击恢复 |
💡 一个认知点：
spacing和scrollAmount的参数类型是number，API23 内部已默认按 vp 处理，不要再包'100vp'字符串——这点后面踩坑节会展开。
三、代码实现（API23 专属，复制可用）
3.1 完整代码（Index.ets）
// 必须导包，否则 Color.Grey 会报 "Cannot find name 'Color'" import { Color } from '@kit.ArkUI' @Entry @Component struct MarqueeDemo { // 控制跑马灯暂停/播放 @State isPaused: boolean = false // 长文本，模拟电商超长商品标题 private longText: string = '【API23新特性】HarmonyOS 6.1 定制款超长商品标题，支持自定义间距和点击暂停，适配多端设备' // 点击计数（状态反馈用） @State clickCount: number = 0 build() { Column({ space: 30 }) { // —— 页面标题 —— Text('HarmonyOS 6.1 Marquee 新特性演示') .fontSize(24) .fontWeight(FontWeight.Bold) .margin({ top: 20 }) // ===== 旧版本效果（对照组的存在感很重要）===== Text('旧版本效果（无间距/无点击暂停）') .fontSize(16) .fontColor(Color.Grey) Marquee({ start: true, step: 2, loop: -1, fromStart: true, src: this.longText }) .width(300) .height(40) .backgroundColor('#f5f5f5') .padding(10) .margin({ bottom: 20 }) // ===== API23 新版本（核心亮点）===== Text('API23 新特性效果（自定义间距 + 点击暂停）') .fontSize(16) .fontColor(Color.Grey) Marquee({ start: !this.isPaused, // 绑定暂停状态 step: 2, loop: -1, fromStart: true, src: this.longText, spacing: 100, // 【API23】两段文本间距 100vp scrollAmount: 30 // 【API23】每秒滚动 30vp }) .width(300) .height(40) .backgroundColor('#e8f4ff') .padding(10) // 【API23 原生点击暂停，不用自己写定时器】 .onClick(() => { this.isPaused = !this.isPaused this.clickCount++ }) // —— 状态反馈区（让"交互生效"肉眼可见）—— Column({ space: 10 }) { Text(`当前状态：${this.isPaused ? '已暂停' : '滚动中'}`) .fontSize(18) .fontColor(this.isPaused ? Color.Red : Color.Green) Text(`点击次数：${this.clickCount}`) .fontSize(16) Text('提示：点击上方蓝色区域可暂停/恢复') .fontSize(14) .fontColor(Color.Grey) } .margin({ top: 20 }) } .width('100%') .height('100%') .alignItems(HorizontalAlign.Center) } }3.2 代码里的三个"API23 标记点"
spacing: 100：旧版没有，文本首尾不再"黏在一起"scrollAmount: 30：替代旧版靠step猜速度的别扭写法.onClick()直接绑@State：不用自己维护setInterval做暂停/恢复，框架接管
四、运行效果（远程模拟器实拍）
环境：DevEco Studio 6.1 → Device Manager →Remote Emulator → Phone API23。
状态 | 表现 |
|---|---|
初始态 | 上方灰底跑马灯（旧版）+ 下方蓝底跑马灯（API23版）同时滚动，状态区显示"滚动中" |
点击蓝底跑马灯 | 蓝底停下，状态切为"已暂停"，点击次数 +1 |
再点击 | 蓝底恢复滚动，状态切回"滚动中" |
五、踩坑记录（官方文档没写的细节）
5.1spacing传'100vp'反而报错
最开始我按"所有尺寸加 vp"的旧习惯写了spacing: '100vp'，编译器直接甩：
Type 'string' is not assignable to type 'number'查了 API23 源码签名才发现：spacing和scrollAmount的参数类型是number，内部已按 vp 换算，传纯数字100就行。这个坑官方文档示例里没强调，新手极易按旧惯性踩。
5.2Color.Grey报Cannot find name 'Color'
代码里用了Color.Grey / Red / Green，但忘了导包：
// 必须加这一行，否则编译器不认 Color import { Color } from '@kit.ArkUI'这个坑在前一篇 @State 文里也提过——ArkTS 的枚举类基本都要显式导包，养成"用枚举先导包"的肌肉记忆能省很多事。
5.3 Preview 又双叒叕不刷新
改完spacing切 Preview，还是跑的旧效果。老办法：File → Invalidate Caches → Invalidate and Restart，清完再开 Preview 才认新参数。这个属于 DevEco 6.1 的通病，三篇文里反复出现，已经能构成"系列共性踩坑"了。
六、总结与延伸
Marquee 在 API23 的这次增强，定位很清晰——不是让你"能用"，而是让你"好用"。spacing解决视觉衔接、scrollAmount解决控速直觉、onClick + @State解决交互 boilerplate，三个点都打在旧版的痛处上。
适配成本 vs 收益比：改 2 行代码（加两个参数 + 绑一个 onClick），就能让电商长标题、首页公告栏、行情滚动这类场景的体验上一个台阶，性价比很高。
💡 下一篇预告：把这颗 Marquee 嵌进"电商商品列表页"，结合上一篇的
@State+ 即将展开的@Link做父子状态传递，实现"点击商品卡片 → 标题暂停 + 底部弹详情"的小交互，把 API23 新特性和状态管理串成一条线。