更新记录

1.0.2（2026-10-13）

• 修复长按弹出气泡后继续拖动手指仍会触发左滑的问题（气泡打开时拦截滑动）
• 修复气泡弹出瞬间在左上角一闪再跳位的问题：量测完成前保持隐藏
• 分割线起始位置改为随 avatarSize 动态计算，避免自定义头像尺寸后错位

平台兼容性

uni-app x(4.66)

其他

hy-message-list-x 仿QQ消息列表

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

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

uni-app（Vue2 / Vue3）版本请见：hy-message-list。 本组件为 uni-app x 版本，仅适用于 uni-app 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-x 目录放入 uni-app x 项目的 uni_modules 目录即可，组件已支持 easycom，无需手动 import。

基本用法

<template>
    <hy-message-list-x :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 setup lang="uts">
    type MessageItem = {
        id ?: any,
        avatar ?: string,
        title ?: string,
        content ?: string,
        time ?: string,
        badge ?: number,
        dot ?: boolean,
        tag ?: string,
        tagColor ?: string,
        tagBackground ?: string,
        tagBorderColor ?: string
    }

    type ActionItem = {
        text : string,
        color ?: string,
        background ?: string
    }

    type ClickPayload = {
        item : MessageItem,
        index : number
    }

    type ActionPayload = {
        item : MessageItem,
        index : number,
        action : ActionItem,
        actionIndex : number
    }

    const a1 : ActionItem = { text: '标为未读', background: '#f0a020' }
    const a2 : ActionItem = { text: '置顶', background: '#3b7cff' }
    const a3 : ActionItem = { text: '删除', background: '#f43b3b' }
    const actions = ref<ActionItem[]>([a1, a2, a3])

    const b1 : ActionItem = { text: '复制' }
    const b2 : ActionItem = { text: '转发' }
    const b3 : ActionItem = { text: '撤回' }
    const bubbleActions = ref<ActionItem[]>([b1, b2, b3])

    const m1 : MessageItem = { id: 1, title: '张三', content: '晚上一起吃饭吗？', time: '12:30', badge: 3 }
    const m2 : MessageItem = { id: 2, title: '产品群', content: '李四：需求已更新', time: '11:02', dot: true }
    const messages = ref<MessageItem[]>([m1, m2])

    const onItemClick = (e : ClickPayload) => {
        uni.showToast({ title: '点击：' + e.item.title!, icon: 'none' })
    }
    const onAction = (e : ActionPayload) => {
        uni.showToast({ title: e.action.text, icon: 'none' })
    }
    const onBubbleAction = (e : ActionPayload) => {
        uni.showToast({ title: e.action.text, icon: 'none' })
    }
</script>

完整可运行示例见组件目录 example/example.uvue，将其拷入 uni-app x 工程并在 pages.json 注册后即可运行。

数据结构

MessageItem

ActionItem

属性 Props

左滑操作栏

长按气泡操作栏

外观与通知

标题标记（tag）

事件 Events

方法 Methods

平台支持

注意事项

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