ar-whiteboard-shapes

ArIM

ArIM 是 IM Web SDK 的命名空间，提供 create 方法、version 属性。

创建实例

使用 create 方法创建 IM 实例。

import { create, type CreateOptions } from 'ar-im';

const options: CreateOptions = {
  appID: 'YOUR_APPID',
  mimIdx: 'YOUR_INDEX',
};
const im = create(options);

IM 实例

通过 create 方法创建的 IM 实例 ArIMClient，拥有一下方法和事件回调。

登录/登出

API	说明
login	登录即时通信 (IM) 系统。
logout	登出即时通信 (IM) 系统。

消息

API	说明
createAudioMessage	创建音频消息。
createCustomMessage	创建自定义消息。
createFileMessage	创建文件消息。
createForwardMessage	创建转发消息。
createImageMessage	登创建图片消息。
createTextMessage	创建文字消息。
createVideoMessage	创建视频消息。
deleteMessage	删除本地消息。
sendMessage	发送(点对点或群组)消息。

会话

API	说明
createConversation	用于创建 C2C（单聊） 或群组会话（群聊）。
deleteConversation	删除本地会话。
getConversationInfo	获取会话信息。
getConversationList	获取会话列表。
getMessageList	获取会话的消息列表。
sendMessageReadReceipt	发送消息已读回执。
setConversationActive	设置会话活动状态。
setConversationNotDisturb	设置会话免打扰状态。
setConversationPinned	设置会话置顶状态。
updateConversation	更新会话的信息。
updateConversationProfile	更新会话的资源。

呼叫

API	说明
acceptCall	同意远端呼叫邀请。
endCall	结束/挂断呼叫。
getCallState	获取当前呼叫状态。
joinCall	主动加入呼叫。
makeCall	发起呼叫。
rejectCall	拒绝远端呼叫邀请。

事件

事件名称枚举可见ArIMClientEventsName。 事件列表枚举可见ArIMClientEvents。

事件名称	API	说明
ArIMClientEventsName.CALL_ENDED	OnEndCall	呼叫结束通知。
ArIMClientEventsName.CALL_MEMBER_JOIN	OnCallMemberJoin	呼叫成员加入通知。
ArIMClientEventsName.CALL_MEMBER_LEAVE	OnCallMemberLeave	呼叫成员离开通知。
ArIMClientEventsName.CALL_MEMBER_STATE	OnCallMemberState	呼叫成员状态通知。
ArIMClientEventsName.CALL_RECEIVED	OnCallMemberLeave	呼叫成员加入通知。
ArIMClientEventsName.CONNECTION_STATUS	OnConnectionStatus	网络状态变化通知。
ArIMClientEventsName.CONVERSATION_CALL_BEGINNING	OnConversationCallBeginning	群呼进行中的通知。
ArIMClientEventsName.CONVERSATION_CALL_ENDED	OnConversationCallEnded	群呼结束通知。
ArIMClientEventsName.CONVERSATION_CREATED	OnConversationCreated	新会话通知。
ArIMClientEventsName.CONVERSATION_DELETED	OnConversationDeleted	会话被删除通知。
ArIMClientEventsName.CONVERSATION_INFO_UPDATED	OnConversationInfoUpdated	会话信息变更通知。
ArIMClientEventsName.JOIN_CALL_RESULT	OnJoinCallResult	加入呼叫结果的通知。
ArIMClientEventsName.KICKED_OUT	OnCallMemberLeave	呼叫成员加入通知。
ArIMClientEventsName.MESSAGE_RECEIVED	OnMessageReceived	新消息通知。
ArIMClientEventsName.MESSAGE_STATUS	OnMessageStatus	发送的消息状态通知。
ArIMClientEventsName.NEW_REPORT_EVENT	OnNewReportEvent	新事件通知。

Usage

1. 创建客户端实例

import { create, type CreateOptions } from 'ar-im';

const options: CreateOptions = {
  appID: 'YOUR_APPID',
  mimIdx: 'YOUR_INDEX',
};
const im = create(options);

2. 监听事件

监听事件，应当在创建实例之后保证全局只监听一次，否则当事件广播触发后，就会广播多次（即监听次数），如果只需要监听一次，可以使用 once, 具体参考EventEmitter。

import {
  Message,
  TextMessage,
  ArIMClientEventsName,
  ConnectionStatus,
  DisconnectReason
} from 'ar-im';

const onNewMessage = (message: Message) => {
  if (message instanceOf TextMessage) {
    const { text } = message.payload;
    console.log('收到新的文字消息:', text);
  }
  // TODO
};
const onConnectionStatus = (currentState: ConnectionStatus, prevState: ConnectionStatus, reason?: DisconnectReason | string) => {
  // TODO
};

// 监听新消息通知
im.on(ArIMClientEventsName.MESSAGE_RECEIVED, onNewMessage);
// 监听连接状态变化
im.on(ArIMClientEventsName.CONNECTION_STATUS, onConnectionStatus);

3. 发送文字消息

import {
  createTextMessage,
} from 'ar-im';

const textMessage = createTextMessage({
  to: conversationId.value,
  conversationType,
  payload: {
    text: content.text!
  }
});
// 发送
im.sendMessage(message);

4. 发起呼叫

import {
  createTextMessage,
} from 'ar-im';

// 被呼叫的用户 ID
const userIds = ['123', '456'];
// 发送
im.makeCall(
  userIds,
  // 自定呼叫数据
  JSON.stringify({
    mediaType: 'audio', // audio or video
  }),
  {
    // 可选参数，呼叫等待时长（秒）
    wait: 60,
    // 可选参数，自定呼叫 ID
    // callId,
    // 可选参数，自定群组 ID
    // groupId
  }
);

完整 Demo

import {
  create,
  type CreateOptions,
  Message,
  TextMessage,
  createTextMessage,
  ArIMClientEventsName,
  ConnectionStatus,
  DisconnectReason,
  CallProfile
} from 'ar-im';

let im: ArIMClient || null = null;

const onNewMessage = (message: Message) => {
  if (message instanceOf TextMessage) {
    const { text } = message.payload;
    console.log('收到新的文字消息:', text);
  }
  // TODO
};
const onConnectionStatus = (currentState: ConnectionStatus, prevState: ConnectionStatus, reason?: DisconnectReason | string) => {
  // TODO
};
const onCallInvite = (callProfile: CallProfile) => {
  // TODO
};
const init = async (userId: string) => {
  const options: CreateOptions = {
    appID: 'YOUR_APPID',
    mimIdx: 'YOUR_INDEX',
  };
  im = create(options);
  // 监听新消息通知
  im.on(ArIMClientEventsName.MESSAGE_RECEIVED, onNewMessage);
  // 监听连接状态变化
  im.on(ArIMClientEventsName.CONNECTION_STATUS, onConnectionStatus);
  // 监听呼叫邀请
  im.on(ArIMClientEventsName.CALL_RECEIVED, onCallInvite);

  await im.login({
    userID: userId,
    userName: '',
    userAvatar: ''
  });
};

const destroy = () => {
  im.logout();
  // 取消监听新消息通知
  im.off(ArIMClientEventsName.MESSAGE_RECEIVED, onNewMessage); // 保证 this 指向，否则无法取消监听
  // 取消监听连接状态变化
  im.off(ArIMClientEventsName.CONNECTION_STATUS, onConnectionStatus);
  // 取消监听呼叫邀请
  im.off(ArIMClientEventsName.CALL_RECEIVED, onCallInvite);
  im = null;
}