更新记录

1.0.3（2026-10-13）

• 修复 bubbleBackground 属性不生效：此前传值会落回默认深色背景，现气泡主体与箭头统一使用自定义背景
• 修复长按弹出气泡后继续拖动手指仍会触发左滑的问题（气泡打开时拦截滑动）
• 修复气泡弹出瞬间在左上角一闪再跳位的问题：量测完成前保持隐藏
• 分割线起始位置改为随 avatarSize 动态计算，避免自定义头像尺寸后错位

平台兼容性

uni-app(5.0)

其他

hy-message-list 仿QQ消息列表

hy-message-list 是一个 uni-app（Vue2 / Vue3） 的仿 QQ 消息列表组件，数据驱动、开箱即用：

• 传入 messages 数组即可渲染完整会话列表；
• 支持左滑露出操作栏（收藏、标记已读、删除等，数量与颜色可配）；
• 支持长按弹出气泡操作菜单（可开关，自动避让屏幕边界，保证完整可见）；
• 头像支持圆形 / 方形 / 圆角；标题、内容、时间齐全；支持未读数字角标与小红点两种通知形式。

同时提供 uni-app x 版本：hy-message-list-x。

功能特性

• 数据驱动：messages 数组 + actions / bubbleActions 操作配置，无需手写列表结构
• 左滑操作栏
  • 支持自定义文字颜色（actionTextColor / 单项 color）与背景（actionBackground / 单项 background）
  • 支持限制操作数量（maxActions），操作栏宽度受容器约束，永不超出页面宽度
  • 支持固定按钮宽度（actionWidth）或按内容自适应；actionRadius 可设圆角
• 长按气泡操作栏
  • 通过 enableBubble 控制开关；bubbleDuration 控制长按触发时长
  • 位置跟随长按点：气泡以手指长按的水平位置为中心弹出，超宽时自动夹紧
  • 默认在消息上方弹出，上方空间不足自动改到下方，并做水平夹紧，保证完整落在屏幕内
  • 文字颜色（bubbleTextColor / 单项 color）与背景（bubbleBackground）可自定义
  • 长按后轻微移动或抬手会自动取消，不影响正常点击与滑动
• 标题标记：可在标题左侧显示自定义标记文字，颜色、背景、边框、圆角、字号、内外间距均可配置
• 互斥收起：任何时刻只允许一项左滑展开；打开左滑栏会自动收起气泡，打开气泡会自动收起左滑栏
• 统一收起：点击任意消息、开始任意滑动、点击气泡遮罩，左滑栏与气泡栏都会同时收起
• 通知提醒：badge 数字角标（超过 badgeMax 显示 99+）与 dot 小红点，二者均可用 showBadge / showDot 全局开关
• 头像 avatarShape 支持 circle 圆形与 square 方形（avatarRadius 控制圆角）

安装

将 hy-message-list 目录放入项目的 uni_modules 目录即可，组件已支持 easycom，无需手动 import。

基本用法

<template>
    <hy-message-list :messages="messages" :actions="actions" :bubble-actions="bubbleActions" :max-actions="3"
        avatar-shape="circle" :enable-bubble="true" @item-click="onItemClick" @action="onAction"
        @bubble-action="onBubbleAction" />
</template>

<script>
    export default {
        data() {
            return {
                messages: [
                    { id: 1, avatar: '/static/a.png', title: '张三', content: '晚上一起吃饭吗？', time: '12:30', badge: 3 },
                    { id: 2, avatar: '/static/b.png', title: '产品群', content: '李四：需求已更新', time: '11:02', badge: 99, dot: true },
                    { id: 3, avatar: '/static/c.png', title: '王五', content: '收到，谢谢！', time: '昨天', dot: true }
                ],
                actions: [
                    { text: '标为未读', background: '#f0a020' },
                    { text: '置顶', background: '#3b7cff' },
                    { text: '删除', background: '#f43b3b' }
                ],
                bubbleActions: [
                    { text: '复制' },
                    { text: '转发' },
                    { text: '撤回' }
                ]
            }
        },
        methods: {
            onItemClick(e) {
                uni.showToast({ title: '点击：' + e.item.title, icon: 'none' })
            },
            onAction(e) {
                uni.showToast({ title: e.action.text + '：' + e.item.title, icon: 'none' })
            },
            onBubbleAction(e) {
                uni.showToast({ title: e.action.text + '：' + e.item.title, icon: 'none' })
            }
        }
    }
</script>

完整可运行示例见本工程 pages/message-list/message-list.vue。

数据结构

MessageItem

ActionItem

属性 Props

左滑操作栏

长按气泡操作栏

外观与通知

标题标记（tag）

事件 Events

方法 Methods

平台支持

注意事项

1. 组件为数据驱动的整列列表，数据请通过 messages 传入，不要在外层再用 v-for 包裹。
2. actions 数量较多时建议设置 maxActions 限制显示数量；操作栏采用 flex 布局并限制在容器宽度内，不会横向溢出页面，超宽时按钮会等比压缩并对文字做省略。
3. 长按气泡的位置基于 uni.createSelectorQuery 实测行位置计算，默认在消息上方弹出；上方空间不足时自动改为下方并夹紧到屏幕内，保证完整可见。
4. 左滑与气泡互斥：打开其中一个会自动收起另一个；点击消息、开始滑动、点击气泡遮罩均会统一收起。
5. 本组件不涉及输入框，无 input / textarea 兼容性问题。