LiveChat

live-chat

直播公屏 · 高频自动滚消息流 + message/enter(进场)/gift(送礼)/follow(关注)/system(系统)五类型默认皮肤 + 等级牌/身份徽标 + 置顶区 + 上滚查看历史时浮出「N 条新消息」恢复钮(贴底判定) + maxItems 窗口限流 + renderItem 逃生舱 + overlay 浅色态(叠加深色视频上白字) · 区别 AI 轮次制 Conversation

用法

基础用法

items 受控追加，组件自动滚到底；支持 message / enter / gift / follow / system 多种消息类型。

欢迎来到直播间，文明发言哦~

夜航船来了

12阿白：主播好~

momo 关注了主播 ❤

小鹿送出💖 小心心×6

3Kris：求链接

28豆豆龙：下单了

tsx

<LiveChat
  items={[
    { id: "s0", type: "system", text: "欢迎来到直播间~" },
    { id: "e1", type: "enter", user: { name: "夜航船" } },
    { id: "m1", type: "message", user: { name: "阿白", level: 12 }, text: "主播好~" },
    { id: "g1", type: "gift", user: { name: "小鹿" }, gift: { name: "小心心", icon: "💖", combo: 6 } },
  ]}
/>

置顶公告

pinned 渲染在顶部置顶区（公告/规则），不参与滚动流。

置顶今晚 8 点抽奖，关注不迷路

欢迎来到直播间，文明发言哦~

夜航船来了

12阿白：主播好~

momo 关注了主播 ❤

小鹿送出💖 小心心×6

3Kris：求链接

28豆豆龙：下单了

tsx

<LiveChat
  items={items}
  pinned={[{ id: "p1", type: "system", text: "今晚 8 点抽奖，关注不迷路" }]}
/>

视频叠加态

overlay 用于叠在深色视频上的 C 端公屏：藏滚动条、顶部渐隐、文字转白并带阴影。

欢迎来到直播间，文明发言哦~

夜航船来了

12阿白：主播好~

momo 关注了主播 ❤

小鹿送出💖 小心心×6

3Kris：求链接

28豆豆龙：下单了

tsx

<div className="relative aspect-[9/16] bg-black">
  <video ... />
  <div className="absolute inset-x-2 bottom-2 h-48">
    <LiveChat items={items} overlay className="h-full" />
  </div>
</div>

何时用

直播间公屏：高频追加多类型消息（发言/进场/送礼/关注/系统公告）并自动贴底滚动。需要叠在视频上时开 overlay。本组件是单向广播式滚动流；要 AI 多轮问答用 Conversation，要纯日志着色用 LogViewer。

导入

import { LiveChat } from "@hulianui/ui"

Props

名称	类型	默认	说明
items*	`LiveChatItem[]`	—	消息流（受控，追加）
pinned	`LiveChatItem[]`	—	顶部置顶区（公告/规则）
autoScroll	`boolean`	`true`	自动滚到底；用户上滚时暂停并浮出「N 条新消息」恢复钮
maxItems	`number`	`200`	滚动窗保留上限（性能）
overlay	`boolean`	`false`	叠在深色视频上的浅色态（文字改白/半透白 + 文字阴影）
className	`string`	—	容器自定义类

Slots

插槽	类型	说明
renderItem	`(item: LiveChatItem) => ReactNode`	渲染函数：自定义单条消息渲染（逃生舱）

LiveChatItem：{ id: string; type: "message"｜"enter"｜"gift"｜"follow"｜"system"; user?: LiveChatUser; text?: ReactNode; gift?: { name; icon?; combo? }; at?: string }。
LiveChatUser：{ name: string; avatar?: string; level?: number; badge?: ReactNode }（level 渲染等级牌，badge 渲染房管/铁粉等身份徽标）。

禁忌 / 坑

自动贴底依赖「当前是否贴底」判定：用户上滚查看历史时 autoScroll 暂停，浮出「N 条新消息」钮，点它才恢复贴底——不要在外部强行 scrollTo 干扰。
items 须给容器固定高度（如 className="h-full" + 父容器定高），否则滚动区无法形成。
高频追加时靠 maxItems 截断窗口；不要把全量历史塞进 items。

用法

基础用法

items 受控追加，组件自动滚到底；支持 message / enter / gift / follow / system 多种消息类型。

欢迎来到直播间，文明发言哦~

夜航船来了

12阿白：主播好~

momo 关注了主播 ❤

小鹿送出💖 小心心×6

3Kris：求链接

28豆豆龙：下单了

tsx

<LiveChat
  items={[
    { id: "s0", type: "system", text: "欢迎来到直播间~" },
    { id: "e1", type: "enter", user: { name: "夜航船" } },
    { id: "m1", type: "message", user: { name: "阿白", level: 12 }, text: "主播好~" },
    { id: "g1", type: "gift", user: { name: "小鹿" }, gift: { name: "小心心", icon: "💖", combo: 6 } },
  ]}
/>

置顶公告

pinned 渲染在顶部置顶区（公告/规则），不参与滚动流。

置顶今晚 8 点抽奖，关注不迷路

欢迎来到直播间，文明发言哦~

夜航船来了

12阿白：主播好~

momo 关注了主播 ❤

小鹿送出💖 小心心×6

3Kris：求链接

28豆豆龙：下单了

tsx

<LiveChat
  items={items}
  pinned={[{ id: "p1", type: "system", text: "今晚 8 点抽奖，关注不迷路" }]}
/>

视频叠加态

overlay 用于叠在深色视频上的 C 端公屏：藏滚动条、顶部渐隐、文字转白并带阴影。

欢迎来到直播间，文明发言哦~

夜航船来了

12阿白：主播好~

momo 关注了主播 ❤

小鹿送出💖 小心心×6

3Kris：求链接

28豆豆龙：下单了

tsx

<div className="relative aspect-[9/16] bg-black">
  <video ... />
  <div className="absolute inset-x-2 bottom-2 h-48">
    <LiveChat items={items} overlay className="h-full" />
  </div>
</div>

Props

名称	类型	默认	说明
items*	`LiveChatItem[]`	—	消息流（受控，追加）
pinned	`LiveChatItem[]`	—	顶部置顶区（公告/规则）
autoScroll	`boolean`	`true`	自动滚到底；用户上滚时暂停并浮出「N 条新消息」恢复钮
maxItems	`number`	`200`	滚动窗保留上限（性能）
overlay	`boolean`	`false`	叠在深色视频上的浅色态（文字改白/半透白 + 文字阴影）
className	`string`	—	容器自定义类

Slots

插槽	类型	说明
renderItem	`(item: LiveChatItem) => ReactNode`	渲染函数：自定义单条消息渲染（逃生舱）

LiveChatItem：

{ id: string; type: "message"｜"enter"｜"gift"｜"follow"｜"system"; user?: LiveChatUser; text?: ReactNode; gift?: { name; icon?; combo? }; at?: string }

。
LiveChatUser：{ name: string; avatar?: string; level?: number; badge?: ReactNode }（level 渲染等级牌，badge 渲染房管/铁粉等身份徽标）。

禁忌 / 坑

自动贴底依赖「当前是否贴底」判定：用户上滚查看历史时 autoScroll 暂停，浮出「N 条新消息」钮，点它才恢复贴底——不要在外部强行 scrollTo 干扰。

items 须给容器固定高度（如 className="h-full" + 父容器定高），否则滚动区无法形成。

高频追加时靠 maxItems 截断窗口；不要把全量历史塞进 items。

LiveChat

用法

基础用法

置顶公告

视频叠加态

何时用

导入

Props

Slots

禁忌 / 坑

相关

LiveChat

用法

基础用法

置顶公告

视频叠加态

何时用

导入

Props

Slots

禁忌 / 坑

相关