用户资料 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

用户资料

更新时间： 2025/07/02 10:00:13

网易云信即时通讯 SDK（NetEase IM SDK，简称 NIM SDK）提供用户信息的托管，实现用户资料的统一管理和共享。

本文介绍了如何使用 NIM SDK 管理用户资料。您将了解如何更新、获取和搜索用户信息，以及如何监听用户资料变更事件。

支持平台

本文内容适用的开发平台或框架如下表所示，涉及的接口请参考下文相关接口章节：

安卓	iOS	macOS/Windows	Web/uni-app/小程序	Node.js/Electron	鸿蒙	Flutter
✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️️️️	✔️️️

技术原理

NIM SDK 提供了完整的用户资料管理功能，包括：

更新自身用户资料
获取指定用户资料
根据关键信息搜索用户资料
监听用户资料变更事件

用户资料包括用户昵称、性别、头像、签名、手机、邮箱、生日等信息。SDK 会将用户资料缓存到本地，但是除自身的资料外，SDK 不保证其他用户资料的实时更新。以下事件会触发其他用户资料的更新：

登录时会同步好友的用户资料（注册数据同步 addLoginDetailListener.onDataSync 回调，完成会发出通知）。
收到其他用户发来消息时，如果消息发送者的用户资料有更新，则 SDK 会同步更新对方的用户资料。
直接调用 SDK 接口从服务器拉取最新的用户资料，具体请参考本文的云端获取用户信息。

如果既不是好友，也未收到该用户发送的消息，则 SDK 不会实时更新对方的用户资料。
如果需要同步的用户资料较多，SDK 的同步时间可能会较长。

graph LR
    A[登录] --> B[同步好友的用户资料]
    B --> C{是否需要更新其他用户资料?}
    C -->|是| D[收到消息时更新发送者资料]
    C -->|是| E[主动调用 API 获取最新资料]
    C -->|否| F[使用本地缓存资料]

前提条件

在使用用户资料管理功能之前，请确保您已完成以下步骤:

已实现登录 IM。
了解 NIM SDK 中用户资料管理功能的原理。

监听用户相关事件

在进行用户相关操作前，您可以提前注册相关事件。注册成功后，当用户相关事件发生时，SDK 会触发对应回调通知。

注册监听

用户相关回调：

onUserProfileChanged：用户资料变更回调，返回变更的用户资料列表。

示例代码：

安卓

调用 addUserListener 方法注册监听：

JavaNIMClient.getService(V2NIMUserService.class).addUserListener(new V2NIMUserListener() {
    @Override
    public void onUserProfileChanged(List<V2NIMUser> users) {
        // 处理用户资料变更
    }
});

iOS

调用 addUserListener 方法注册监听：

Objective-C[[[NIMSDK sharedSDK] V2NIMUserService] addUserListener:self];

- (void)onUserProfileChanged:(NSArray<V2NIMUser *> *)users {
    // 处理用户资料变更
}

macOS/Windows

调用 addUserListener 方法注册监听：

C++V2NIMUserListener listener;
listener.onUserProfileChanged = [](std::vector<V2NIMUser> users) {
    // user profile changed
};
listener.onBlockListAdded = [](V2NIMUser user) {
    // user added to blocklist
};
listener.onBlockListRemoved = [](std::string accountId) {
    // user removed from blocklist
};
userService.addUserListener(listener);

Web/uni-app/小程序

调用 on("EventName") 方法注册监听：

TypeScriptnim.V2NIMUserService.on("onUserProfileChanged", function (users: V2NIMUser[]) {})

Node.js/Electron

调用 on("EventName") 方法注册监听：

TypeScriptv2.userService.on("userProfileChanged", function (users: V2NIMUser[]) {})

鸿蒙

调用 on("EventName") 方法注册监听：

TypeScriptnim.userService.on("onUserProfileChanged", function (users: V2NIMUser[]) {})

Flutter

调用 listen 方法注册监听：

Dartsubsriptions.add(NimCore.instance.userService.onUserProfileChanged.listen((e) {
      //do somethin

移除监听

安卓

如需移除用户相关监听器，可调用 removeUserListener 方法。

JavaNIMClient.getService(V2NIMUserService.class).removeUserListener(listener);

iOS

如需移除用户相关监听器，可调用 removeUserListener 方法。

Objective-C[[[NIMSDK sharedSDK] V2NIMUserService] removeUserListener:self];

macOS/Windows

如需移除用户相关监听器，可调用 removeUserListener 方法。

C++V2NIMUserListener listener;
// ...
userService.addUserListener(listener);
// ...
userService.removeUserListener(listener);

Web/uni-app/小程序

如需移除用户相关监听器，可调用 off("EventName") 方法。

TypeScriptnim.V2NIMUserService.off("onUserProfileChanged", function (users: V2NIMUser[]) {})

Node.js/Electron

如需移除用户相关监听器，可调用 off("EventName") 方法。

TypeScriptv2.userService.off("userProfileChanged", function (users: V2NIMUser[]) {})

鸿蒙

如需移除用户相关监听器，可调用 off("EventName") 方法。

TypeScriptnim.userService.off("onUserProfileChanged", function (users: V2NIMUser[]) {})

Flutter

如需移除用户相关监听器，可调用 cancel 方法。

Dartsubsriptions.forEach((subsription) {
    subsription.cancel();
  });

更新本人用户资料

调用 updateSelfUserProfile 方法更新自身的用户资料。

可可更新的字段包括：

name：用户昵称
avatar：头像 URL
gender：性别
birthday：生日
mobile：手机号
email：邮箱
sign：个性签名
serverExtension：服务器扩展字段

更新用户资料成功后，SDK 会返回用户资料变更回调 onUserProfileChanged，并同步缓存到本地。

示例代码：

安卓

JavaV2NIMUserUpdateParams updateParams = V2NIMUserUpdateParams.V2NIMUserUpdateParamsBuilder.builder()
    .withAvatar(avatar)
    .withBirthday(birthday)
    .withEmail(email)
    .withGender(gender)
    .withMobile(mobile)
    .withName(name)
    .withServerExtension(serverExtension)
    .withSign(sign)
    .build();

NIMClient.getService(V2NIMUserService.class).updateSelfUserProfile(updateParams,
new V2NIMSuccessCallback<List<Void>>() {
    @Override
    public void onSuccess(List<Void> voids) {
        // 处理成功回调
    }
},
new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        // 处理失败回调
    }
});

iOS

Objective-C[[[NIMSDK sharedSDK] V2NIMUserService] updateSelfUserProfile:userService success:^{
    //成功回调
} failure:^(V2NIMError * _Nonnull error) {
    //失败回调
}];

macOS/Windows

C++V2NIMUserUpdateParams updateParams;
updateParams.name = "name";
userService.updateSelfUserProfile(
    updateParams,
    []() {
        // update success
    },
    [](V2NIMError error) {
        // update failed, handle error
    });

Web/uni-app/小程序

TypeScriptnim.V2NIMUserService.updateSelfUserProfile({
    name: 'ab',
});

Node.js/Electron

TypeScriptawait v2.userService.updateSelfUserProfile(updateParams)
    name: 'ab',
});

鸿蒙

TypeScriptnim.userService.updateSelfUserProfile({
    name: 'ab'
})
    });

Flutter

Dartawait NimCore.instance.userService.updateSelfUserProfile(param)

获取用户资料

调用 getUserList 方法根据用户账号 ID 批量查询指定的用户资料列表。

该方法根据用户账号 ID 先从客户端本地获取用户资料数据，若本地数据缺失或不足，再查询服务端中的用户资料数据。

单次最多查询 150 个用户资料。
若传入的账号 ID 都不存在，则调用接口失败。若部分账号 ID 存在，则调用接口成功。调用结果只返回账号 ID 存在的用户资料，错误的账号 ID 不返回。

示例代码：

安卓

JavaNIMClient.getService(V2NIMUserService.class).getUserList(accountIds,
    new V2NIMSuccessCallback<List<V2NIMUser>>() {
        @Override
        public void onSuccess(List<V2NIMUser> v2NIMUsers) {
            // TODO: Implement onSuccess logic
        }
    },
    new V2NIMFailureCallback() {
        @Override
        public void onFailure(V2NIMError error) {
            // TODO: Implement onFailure logic
        }
    });

iOS

Objective-C[[[NIMSDK sharedSDK] V2NIMUserService] getUserList:@[@"accountId1",@"accountId2"] success:^(NSArray<V2NIMUser *> * _Nonnull result) {
    // 成功回调
} failure:^(V2NIMError * _Nonnull error) {
    // 失败回调
}];

macOS/Windows

C++nstd::vector<nstd::string> accountIds = {"test1", "test2"};
userService.getUserList(
    accountIds,
    [](nstd::vector<V2NIMUser> users) {
        for (auto&& user : users) {
            // do something
        }
    },
    [](V2NIMError error) {
        // get user list failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst userProfiles = await nim.V2NIMUserService.getUserList(['accid1', 'accid2'])

Node.js/Electron

TypeScriptconst users = await v2.userService.getUserList(accountIds)

鸿蒙

TypeScriptconst userProfiles = await nim.userService.getUserList(['accid1', 'accid2'])

Flutter

Dartawait NimCore.instance.userService.getUserList(accountIds)

根据关键字搜索用户信息

调用 searchUserByOption 方法根据关键字信息搜索用户的资料信息。

该方法默认搜索用户的昵称，若有需要，也可以指定同时搜索用户账号和手机号。

示例代码：

安卓

JavaV2NIMUserSearchOption option = V2NIMUserSearchOption.V2NIMUserSearchOptionBuilder.builder("搜索关键字")
//             按需配置
//            .withSearchAccountId()
//            .withSearchMobile()
//            .withSearchName()
            .build();
    NIMClient.getService(V2NIMUserService.class).searchUserByOption(option,
            new V2NIMSuccessCallback<List<V2NIMUser>>() {
                @Override
                public void onSuccess(List<V2NIMUser> v2NIMUsers) {

                }
            }, new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {

                }
            });

iOS

Objective-CV2NIMUserSearchOption *option = [V2NIMUserSearchOption optionWithKeyword:@"keyword"];
// 按需配置
option.searchName = YES;
option.searchAccountId = YES;
option.searchMobile = YES;
[NIMSDK.sharedSDK.V2NIMUserService searchUserByOption:option
                                        success:^(NSArray <V2NIMUser *> *result)
                                        {

                                        }
                                        failure:^(V2NIMError *error)
                                        {

                                        }];

macOS/Windows

C++V2NIMUserSearchOption option;
option.keyword = "test";
userService.searchUserByOption(
option,
[](nstd::vector<V2NIMUser> users) {
for (auto&& user : users) {
// do something
}
},
[](V2NIMError error) {
// search user failed, handle error
});

Web/uni-app/小程序

TypeScripttry {
    const users = await nim.V2NIMUserService.searchUserByOption({
        keyword: 'nick',
        searchName: true,
        searchAccountId: false,
        searchMobile: true
    })
} catch(err) {
    console.error('searchUserByOption Error:', err)
}

Node.js/Electron

TypeScripttry {
    const users = await v2.userService.searchUserByOption({
    keyword: 'Alice',
    searchName: true
})
} catch(err) {
    console.error('searchUserByOption Error:', err)
}

鸿蒙

TypeScripttry {
    const users = await nim.userService.searchUserByOption({
        keyword: 'nick',
        searchName: true,
        searchAccountId: false,
        searchMobile: true
    })
} catch(err) {
    console.error('searchUserByOption Error:', err)
}

Flutter

Dartawait NimCore.instance.userService.searchUserByOption(userSearchOption)

云端获取用户信息

调用 getUserListFromCloud 方法根据用户账号列表从服务器获取最新的用户信息。

查询用户信息一般建议使用 getUserList 接口，只有需要强制拉取最新用户信息才需要调用 getUserListFromCloud 接口。
避免频繁调用云端接口，合理使用本地缓存。

示例代码：

安卓

JavaList<String> accountIds = new ArrayList<>();
accountIds.add("test01");
accountIds.add("test02");
NIMClient.getService(V2NIMUserService.class).getUserListFromCloud(accountIds, users -> {
    //Query successful
}, error -> {
    //Query failed
});

iOS

Objective-C[NIMSDK.sharedSDK.V2NIMUserService getUserListFromCloud:@[@"accounId1",@"accountId2"] success:^(NSArray<V2NIMUser *> * _Nonnull result) {
        // 成功回调
    } failure:^(V2NIMError * _Nonnull error) {
        // 失败回调
    }];

macOS/Windows

C++nstd::vector<nstd::string> accountIds = {"test1", "test2"};
userService.getUserListFromCloud(
    accountIds,
    [](nstd::vector<V2NIMUser> usersList) {
        for (auto&& user : usersList) {
            // do something
        }
    },
    [](V2NIMError error) {
        // get UserListFromCloud failed, handle error
    });

Web/uni-app/小程序

TypeScriptconst users = await nim.V2NIMUserService.getUserListFromCloud(["AccountID1", "AccountID2"])

Node.js/Electron

TypeScriptconst users = await v2.userService.getUserListFromCloud(accountIds)

鸿蒙

TypeScriptconst users = await nim.userService.getUserListFromCloud(["AccountID1", "AccountID2"])

Flutter

Dartawait NimCore.instance.userService.getUserListFromCloud(accountIds)

API	说明
`addUserListener`	注册用户资料相关监听器
`removeUserListener`	取消注册用户资料相关监听器
`updateSelfUserProfile`	更新自己的用户资料
`getUserList`	根据用户账号 ID 列表获取用户资料
`searchUserByOption`	根据关键字信息搜索用户信息
`getUserListFromCloud`	根据用户账号列表从服务器获取用户信息

API	说明
`on("EventName")`	注册用户资料相关监听器
`off("EventName")`	取消注册用户资料相关监听器
`updateSelfUserProfile`	更新自己的用户资料
`getUserList`	根据用户账号 ID 列表获取用户资料
`searchUserByOption`	根据关键字信息搜索用户信息
`getUserListFromCloud`	根据用户账号列表从服务器获取用户信息

API	说明
`listen`	注册用户资料相关监听器
`cancel`	取消注册用户资料相关监听器
`updateSelfUserProfile`	更新自己的用户资料
`getUserList`	根据用户账号 ID 列表获取用户资料
`searchUserByOption`	根据关键字信息搜索用户信息
`getUserListFromCloud`	根据用户账号列表从服务器获取用户信息

常见问题

Q: 为什么有时获取不到其他用户的最新资料？

A: SDK 不保证实时更新其他用户的资料。如需最新资料，请使用 getUserListFromCloud 方法。

Q: 更新自己的资料后，其他用户何时能看到？

A: 其他用户需要主动刷新或收到您发送的消息才会更新您的资料。

Q: 搜索用户时，如何提高搜索效率？

A: 可以通过设置 V2NIMUserSearchOption 的参数来缩小搜索范围，如只搜索昵称或只搜索账号。

Q: 如何处理用户资料变更的通知？

A: 注册 onUserProfileChanged 监听器，在回调中更新 UI 或本地存储的用户信息。

Q: 单次最多可以获取多少个用户的资料？

A: 单次最多可以获取 150 个用户的资料。如需获取更多，请分批次调用。

此文档是否对你有帮助？

有帮助

去反馈

支持平台
技术原理
前提条件
监听用户相关事件
注册监听
移除监听
更新本人用户资料
获取用户资料
根据关键字搜索用户信息
云端获取用户信息
相关接口
常见问题