黑名单

作为一个在 SpongeAPI 中内置的服务，BanService 添加了一些功能，允许插件开发者禁止或解禁用户。 BanService 提供了若干方法用于将用户禁止、解禁、或者甚至得到关于 Ban 和 Ban 的信息。

小技巧

为了保证你已对服务（Service）这一概念有了基本的了解，请先保证你已了解 服务 中的内容。

获取 BanService

您将需要获取 BanService 来向服务器实际添加黑名单。幸运的是，完成这件事的方式和 SpongeAPI 中的其他服务类似：

import org.spongepowered.api.Sponge;
import org.spongepowered.api.service.ban.BanService;

BanService service = Sponge.serviceManager().provide(BanService.class).get();

现在有了 BanService ，我们还可以进行其他操作。例如，如果我们想检查一个给定的 User 是否在黑名单内，我们可以使用 BanService#isBanned(GameProfile) 方法。或者如果我们想从 User 获取关于黑名单的信息，我们可以使用 BanService#getBanFor(GameProfile) 方法。下面是一个示例：

import java.util.Optional;

import net.kyori.adventure.text.Component;
import org.spongepowered.api.entity.living.player.User;
import org.spongepowered.api.util.ban.Ban;

if (service.isBanned(user.getProfile())) {
    CompletableFuture<Optional<Ban.Profile>> optionalBanFuture = service.find(player.getProfile());
    optionalBanFuture.thenAccept(optionalBan -> {
        if (optionalBan.isPresent()) {
            Ban.Profile profileBan = optionalBan.get();
            Optional<Component> optionalReason = profileBan.getReason();
            if (optionalReason.isPresent()) {
                Component banReason = optionalReason.get();
            }
        }
    });
}

使用黑名单

所以现在我们可以获得 BanService 和 Ban 的信息，但是如果我们想创建自己的 Ban 呢？ 我们可以调用 Ban#builder() 方法，得到 Ban.Builder 并使用它来创建我们自己的 Ban 。通过使用生成器，我们可以指定加入黑名单的匹配类型，加入黑名单的原因或我们希望禁止的 User 。下面是所有这些事情的示例：

import org.spongepowered.api.util.ban.BanTypes;

Ban ban = Ban.builder().type(BanTypes.PROFILE).profile(user.getProfile())
    .reason(Component.text("The Sponge Council has Spoken!")).build();

当然，你可以指定以 IP 的方式匹配在线玩家：

Ban ban = Ban.builder().type(BanTypes.IP)
    .address(player.getConnection().getAddress().getAddress())
    .reason(Component.text("The Sponge Council has Spoken!")).build();

注意，如果你只是希望创建一个简单的、不确定的 User 黑名单，你可以使用 Ban#of(GameProfile) 或者 Ban#of(GameProfile, Component) 方法快速创建。

加入黑名单

现在我们完成了创建，那么我们就可以将其用于 Sponge 了。通过使用之前我们获取的 BanService 的 BanService#addBan(Ban) 方法我们就可以方便地使用新的黑名单。注意添加新的黑名单会移除任何旧的黑名单。

解禁

现在我们想要解禁某一个人。我们可以通过 BanService#pardon(GameProfile) 方法解决这一问题。这一方法返回一个布尔值用于表示该用户之前是否位于黑名单中。

总结

我们可以使用 Ban#builder() 方法生成的 Ban.Builder 创建一个 Ban 。我们可以指定加入黑名单的匹配类型，要禁止的 User 以及原因。 然后我们只是使用 BanService 来添加我们的 Ban 。下面是所有过程的完整代码：

BanService service = Sponge.getServiceManager().provide(BanService.class).get();
Ban ban = Ban.builder().type(BanTypes.PROFILE).profile(user.getProfile())
    .reason(Component.text("The Sponge Council has Spoken!")).build();
service.addBan(ban);