Messenger Ball

一个用于创建智能客服聊天球的 React 组件库，提供悬浮式聊天界面功能。

安装

npm install dingtalk-aics-messenger-ball
# 或者
yarn add dingtalk-aics-messenger-ball
# 或者
pnpm add dingtalk-aics-messenger-ball

快速开始

基础用法

import { init } from "dingtalk-aics-messenger-ball";

// 初始化聊天球
const messengerBall = init({
    appCode: "your-app-code",
    user: {
        id: "user123",
        name: "张三",
        email: "[email protected]",
    },
});

// 销毁实例
messengerBall.destroy();

使用全局控制方法

import { boot, show, hide, shutdown } from "dingtalk-aics-messenger-ball";

// 启动聊天球
boot({
    appCode: "your-app-code",
    user: {
        id: "user123",
        name: "张三",
    },
});

// 显示聊天球
show();

// 隐藏聊天球
hide();

// 完全关闭聊天球
shutdown();

API 参考

init(config)

初始化聊天球，返回包含 destroy 方法的对象。

function init(config: MessengerBallOpenConfig): {
    destroy: () => void;
};

boot(config?)

使用新的配置重新加载悬浮球。

function boot(config?: MessengerBallOpenConfig): void;

show()

展示悬浮球。

function show(): void;

hide()

隐藏悬浮球。

function hide(): void;

shutdown()

注销用户信息并销毁悬浮球。

function shutdown(): void;

配置选项

MessengerBallOpenConfig

聊天球的配置接口：

interface MessengerBallOpenConfig {
    appCode?: string; // 应用代码
    user?: {
        // 用户信息
        id?: string; // 用户ID
        name?: string; // 用户姓名
        email?: string; // 用户邮箱
        avatar?: string; // 用户头像URL
    };
    company?: {
        // 公司信息
        id?: string; // 公司ID
        name?: string; // 公司名称
    };
    extension?: Record<string, string>; // 扩展字段
}

使用示例

基础聊天球

import { init } from "dingtalk-aics-messenger-ball";

const chat = init({
    appCode: "my-app",
    user: {
        id: "12345",
        name: "李四",
        email: "[email protected]",
    },
});

// 使用完毕后销毁
chat.destroy();

企业用户聊天

import { init } from "dingtalk-aics-messenger-ball";

const chat = init({
    appCode: "enterprise-app",
    user: {
        id: "emp001",
        name: "王五",
        email: "[email protected]",
        avatar: "https://example.com/avatar.jpg",
    },
    company: {
        id: "comp123",
        name: "某某科技有限公司",
    },
    extension: {
        department: "技术部",
        role: "工程师",
    },
});

动态控制聊天球

import { boot, show, hide, shutdown } from "dingtalk-aics-messenger-ball";

// 启动聊天球
boot({
    appCode: "support-app",
    user: {
        id: "user789",
        name: "赵六",
    },
});

// 显示聊天球
show();

// 稍后隐藏
setTimeout(() => {
    hide();
}, 5000);

// 完全关闭
setTimeout(() => {
    shutdown();
}, 10000);

重新配置聊天球

import { boot } from "dingtalk-aics-messenger-ball";

// 初始配置
boot({
    appCode: "app1",
    user: { id: "user1", name: "用户1" },
});

// 使用新配置重新加载
boot({
    appCode: "app2",
    user: { id: "user2", name: "用户2" },
    company: { id: "comp1", name: "新公司" },
});

浏览器支持

• Chrome >= 88
• Firefox >= 85
• Safari >= 14
• Edge >= 88

依赖要求

此包需要以下 peer dependencies：

• react >= 16.8.0
• react-dom >= 16.8.0

TypeScript 支持

本包包含完整的 TypeScript 类型定义，无需额外安装 @types 包。