本文档详细介绍了云信Web SDK的API用法，包括静态方法`staticChatroom.getInstance()`，该方法提供单例模式，确保多次调用始终返回同一实例。API还涉及连接管理、重连机制、事件监听、消息处理、聊天室成员管理、文件操作等核心功能。开发者可以通过这些API实现聊天室的创建、连接、管理及消息交互等功能。
staticChatroom.getInstance(options)
此接口为单例模式, 对于同一个账号, 永远返回同一份实例, 即只有第一次调用会初始化一个实例
后续调用此接口会直接返回初始化过的实例, 同时也会调用接口setOptions更新传入的配置
后续调用此接口时, 如果连接已断开, 会自动建立连接
当发生掉线时，SDK会自动进行重连
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
appKey
String
在云信管理后台查看应用的 appKey
account
String
帐号, 应用内唯一
token
String
帐号的 token, 用于建立连接
chatroomId
String
聊天室 id
chatroomAddresses
Array.
聊天室地址列表
onconnect
function
optional
连接建立后的回调, 会传入聊天室信息
onwillreconnect
function
optional
即将重连的回调
此时说明 SDK 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接
此回调会收到一个对象, 包含额外的信息, 有以下字段duration: 距离下次重连的时间
retryCount: 重连尝试的次数
ondisconnect
function
optional
断开连接后的回调
此时说明 SDK 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面
此回调会收到一个对象, 包含错误的信息, 有以下字段code: 出错时的错误码, 可能为空302: 账号或者密码错误
'kicked': 被踢
当code为'kicked'的时候, 此对象会有以下字段reason: 被踢的原因chatroomClosed: 聊天室关闭了
managerKick: 被管理员踢出
samePlatformKick: 不允许同一个帐号重复登录同一个聊天室
message: 文字描述的被踢的原因
onerror
function
optional
发生错误的回调, 会传入错误对象
onmsgs
function
optional
收到消息的回调, 会传入消息数组
Example:
var chatroom = new Chatroom({
appKey: 'appKey',
account: 'account',
token: 'token',
chatroomId: 'chatroomId',
chatroomAddresses: [
'address1',
'address2'
],
onconnect: onChatroomConnect,
onerror: onChatroomError,
onwillreconnect: onChatroomWillReconnect,
ondisconnect: onChatroomDisconnect,
// 消息
onmsgs: onChatroomMsgs
});
function onChatroomConnect(chatroomInfo) {
console.log('进入聊天室', chatroomInfo);
}
function onChatroomWillReconnect(obj) {
// 此时说明 SDK 已经断开连接, 请开发者在界面上提示用户连接已断开, 而且正在重新建立连接
console.log('即将重连', obj);
}
function onChatroomDisconnect(error) {
// 此时说明 SDK 处于断开状态, 开发者此时应该根据错误码提示相应的错误信息, 并且跳转到登录页面
console.log('连接断开', error);
if (error) {
switch (error.code) {
// 账号或者密码错误, 请跳转到登录页面并提示错误
case 302:
break;
// 被踢, 请提示错误后跳转到登录页面
case 'kicked':
break;
default:
break;
}
}
}
function onChatroomError(error, obj) {
console.log('发生错误', error, obj);
}
function onChatroomMsgs(msgs) {
console.log('收到聊天室消息', msgs);
}
audioToMp3(options){String}
将音频 url 转为 mp3
此方法会返回一个新的 url
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
url
String
url
Returns:
Type
Description
String
转为 mp3 后的 url
Example:
var url = 'http://b12026.nos.netease.com/MTAxMTAxMA==/bmltYV8xMTQwMzFfMTQ1MTg4ODk5MjMxMV9mNmI1Y2QyZC03N2UzLTQxNmUtYWY5NC1iODlhZGY4ZTYzYWQ=';
var mp3Url = chatroom.audioToMp3({
url: url
});
console.log(mp3Url);
connect(){Void}
进入聊天室
Returns:
Type
Description
Void
Example:
chatroom.connect();See:
disconnect(){Void}
退出聊天室
Returns:
Type
Description
Void
Example:
chatroom.disconnect();See:
getChatroom(options){Void}
获取当前聊天室的信息
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
done
function
结果回调函数, 成功时会额外附上聊天室信息
Returns:
Type
Description
Void
Example:
chatroom.getChatroom({
done: getChatroomDone
});
function getChatroomDone(error, obj) {
console.log('获取当前聊天室的信息' + (!error?'成功':'失败'), error, obj);
}
getChatroomMembers(options){Void}
获取聊天室成员列表
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Default
Description
guest
Boolean
true表示获取游客, false表示获取非游客成员
游客列表按照游客进入聊天室的时间倒序排列
非游客(即固定成员)列表按照成为固定成员的时间倒序排列
onlyOnline
Boolean
false
optional
当设置guest=false来获取非游客成员时, 默认会获取所有的固定成员, 包括不在线的, 可以设置onlyOnline=true来只获取在线的固定成员
time
Number
0
optional
分页用, 查找该时间戳之前的成员
默认 0 代表当前服务器时间
获取游客时, 此字段填上次获取的最后一个游客的enterTime
获取非游客时, 此字段填上次获取的最后一个非游客的updateTime
limit
Number
100
optional
分页用, 默认 100
done
结果回调函数, 成功时会额外附上聊天室成员信息列表
Returns:
Type
Description
Void
Example:
chatroom.getChatroomMembers({
guest: false,
limit: 100,
done: getChatroomMembersDone
});
function getChatroomMembersDone(error, obj) {
console.log('获取聊天室成员' + (!error?'成功':'失败'), error, obj.members);
}
getChatroomMembersInfo(options){Void}
获取聊天室成员信息
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
accounts
Array.
待查询的账号列表
done
function
结果回调函数, 成功时会额外附上聊天室成员信息列表
Returns:
Type
Description
Void
Example:
chatroom.getChatroomMembersInfo({
accounts: ['account1', 'account2'],
done: getChatroomMembersInfoDone
});
function getChatroomMembersInfo(erorr, obj) {
console.log('获取聊天室成员信息' + (!error?'成功':'失败'), error, obj);
}
getHistoryMsgs(options){Void}
获取聊天室历史消息
获取从 timetag 对应的时间点往前的若干条数据
不填 timetag 的话默认为服务器当前时间
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Default
Description
timetag
Number
optional
时间戳
limit
Number
100
optional
limit, 默认 100
Returns:
Type
Description
Void
Example:
chatroom.getHistoryMsgs({
timetag: 1451393192478,
limit: 100,
done: getHistoryMsgsDone
});
function getHistoryMsgsDone(error, obj) {
console.log('获取聊天室历史' + (!error?'成功':'失败'), error, obj.msgs);
}
kickChatroomMember(options){Void}
踢聊天室成员
当有人被踢出聊天室时, 所有其他聊天室成员会收到类型为'kickMember'的聊天室通知消息。
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
account
String
待踢的账号
custom
String
optional
扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段, 被踢的人收到的ondisconnect回调接收的参数的custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
done
function
结果回调函数
Returns:
Type
Description
Void
Example:
chatroom.kickChatroomMember({
account: 'account',
done: kickChatroomMemberDone
});
function kickChatroomMember(error, obj) {
console.log('踢人' + (!error?'成功':'失败'), error, obj);
}
markChatroomBlacklist(options){Void}
设置聊天室黑名单
被加入黑名单的人将不能进入此聊天室
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
account
String
待设置的账号
isAdd
Boolean
true表示添加, false表示移除
custom
String
optional
扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
done
function
结果回调函数, 成功时会额外附上聊天室成员信息
Returns:
Type
Description
Void
Example:
chatroom.markChatroomBlacklist({
account: 'account',
isAdd: true,
done: markChatroomBlacklistDone
});
function markChatroomBlacklistDone(error, obj) {
console.log('添加聊天室黑名单' + (!error?'成功':'失败'), error, obj.member);
}
markChatroomCommonMember(options){Void}
设置聊天室普通成员
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Default
Description
account
String
待设置的账号
isAdd
Boolean
是否加为普通成员
level
Number
0
optional
等级
custom
String
optional
扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
done
function
结果回调函数
Returns:
Type
Description
Void
Example:
chatroom.markChatroomCommonMember({
account: 'account',
level: 0,
done: markChatroomCommonMemberDone
});
function markChatroomCommonMemberDone(error) {
console.log('设置聊天室普通成员' + (!error?'成功':'失败'), error);
}
markChatroomGaglist(options){Void}
设置聊天室禁言名单
被加入禁言名单的人将不能在该聊天室发送消息
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
account
String
待设置的账号
isAdd
Boolean
true表示添加, false表示移除
custom
String
optional
扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
done
function
结果回调函数, 成功时会额外附上聊天室成员信息
Returns:
Type
Description
Void
Example:
chatroom.markChatroomGaglist({
account: 'account',
isAdd: true,
done: markChatroomGaglistDone
});
function markChatroomGaglistDone(error, obj) {
console.log('添加聊天室禁言名单' + (!error?'成功':'失败'), error, obj.member);
}
markChatroomManager(options){Void}
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
account
String
待设置的账号
isAdd
Boolean
true表示添加, false表示移除
custom
String
optional
扩展字段, 如果填了, 那么其它聊天室成员收到的聊天室通知消息的attach.custom的值为此字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
done
function
结果回调函数, 成功时会额外附上聊天室成员信息
Returns:
Type
Description
Void
Example:
chatroom.markChatroomManager({
account: 'account',
isAdd: true,
done: markChatroomManagerDone
});
function markChatroomManagerDone(error, obj) {
console.log('添加聊天室管理员' + (!error?'成功':'失败'), error, obj.member);
}
packFileDownloadName(options){String}
修改图片下载的名字
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
url
String
原图 url
name
String
下载的名字
Returns:
Type
Description
String
修改图片下载名字后的图片 url
Example:
var url = 'http://nim.nos.netease.com/MTAxMTAwMg==/bmltYV8xNDc5OTNfMTQ0MzE0NTgyNDI0M184YjFkYTMwMS02NjcxLTRiYjktYTUwZC04ZTVlZjZlNzZjMzA=';
var nameUrl = chatroom.packFileDownloadName({
url: url,
name: '测试.jpg'
});
console.log(nameUrl);
previewFile(options){Void}
预览文件
开发者可以预览文件, 支持以下几种场景通过参数fileInput传入文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
通过参数blob传入 Blob 对象
通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL
SDK会将文件上传到文件服务器, 然后将拿到的文件对象在done回调中传给开发者, 文件对象有以下几种
开发者在拿到文件对象之后, 可以调用发送文件消息来发送文件消息。
文件大小限制为最大 100M高级浏览器会在上传前就检测文件大小
IE8/IE9 会在上传完成后检测文件大小
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
type
String
optional
文件过滤器
image会过滤掉非图片的文件, audio过滤掉非音频, video会过滤掉非视频的文件
IE8/IE9 不支持文件过滤
fileInput
String
|
Node
optional
文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
blob
Blob
optional
Blob 对象
dataURL
String
optional
包含 MIME type 和 base64 数据的 data URL
uploadprogress
optional
上传进度, ie9以下不支持上传进度
done
结果回调函数, 成功时会收到文件对象, 请参考
Returns:
Type
Description
Void
Example:
chatroom.previewFile({
type: 'image',
fileInput: fileInput,
uploadprogress: function(obj) {
console.log('文件总大小: ' + obj.total + 'bytes');
console.log('已经上传的大小: ' + obj.loaded + 'bytes');
console.log('上传进度: ' + obj.percentage);
console.log('上传进度文本: ' + obj.percentageText);
},
done: function(error, file) {
console.log('上传image' + (!error?'成功':'失败'));
// show file to the user
if (!error) {
var msg = chatroom.sendFile({
scene: 'p2p',
to: 'account',
file: file,
done: sendChatroomMsgDone
});
console.log('正在发送聊天室image消息, id=' + msg.idClient);
}
}
});See:
sendCustomMsg(options)
发送自定义消息
自定义消息是消息类型的一种
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
content
String
自定义消息的消息内容, 推荐使用JSON格式构建
resend
Boolean
optional
是否是重发
idClient
String
optional
如果是重发, 那么需要带上之前生成的idClient来标记这条消息
custom
String
optional
扩展字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
fromNick
String
optional
发送方的昵称
done
结果回调函数
Returns:
Type
Description
Example:
var value = Math.ceil(Math.random()*3);
var content = {
type: 1,
data: {
value: value
}
};
var msg = chatroom.sendCustomMsg({
content: JSON.stringify(content),
done: sendChatroomMsgDone
});
console.log('正在发送聊天室自定义消息, id=' + msg.idClient);See:
sendFile(options){Void|Message}
发送文件消息
文件消息是消息类型的一种
开发者可以直接发送文件消息支持以下几种场景通过参数fileInput传入文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
通过参数blob传入 Blob 对象
通过参数dataURL传入包含 MIME type 和 base64 数据的 data URL
SDK会先将文件上传到文件服务器, 然后把拿到的文件对象在uploaddone回调中传给用户, 然后将其拼装成文件消息发送出去。
开发者也可以先预览文件来获取文件对象, 然后调用此接口发送文件消息。通过参数file传入文件
直接发送文件消息的话会在beforesend回调里面传入SDK生成的idClient, 如果先预览文件再发送, 那么此接口会直接返回idClient
参数type指定了要发送的文件类型, 包括图片、音频、视频和普通文件, 对应的值分别为'image'、'audio'、'video'和'file', 不传默认为'file'。
图片、音频、视频和普通文件的区别在于具体的文件信息不一样, 具体字段请参考
文件大小限制为最大100M高级浏览器会在上传前就检测文件大小
IE8和IE9会在上传完成后检测文件大小
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Default
Description
type
String
optional
文件过滤器,
'image'会过滤掉非图片的文件, 'audio'过滤掉非音频, 'video'会过滤掉非视频的文件,
IE8/IE9 不支持文件过滤
fileInput
String
|
Node
optional
文件选择 dom 节点或者节点 ID, SDK 会读取该节点下的文件, 在上传完成前请不要操作该节点下的文件
blob
Blob
optional
Blob 对象
dataURL
String
optional
MIME type 和 base64 数据的 data URL
file
Array
optional
文件对象, 开发者可以通过预览文件拿到文件对象
resend
Boolean
false
optional
是否是重发
beginupload
function
optional
开始上传图片的回调
如果开发者传入 fileInput, 在此回调之前不能修改 fileInput
在此回调之后可以取消图片上传, 此回调会接收一个参数 upload, 调用 upload.abort(); 来取消文件上传
uploadprogress
optional
上传进度, IE9以下不支持上传进度
uploaddone
optional
上传完成回调
beforesend
optional
发送文件消息之前的回调函数
resend
Boolean
optional
是否是重发
idClient
String
optional
如果是重发, 那么需要带上之前生成的idClient来标记这条消息
custom
String
optional
扩展字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
fromNick
String
optional
发送方的昵称
done
结果回调函数
Returns:
Type
Description
Void
|
Message
如果提供了参数fileInput, 那么先上传文件到服务器再发送, 不会返回消息, 会在beforesend里面返回消息.
如果提供了参数file, 那么直接发送文件消息, 返回消息
Example:
chatroom.sendFile({
type: 'image',
fileInput: fileInput,
uploadprogress: function(obj) {
console.log('文件总大小: ' + obj.total + 'bytes');
console.log('已经上传的大小: ' + obj.loaded + 'bytes');
console.log('上传进度: ' + obj.percentage);
console.log('上传进度文本: ' + obj.percentageText);
},
uploaddone: function(error, file) {
console.log('上传' + (!error?'成功':'失败'), error, file);
},
beforesend: function(msg) {
console.log('正在发送聊天室image消息, id=' + msg.idClient);
},
done: sendChatroomMsgDone
});See:
sendGeo(options)
发送地理位置消息
地理位置消息是消息类型的一种, geo参数请参考地理位置对象
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
geo
Object
地理位置对象
Name
Type
Description
lng
Number
经度
lat
Number
纬度
title
String
地址描述
resend
Boolean
optional
是否是重发
idClient
String
optional
如果是重发, 那么需要带上之前生成的idClient来标记这条消息
custom
String
optional
扩展字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
Returns:
Type
Description
Example:
var msg = chatroom.sendGeo({
scene: 'p2p',
to: 'account',
geo: {
lng: '116.3833',
lat: '39.9167',
title: 'Beijing'
},
done: sendChatroomMsgDone
});
console.log('正在发送聊天室geo消息, id=' + msg.idClient);See:
sendText(options)
发送文本消息
文本消息是消息的一种, 请参考消息
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
text
String
文本消息内容
resend
Boolean
optional
是否是重发
idClient
String
optional
如果是重发, 那么需要带上之前生成的idClient来标记这条消息
custom
String
optional
扩展字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
done
结果回调函数
Returns:
Type
Description
Example:
var msg = chatroom.sendText({
text: 'hello',
done: sendChatroomMsgDone
});
console.log('正在发送聊天室text消息, id=' + msg.idClient);
function sendChatroomMsgDone(error, msg) {
console.log('发送聊天室' + msg.type + '消息' + (!error?'成功':'失败') + ', id=' + msg.idClient, error, msg);
}See:
sendTipMsg(options)
发送提醒消息
提醒消息是消息类型的一种
提醒消息用于会话内的状态提醒，如进入会话时出现的欢迎消息，或者会话命中敏感词后的提示消息等等.
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
tip
String
提醒内容
resend
Boolean
optional
是否是重发
idClient
String
optional
如果是重发, 那么需要带上之前生成的idClient来标记这条消息
custom
String
optional
扩展字段
推荐使用JSON格式构建, 非JSON格式的话, Web端会正常接收, 但是会被其它端丢弃
Returns:
Type
Description
Example:
var msg = chatroom.sendTipMsg({
scene: 'p2p',
to: 'account',
tip: 'tip content',
done: sendChatroomMsgDone
});
console.log('正在发送聊天室提醒消息, id=' + msg.idClient);See:
setOptions(options)
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
token
String
帐号的 token, 用于建立连接
Example:
// 更新 token 的例子
chatroom.setOptions({
token: 'newToken'
});
updateChatroomMemberTempMute(options){Void}
Params:
Name
Type
Description
options
Object
配置参数
Name
Type
Description
account
String
帐号
duration
Number
禁言时长，单位秒，传0表示解除禁言
needNotify
Boolean
是否需要下发对应的通知消息
custom
String
对应的通知消息的扩展字段
Returns:
Type
Description
Void
Example:
chatroom.updateChatroomMemberTempMute({
account: 'account',
duration: 60,
needNotify: true,
custom: 'biu',
done: updateChatroomMemberTempMuteDone
})
function updateChatroomMemberTempMuteDone(error, obj) {
console.log('设置聊天室临时禁言' + (!error?'成功':'失败'), error, obj);
}
扫一扫
523
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
