Creating Placeholder Tokens

Предупреждение

Эти документы были написаны для SpongeAPI 7 и, вероятно, устаревшие. Если вы чувствуете, что вы можете помочь обновить их, пожалуйста, отправьте PR!

Основой Sponge Placeholder API является возможность создавать свои собственные токены для плейсхолдеров , делая их доступными для всех плагинов. Чтобы создать свой плейсхолдер, вы должны создать объект наследующий PlaceholderParser, который будет зарегистрирован в соответсвующем регистре.

Creating PlaceholderParsers

There are two ways you can create a PlaceholderParser:

• Воспользуйтесь PlaceholderParser#builder(): предоставьте ваш PluginContainer, ID токена и функцию, которая получает PlaceholderContext и возвращает Component.

• Directly implement the interface.

PlaceholderParser объект требует PlaceholderContext, который содержит в себе контекст запроса и возвращает Component основанный на этом контексте. PlaceholderContext может содержать в себе:

• An associated object, such as a Player

• An argument string which generally will be provided by a templating engine

This is the minimum as specified by Sponge.

Если ваш плейсхолдер не может предоставить текст по каким либо причинам, например потому что в контексте отсутствуют необходимые данные или аргументы, плейсхолдер должен возвращать пустой Component, а не выбрасывать исключение.

Совет

If you wish to provide the ability to add multiple arguments to your placeholder, consider specifying a way to split up the argument string.

Remember to tell users of your plugin what you expect your argument string to look like.

Example: Default World Name PlaceholderParser

Указанный PlaceholderParser пытается получить название мира по умолчанию, возвращая пустой Component, если тот не может быть найден. Он использует конструктор для создания парсера с ID spongedocs:defaultworld, предполагая, что ID плагина spongedocs.

import net.kyori.adventure.text.Component;

PluginContainer thisPlugin = ...;

PlaceholderParser parser = PlaceholderParser.builder()
    .plugin(this.thisPlugin)
    .id("defaultworld")
    .name("Default World Placeholder")
    .parser(placeholderContext -> {
        return Sponge.getServer()
            .getDefaultWorld()
            .map(x -> x.getWorldName())
            .orElse(Component.empty());
    })
    .build();

Example: Player Location PlaceholderParser

Этот PlaceholderParser пытается получить местоположение игрока в мире. Если он будет использован без Player в качестве связанного объекта, он вернет пустой Component. Этот парсер напрямую реализует интерфейс PlaceholderParser.

import net.kyori.adventure.text.TextComponent;

public class PlayerLocationPlaceholder implements PlaceholderParser {

    @Override
    public String getId() {
        return "spongedocs:location"
    }

    @Override
    public String getName() {
        return "Location Placeholder"
    }

    @Override
    public Component parse(PlaceholderContext placeholderContext) {
        placeholderContext.associatedObject()
            .filter(x -> x instanceof Player)
            .map(player -> ((Player) player).getLocation())
            .map(location -> TextComponent.ofChildren(
                Component.text("World: "),
                Component.text(location.getExtent().getName()),
                Component.text(" - "),
                Component.text(location.getPosition())))
            .orElse(Component.empty());
    }
}

Example: Current Time PlaceholderParser

This PlaceholderParser returns the current time in the server’s local timezone. If the string «UTC» is provided as the argument string, it returns the current time in the UTC time zone. This implements the PlaceholderParser interface directly.

public class CurrentTimePlaceholder implements PlaceholderParser {

    @Override
    public String getId() {
        return "spongedocs:currenttime";
    }

    @Override
    public String getName() {
        return "Current Time parser";
    }

    @Override
    public Component parse(PlaceholderContext placeholderContext) {
        if (placeholderContext.argumentString().filter(x -> x.equalsIgnoreCase("UTC")).isPresent()) {
            return Component.text(OffsetDateTime.now(ZoneOffset.UTC).format(FORMATTER));
        }
        return Component.text(OffsetDateTime.now().format(FORMATTER));
    }

}

Registering Your PlaceholderParser

For your parser to be easily accessible to other plugins, it must be registered in the registry. This should be done by listening to the GameRegistryEvent.Register<PlaceholderParser> event and registering your parsers using the register method.

Example: Registering a PlaceholderParser

PlaceholderParser parser = ...;

@Listener
public void registerTokensEvent(GameRegistryEvent.Register<PlaceholderParser> event) {
    event.register(this.parser);
}