Webark IM Template

一个开箱即用的 React IM 前端模板。内置桌面三栏、移动端聊天、联系人、群资料、设置、帮助、Markdown 消息、表情、@ 提及和本地 demo 数据。

在线体验 · 为什么用 · 快速开始 · 如何套用 · 反馈建议

⚠️ 声明

本项目为独立开源 IM 前端模板，不隶属于任何第三方即时通讯平台。本项目仅供学习交流，请勿用于违法用途。

🖼️ 预览

❓ 为什么用

• 完整 IM 前端骨架：会话列表、聊天窗口、联系人、群聊详情、资料页和设置页。
• 同时适配桌面端和移动端，默认就是可体验的聊天界面。
• 纯前端 demo，无数据库，无自建后端，拉下来即可运行。
• 组件和状态边界清晰，方便接入自己的登录、API、上传、通知和机器人能力。
• 提供工具页、消息渲染、输入框按钮、资料操作和设置面板等轻量扩展入口。

🚀 快速开始

bun install
bun run dev

默认访问：

http://localhost:5173

生产构建：

bun run build
bun run preview

🧩 如何套用

从模板入口引入核心组件：

import {
	ChatShell,
	ChatSidebarContent,
	ChatMainContent,
	createMemoryChatDataSource,
	type ChatDataSource,
	useChatShellController,
} from "webark-im-template";
import "webark-im-template/styles.css";

你只需要实现或注入一个 ChatDataSource，模板负责 UI、列表、输入和常见 IM 交互。登录鉴权、服务端接口、文件上传、推送通知、机器人和业务路由都放在自己的应用层。

核心适配接口：

• loadConversations
• loadContacts
• loadMessages(conversationId, cursor)
• sendMessage
• retryMessage
• subscribe
• markAsRead

模板内置 createMemoryChatDataSource 作为 Mock Adapter，适合 demo、测试和最小接入示例；真实项目应替换为自己的 API adapter。

消息层已支持：

• 游标分页和加载更早消息
• 动态高度消息布局和历史加载后的滚动锚点保持
• 历史分页去重合并
• 乐观发送、pending / sent / failed
• clientMessageId 去重和服务端回执覆盖本地临时消息
• 失败重试入口

常用扩展函数：

• composeToolRegistry
• composeMessageRenderers
• composeComposerActionRegistry
• composeProfileActionRegistry
• composeConversationDetailActionRegistry
• composeSettingsPanelRegistry

最小业务接入示例见 examples/minimal。

📁 目录

src/
  App.tsx          demo app
  main.tsx         Vite entry
  styles.css       style entry
	styles/          CSS files
	template/        reusable IM components, data source, types, state, demo data
examples/minimal/   smallest business integration sample
e2e/                Playwright smoke tests
tests/              unit and component tests

🪪 License

MIT @Dogxi