tencent cloud

文档反馈

Android&iOS&Windows&Mac

最后更新时间:2024-07-05 18:00:23

    功能描述

    会话置顶指的是把单聊或群聊会话固定在会话列表的最顶部,滑动会话列表时一直保持在顶部,方便用户查找。置顶状态会存储在服务器,切换终端设备后,置顶状态会同步到新设备上。
    说明
    1. 置顶会话功能仅增强版 SDK 5.3.425 及以上版本支持。
    2. 置顶会话数上限 50,不支持增加。

    效果展示

    您可以使用本功能,实现如下图所示的会话置顶效果,其中灰色背景的两个群聊是被置顶的群聊会话:
    

    接口说明

    置顶会话

    您可以调用 pinConversation(Android / iOS & Mac / Windows) 接口,设置是否置顶会话。
    调用 getConversationList 获取会话列表时,该接口返回的会话列表中,置顶的会话在前,未置顶的会话在后。您可以通过 V2TIMConversation 对象的 isPinned 字段,检查会话有没有置顶。
    会话的顺序,按V2TIMConversation 对象的 orderKey 字段排序。orderKey 字段是整型数,当发送新消息、接收新消息、设置草稿或置顶会话时,会话被激活,orderKey 字段会增大。
    会话被置顶后,置顶会话始终排在未置顶会话的前面。如果同时置顶多个会话,这几个会话之间的相对顺序仍然会保持。 例如,有 5 个依次排序的会话 1、2、3、4、5,同时置顶会话 2 和 3,置顶后的顺序是 2、3、1、4、5,显然,会话 2 和 3 排在最前面,并且会话 2 仍然排在 3 的前面。
    示例代码如下:
    Android
    iOS & Mac
    Windows
    // isPinned 参数为 true,表示置顶会话,否则,表示取消置顶。
    String conversationID = "conversationID";
    V2TIMManager.getConversationManager().pinConversation(conversationID, true, new V2TIMCallback() {
    @Override
    public void onSuccess() {
    Log.i("imsdk", "success");
    }
    
    @Override
    public void onError(int code, String desc) {
    Log.i("imsdk", "failure, code:" + code + ", desc:" + desc);
    }
    });
    // isPinned 参数为 YES,表示置顶会话,否则,表示取消置顶。
    NSString *conversationID = @"conversationID";
    [[V2TIMManager sharedInstance] pinConversation:conversationID isPinned:YES succ:^{
    NSLog(@"success");
    } fail:^(int code, NSString *desc) {
    NSLog(@"failure, code:%d, desc:%@", code, desc);
    }];
    class Callback final : public V2TIMCallback {
    public:
    using SuccessCallback = std::function<void()>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;
    
    Callback() = default;
    ~Callback() override = default;
    
    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
    success_callback_ = std::move(success_callback);
    error_callback_ = std::move(error_callback);
    }
    
    void OnSuccess() override {
    if (success_callback_) {
    success_callback_();
    }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
    if (error_callback_) {
    error_callback_(error_code, error_message);
    }
    }
    
    private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
    };
    
    V2TIMString conversationID = u8"conversationID";
    bool isPinned = true;
    
    auto callback = new Callback;
    callback->SetCallback(
    [=]() {
    // 置顶会话成功
    delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
    // 置顶会话失败
    delete callback;
    });
    
    V2TIMManager::GetInstance()->GetConversationManager()->PinConversation(conversationID, isPinned, callback);

    会话置顶变更通知

    如果您事先调用了 addConversationListener(Android / iOS & Mac / Windows) 添加会话监听器,就可以在 onConversationChanged 中获取到 V2TIMConversation 对象的 isPinned 字段值。根据这个字段可以判断会话的置顶状态是否变化。
    示例代码如下:
    Android
    iOS & Mac
    Windows
    public void onConversationChanged(List<V2TIMConversation> conversationList) {
    // 收到会话信息变更通知
    Log.i("imsdk", "onConversationChanged");
    }
    - (void)onConversationChanged:(NSArray<V2TIMConversation*> *) conversationList {
    for (V2TIMConversation *conv in conversationList) {
    if ([conv.conversationID isEqualToString:self.conversationData.conversationID]) {
    // conv.isPinned 为会话置顶状态
    }
    }
    }
    class ConversationListener final : public V2TIMConversationListener {
    public:
    void OnConversationChanged(const V2TIMConversationVector& conversationList) override {
    // 收到会话信息变更通知
    }
    // 其他成员 ...
    };
    
    // 添加会话事件监听器,注意在移除监听器之前需要保持 conversationListener 的生命期,以免接收不到事件回调
    ConversationListener conversationListener;
    V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持