> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 好友列表

> 在 Unity 中构建 PlayFab 好友列表的快速入门教程，涵盖如何添加、删除和显示好友，以及链接 Steam、Facebook 和 XBOX 好友。

好友列表是提升玩家社交能力的绝佳功能。它易于使用，并可以让排行榜对用户更具吸引力。

## 先决条件

### SDK：Unity

* 在 `PlayFabSharedSettings` 对象中已设置游戏 ID。
* 项目能够成功登录用户。
* 游戏至少注册了两个用户。

## 关于好友

游戏中的任何玩家都可以与游戏中的任何其他玩家成为好友。值得注意的是，PlayFab 中的好友关系是单向的。

如果 **Albert** 将 **Bob** 添加为好友，则 **Bob** *不需要*任何批准流程。事实上，**Bob** 可能并不知情。

**Bob** 必须单独添加 **Albert**，好友关系才是*相互的*。如果您希望实施相互性规则，则由您的游戏负责通过自定义游戏服务器或 CloudScript 逻辑（如有必要）来强制执行这些条件。

如果玩家已关联其 Steam、Facebook 或 XBOX Live 账户，且这些好友也在玩您的游戏，则也可以显示这些平台特定的好友。

## 添加好友

示例代码使用函数 `DisplayFriends()` 和 `DisplayError(string error)` 来代替您应用的 UI。您可以将它们粘贴到编辑器中，即可无需额外操作即可运行 — 或者用您自己的代码替换这些调用。

```csharp theme={null}
void DisplayFriends(List<FriendInfo> friendsCache) { friendsCache.ForEach(f => Debug.Log(f.FriendPlayFabId)); }
void DisplayPlayFabError(PlayFabError error) { Debug.Log(error.GenerateErrorReport()); }
void DisplayError(string error) { Debug.LogError(error); }
```

1. 玩家登录后，即可访问好友的 UI。此功能通常至少包括添加、删除和显示好友。
2. 若要获取玩家当前的好友列表，请使用 [GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) API 调用。

```csharp theme={null}
List<FriendInfo> _friends = null;

void GetFriends() {
    PlayFabClientAPI.GetFriendsList(new GetFriendsListRequest {
        IncludeSteamFriends = false,
        IncludeFacebookFriends = false,
        XboxToken = null
    }, result => {
        _friends = result.Friends;
        DisplayFriends(_friends); // triggers your UI
    }, DisplayPlayFabError);
}
```

[GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) 的结果包含一个 friends 参数，它是一组 [FriendInfo](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist#friendinfo) 对象的列表。

3. 若要向玩家的好友列表中添加好友，请使用 [AddFriend](xref:titleid.playfabapi.com.client.friendlistmanagement.addfriend) API 调用。

```csharp theme={null}
enum FriendIdType { PlayFabId, Username, Email, DisplayName };

void AddFriend(FriendIdType idType, string friendId) {
    var request = new AddFriendRequest();
    switch (idType) {
        case FriendIdType.PlayFabId:
            request.FriendPlayFabId = friendId;
            break;
        case FriendIdType.Username:
            request.FriendUsername = friendId;
            break;
        case FriendIdType.Email:
            request.FriendEmail = friendId;
            break;
        case FriendIdType.DisplayName:
            request.FriendTitleDisplayName = friendId;
            break;
    }
    // Execute request and update friends when we are done
    PlayFabClientAPI.AddFriend(request, result => {
        Debug.Log("Friend added successfully!");
    }, DisplayPlayFabError);
}
```

4. 若要从玩家的好友列表中移除某位玩家，请使用 [RemoveFriend](xref:titleid.playfabapi.com.client.friendlistmanagement.removefriend) API 调用。

```csharp theme={null}
// unlike AddFriend, RemoveFriend only takes a PlayFab ID
// you can get this from the FriendInfo object under FriendPlayFabId
void RemoveFriend(FriendInfo friendInfo) {
    PlayFabClientAPI.RemoveFriend(new RemoveFriendRequest {
        FriendPlayFabId = friendInfo.FriendPlayFabId
    }, result => {
        _friends.Remove(friendInfo);
    }, DisplayPlayFabError);
}
```

## 更进一步

除了添加、删除和显示之外，您还可以对好友执行其他操作。

### 为好友添加标签

从 [GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) 检索到的 [FriendInfo](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist#friendinfo) 对象包含该好友的标签列表。更新此列表时，您需要从中添加和删除标签，并将其包含在 API 调用中（如下所示）。

```csharp theme={null}
// this REPLACES the list of tags on the server
// for updates, make sure this includes the original tag list
void SetFriendTags(FriendInfo friend, List<string> newTags)
{
    // update the tags with the edited list
    PlayFabClientAPI.SetFriendTags(new SetFriendTagsRequest
    {
        FriendPlayFabId = friend.FriendPlayFabId,
        Tags = newTags
    }, tagresult => {
        // Make sure to save new tags locally. That way you do not have to hard-update friendlist
        friend.Tags = newTags;
    }, DisplayPlayFabError);
}
```

您可以使用标签来告知匹配（例如，玩家不喜欢与被标记为 **2tuff** 的好友一起进行困难难度的游戏），实现好友分组 — 或者仅用它们来存储与关系相关的所需元数据。

需要重点注意的是，PlayFab 目前不会以任何方式为这些标签编制索引。[GetFriendsList](xref:titleid.playfabapi.com.client.friendlistmanagement.getfriendslist) 无法基于标签进行过滤，因此该操作必须在本地完成。

考虑此系统可能带来的任何性能影响时，请牢记这一点。


## Related topics

- [XBOX 要求](/zh-CN/services/playfab/multiplayer/networking/xbox-requirements.md)
- [PlayFab Party 邀请和安全模型](/zh-CN/services/playfab/multiplayer/networking/concepts-invitations-security-model.md)
- [XR-070 好友列表](/zh-CN/publishing/certification/xr/xr-070.md)
- [好友](/zh-CN/services/playfab/community/associations/friends/index.md)
- [FMA：XR-070 好友列表](/zh-CN/publishing/certification/fma/xr-070.md)