使用者、好友與線上狀態

本頁講與“人”有關的功能：使用者資料（im.users）、好友和黑名單（im.friends）、線上狀態（im.presence）和本人的登入裝置（im.devices）。能做哪些操作由執行策略決定。

要做什麼	看哪裡
顯示、修改本人資料，顯示別人的暱稱頭像	本人和其他使用者資料
加好友、處理好友申請、改備註	好友和申請
拉黑、設定加好友方式	黑名單與加好友方式
顯示線上、離線	線上狀態
檢視和踢掉本人的其他裝置	登入裝置

本人和其他使用者資料

val me = im.users.refreshMe()
im.users.updateMe(nickname = "小明")
val profiles = im.users.fetch(listOf("bob"), force = true)
println(profiles["bob"]?.nickname)

• users.me 是本人資料的 StateFlow。
• get(username) 同步讀取快取中的資料，沒有時返回 null。
• fetch 返回使用者名稱到資料的 Map；快取沒過期的直接用快取，force = true 時一律向服務端查詢。
• updateMe 可以修改 nickname、avatarUrl、attributes，也支援 clearAttributes 和 version。attributes 中值為 null 的鍵被刪除，clearAttributes 清空全部屬性。
• 設定頭像時先以 USER_AVATAR 上傳，再把得到的 URL 寫進資料，見頭像與群檔案。
• myMute 是本人被禁言的資訊，只用於顯示；能否傳送以服務端的檢查為準。

好友和申請

im.friends.requests.send("bob", message = "你好，我是小明")
im.friends.requests.accept("bob", remark = "同事")
im.friends.update("bob", remark = "项目同事")

• friends.list() / listFlow() 提供好友列表；get 讀取本地的一位好友，check 批次檢查與別人的關係，remove 刪除好友。listInfo 是好友數和上限，見資料型別。
• requests.received() / sent() 分頁查詢收到和發出的申請；decline 拒絕，markRead 把收到的申請標為已讀，unreadCount 是未讀申請數的 StateFlow。
• send 的結果取決於對方的加好友方式：可能直接成為好友，也可能只是發出申請。請按返回值和最新的好友列表顯示。

黑名單與加好友方式

im.friends.blacklist.add("bob")
val blocked = im.friends.blacklist.has("bob")
im.friends.blacklist.remove("bob")

• blacklist.list() / listFlow() 訂閱黑名單。
• friends.settings.get() 查詢本人的加好友方式，set(mode) 修改；mode 為 null 時使用應用的預設值。
• 拉黑後對訊息和通話的影響由服務端的策略決定。

線上狀態

val subscription = im.presence.subscribe(listOf("bob"))
try {
    val known = im.presence.get("bob")
    val queried = im.presence.query(listOf("bob"))
    println(known)
    println(queried)
} finally {
    subscription.close()
}

• subscribe 持續關注這些人的線上狀態，頁面離開時關閉；狀態變化時發出 PresenceChanged 事件。
• get 讀取記憶體中已知的狀態，query 主動向服務端查詢一次。
• 查不到、訂閱失敗或沒有許可權時，不要一律顯示“離線”：區分“未知”“看不到”和真的離線。訂閱失敗會發出 PresenceSubscribeFailed。

登入裝置

• devices.online() 讀取本人當前線上的裝置，sessions() 查詢本人全部有效的登入，kick(sessionId) 讓指定的裝置下線。
• 本人的線上裝置變化時發出 DevicesChanged，在新裝置上登入時發出 DevicesNewLogin。
• 裝置數上限、同類平臺互相替換等規則見服務端的多端登入。

完整引數見使用者介面、好友介面、線上狀態介面。