#ChatLayout 聊天布局

ChatLayout 提供了一个标准的聊天界面布局，包含头部、可滚动的消息区域和底部的输入/操作区域。内置自动滚动到底部功能，并通过 ref 暴露滚动容器和滚动方法。

#代码演示

#API Playground

通过控制面板调试 header / footer / footerHeight / showFooterBackground / scrollBehavior / 命令式 ref（scrollToBottom / isAtBottom）/ onScrollStateChange 等核心 API。

#基础用法

最简单的用法：配置 header、children（消息列表）和 footer（输入区域），通过 ref 调用 scrollToBottom。

#header 配置详解

header 属性接受 LayoutHeaderConfig，支持标题、分享按钮、左右侧折叠按钮、受控/非受控模式及自定义扩展内容。

#footer 与背景渐变

footer 放置输入框等底部操作区，footerHeight 控制最小高度，showFooterBackground 开关底部渐变遮罩。

#滚动控制

通过 scrollBehavior 切换滚动动画，使用 ref 上的 scrollToBottom 方法或直接操作 scrollContainer DOM 元素实现精细滚动控制。

#classNames 与 styles 自定义样式

通过 classNames / styles 对根容器、内容区、滚动区、底部区等各区域进行精细的样式定制。

#滚动状态监听

通过 onScrollStateChange 监听滚动状态（isAtBottom / isPinned），实现"回到底部"浮动按钮等交互。用户上滑离开底部时显示按钮，点击后平滑滚动回底部。

#完整对话场景

模拟真实聊天场景：输入框 + 发送按钮 + 自动回复，展示 ChatLayout 与 BubbleList 配合使用的典型模式。

#无头部模式

不传 header 时，ChatLayout 仅包含内容区和底部区，适用于嵌入式面板、侧边栏等不需要顶部标题栏的场景。

#动态底部高度

footer 实际高度可随内容变化（如多行输入框），ChatLayout 自动检测并调整内容区底部留白，无需手动同步 footerHeight。

#空状态与新对话

对话列表为空时展示欢迎页和快捷提问，发送消息后切换为 BubbleList 列表，演示空状态到有内容状态的过渡。

#API

#ChatLayoutProps

#ChatLayoutRef

通过 ref 获取组件实例，用于控制滚动行为或访问底层 DOM。

#ChatLayoutScrollState

onScrollStateChange 回调接收的滚动状态对象。

import { useRef } from 'react';
import { ChatLayout, ChatLayoutRef } from '@ant-design/agentic-ui';

const chatRef = useRef<ChatLayoutRef>(null);

// 滚动到底部
chatRef.current?.scrollToBottom();

// 访问滚动容器 DOM
const el = chatRef.current?.scrollContainer;
console.log(el?.scrollTop, el?.scrollHeight);

#LayoutHeaderConfig（header 属性）

#特性

• 自动滚动：内置 useAutoScroll hook，新内容添加时自动滚动到底部，滚动容器内手动上划后停止跟随。
• 布局结构：标准 Header-Content-Footer 结构，内容区自适应高度并独立可滚动。
• 底部遮罩：showFooterBackground 开启时，底部渐变背景让内容和输入框之间的衔接更自然。
• Ref 控制：通过 ref.scrollToBottom() 精确触发滚动，或通过 ref.scrollContainer 直接操作 DOM。
• 语义样式：支持 classNames / styles 对内部各层级区域进行独立样式定制。