HarmonyOS RcList 组件事件处理机制与实战应用

常用 API 如下表所示：

事件综合应用示例

以下是一个完整可运行的页面，综合演示所有交互机制：

import { RcList, RcListItem } from 'rchoui'

@Entry
@ComponentV2
struct RcListInteractionDemo {
    // 开关状态
    @Local switchA: boolean = true
    @Local switchB: boolean = false
    @Local switchC: boolean = true

    // 操作日志
    @Local logs: string[] = []

    // 滚动控制器
    private scroller: Scroller = new Scroller()

    // 添加日志
    private addLog(msg: string): void {
        const time = new Date().toLocaleTimeString()
        this.logs = [`[${time}] ${msg}`, ...this.logs.slice(0, 9)]
    }

    build() {
        Column({ space: 0 }) {
            // 日志区域
            Column() {
                Text('操作日志').fontSize(14).fontWeight(FontWeight.Medium).margin({ bottom: 8 })
                ForEach(this.logs.slice(0, 5), (log: string) => {
                    Text(log).fontSize(12).fontColor('#606266').width('100%')
                }, (log: string): string => log)
                if (this.logs.length === 0) {
                    Text('暂无操作记录').fontSize(12).fontColor('#c0c4cc')
                }
            }.width('100%').padding(12).backgroundColor('#fff').border({ width: { bottom: 1 }, color: '#e4e7ed', style: BorderStyle.Solid })

            Scroll() {
                Column({ space: 16 }) {
                    // ===== 1. 点击交互 =====
                    Text('点击交互').fontSize(16).fontWeight(FontWeight.Medium).margin({ top: 16, bottom: 4 })
                    RcList({ rcListBorder: true }) {
                        RcListItem({
                            rcListItemTitle: '普通点击项',
                            rcListItemNote: '点击后记录日志',
                            rcListItemClickable: true,
                            onRcListItemClick: () => {
                                this.addLog('点击了「普通点击项」')
                            }
                        })
                        RcListItem({
                            rcListItemTitle: '带右侧文字',
                            rcListItemRightText: '详情',
                            rcListItemClickable: true,
                            onRcListItemClick: () => {
                                this.addLog('点击了「带右侧文字」，即将跳转')
                            }
                        })
                        RcListItem({
                            rcListItemTitle: '无按压反馈',
                            rcListItemNote: '不设置 clickable，无视觉反馈',
                            rcListItemClickable: false,
                            onRcListItemClick: () => {
                                this.addLog('点击了「无按压反馈」，事件仍然触发')
                            }
                        })
                    }

                    // ===== 2. 禁用状态 =====
                    Text('禁用状态保护').fontSize(16).fontWeight(FontWeight.Medium).margin({ bottom: 4 })
                    RcList({ rcListBorder: true }) {
                        RcListItem({
                            rcListItemTitle: '正常可点击',
                            rcListItemNote: '点击会触发事件',
                            rcListItemDisabled: false,
                            rcListItemClickable: true,
                            onRcListItemClick: () => {
                                this.addLog('「正常项」被点击')
                            }
                        })
                        RcListItem({
                            rcListItemTitle: '已禁用（不可点击）',
                            rcListItemNote: '即使设置了 clickable 也无效',
                            rcListItemDisabled: true,
                            rcListItemClickable: true,
                            onRcListItemClick: () => {
                                this.addLog('这行永远不会出现在日志中')
                            }
                        })
                        RcListItem({
                            rcListItemTitle: '已禁用的开关',
                            rcListItemNote: '开关无法切换',
                            rcListItemShowSwitch: true,
                            rcListItemSwitchChecked: true,
                            rcListItemDisabled: true,
                            rcListItemShowArrow: false
                        })
                    }

                    // ===== 3. 开关交互 =====
                    Text('开关状态管理').fontSize(16).fontWeight(FontWeight.Medium).margin({ bottom: 4 })
                    RcList({ rcListBorder: true }) {
                        RcListItem({
                            rcListItemTitle: '通知推送',
                            rcListItemNote: this.switchA ? '已开启' : '已关闭',
                            rcListItemShowSwitch: true,
                            rcListItemSwitchChecked: this.switchA,
                            rcListItemShowArrow: false,
                            onRcListItemSwitchChange: (checked: boolean) => {
                                this.switchA = checked
                                this.addLog(`通知推送：${checked ? '开启' : '关闭'}`)
                            }
                        })
                        RcListItem({
                            rcListItemTitle: '自动更新',
                            rcListItemNote: this.switchB ? '已开启' : '已关闭',
                            rcListItemShowSwitch: true,
                            rcListItemSwitchChecked: this.switchB,
                            rcListItemShowArrow: false,
                            onRcListItemSwitchChange: (checked: boolean) => {
                                this.switchB = checked
                                this.addLog(`自动更新：${checked ? '开启' : '关闭'}`)
                            }
                        })
                        RcListItem({
                            rcListItemTitle: '定位服务',
                            rcListItemNote: this.switchC ? '已开启' : '已关闭',
                            rcListItemShowSwitch: true,
                            rcListItemSwitchChecked: this.switchC,
                            rcListItemShowArrow: false,
                            rcListItemShowBorder: false,
                            onRcListItemSwitchChange: (checked: boolean) => {
                                this.switchC = checked
                                this.addLog(`定位服务：${checked ? '开启' : '关闭'}`)
                            }
                        })
                    }

                    // ===== 4. 滚动事件 =====
                    Text('滚动事件监听').fontSize(16).fontWeight(FontWeight.Medium).margin({ bottom: 4 })
                    Row({ space: 8 }) {
                        Button('回到顶部').onClick(() => {
                            this.scroller.scrollEdge(Edge.Top)
                            this.addLog('手动滚动到顶部')
                        })
                        Button('跳到底部').onClick(() => {
                            this.scroller.scrollEdge(Edge.Bottom)
                            this.addLog('手动滚动到底部')
                        })
                    }
                    RcList({
                        rcListHeight: 240,
                        rcListScrollable: true,
                        rcListScroller: this.scroller,
                        rcListScrollBarState: BarState.On,
                        rcListBorder: true,
                        onRcListScrollToLower: () => {
                            this.addLog('滚动到底部，可加载更多')
                        },
                        onRcListScrollToUpper: () => {
                            this.addLog('滚动到顶部，可下拉刷新')
                        }
                    }) {
                        ForEach(Array.from<number, number>({ length: 15 }, (_: number, i: number): number => i), (index: number) => {
                            RcListItem({
                                rcListItemTitle: `滚动列表项 ${index + 1}`,
                                rcListItemNote: `这是第 ${index + 1} 条数据`,
                                rcListItemRightText: `${index + 1}`,
                                rcListItemClickable: true,
                                onRcListItemClick: () => {
                                    this.addLog(`点击了第 ${index + 1} 项`)
                                }
                            })
                        }, (index: number): string => `scroll-item-${index}`)
                    }
                    Text('事件演示结束').fontSize(13).fontColor('#909399').textAlign(TextAlign.Center).margin({ top: 8, bottom: 30 })
                }.width('100%').padding(16)
            }.layoutWeight(1).backgroundColor('#f5f5f5')
        }.width('100%').height('100%')
    }
}

常见交互场景速查

禁用状态的注意事项

1. 视觉透明度：禁用时整体 opacity: 0.6，不需要单独修改子元素样式
2. 事件彻底阻断：onRcListItemClick 在 handleRcListItemClick 中被拦截，不穿透
3. 开关同步禁用：rcListItemDisabled 会自动传递给内部 RcSwitch，无需额外设置
4. 仅禁用视觉：如果只想改变外观而不阻断事件，可以不用 rcListItemDisabled，直接通过 opacity 修改

总结

RcList 的交互系统经过精心分层：点击反馈与事件回调独立控制，禁用保护穿透视觉与行为双层，开关状态通过 @Local 内部状态实现解耦，滚动事件分三粒度按需监听，外部 Scroller 支持命令式控制。每个交互能力都可以独立使用，也可以自由组合，构成了一套完整、健壮的列表交互体系。

掌握这些交互机制，你可以实现设置页面、消息列表、联系人等高频应用场景，而无需关心底层的事件冒泡和状态管理细节。