PlaceholderAPI 专家 Wiki

本专家仅负责提供 PlaceholderAPI 相关的确定性 API 信息与示例，不覆盖或回答其他主题。

一、概述

PlaceholderAPI（简称 PAPI）是 Bukkit / Spigot / Paper 服务端中广泛使用的占位符解析框架，用于在文本中动态插入玩家、服务器或插件相关的数据。

占位符的基本格式为：

%identifier_key%

其中：

identifier：扩展标识符（由扩展提供）
key：具体变量名

二、核心类与包结构

1. 核心类

me.clip.placeholderapi.PlaceholderAPI

用于解析占位符、查询已注册扩展等。

2. 扩展基类（推荐）

me.clip.placeholderapi.expansion.PlaceholderExpansion

用于编写自定义占位符扩展（现代方式）。

3. 旧版钩子接口（不推荐新项目使用）

me.clip.placeholderapi.PlaceholderHook

主要用于兼容旧版扩展。

三、占位符解析常用方法

1. 解析单个玩家占位符

String result = PlaceholderAPI.setPlaceholders(
    player,
    "%player_name% 欢迎来到服务器!"
);

2. 解析离线玩家占位符

String result = PlaceholderAPI.setPlaceholders(
    offlinePlayer,
    "%player_name%"
);

注意：离线玩家可用的占位符取决于具体扩展实现。

3. 批量解析占位符列表

List<String> resultList = PlaceholderAPI.setPlaceholders(
    player,
    messageList
);

适用于公告、Lore、多行文本等场景。

4. 关系型占位符（两个玩家）

String result = PlaceholderAPI.setRelationalPlaceholders(
    player1,
    player2,
    "%rel_player1_name% vs %rel_player2_name%"
);

常用于 PVP、组队、好友、敌对关系等插件。

四、自定义 PlaceholderExpansion

1. 扩展占位符格式

假设 getIdentifier() 返回：

myplugin

则最终占位符形式为：

%myplugin_变量名%

2. 关键方法说明

`getIdentifier()`

@Override
public String getIdentifier() {
    return "myplugin";
}

返回扩展的唯一标识符。

`getAuthor()`

@Override
public String getAuthor() {
    return "YourName";
}

`getVersion()`

@Override
public String getVersion() {
    return "1.0.0";
}

`onPlaceholderRequest(Player player, String params)`

@Override
public String onPlaceholderRequest(Player player, String params) {
    if (player == null) {
        return "";
    }

    if (params.equalsIgnoreCase("health")) {
        return String.valueOf(player.getHealth());
    }

    if (params.equalsIgnoreCase("level")) {
        return String.valueOf(player.getLevel());
    }

    return null;
}

说明：

params：占位符中 _ 后的部分
- %myplugin_health% → health
返回 null：表示该占位符不存在
player 可能为 null，必须先判空

五、高级查询 API

1. 获取所有已注册的扩展标识符

Set<String> identifiers = PlaceholderAPI.getRegisteredIdentifiers();

示例返回内容：

player
vault
essentials
myplugin

2. 获取所有已注册的占位符扩展

Map<String, PlaceholderHook> map = PlaceholderAPI.getPlaceholders();

主要用于调试或兼容旧系统。

3. 判断字符串是否包含占位符

boolean has = PlaceholderAPI.containsPlaceholders("%player_name%");

常用于优化性能，避免不必要的解析。

六、使用与回答规范

当问题涉及以下内容时：
- 如何解析占位符
- 如何编写 PlaceholderAPI 扩展
- 如何判断占位符是否存在或有效
  必须基于本文列出的类名与方法，提供可编译的 Java 示例
必须清晰区分：
- 占位符格式：%identifier_key%
- 扩展标识符：identifier
禁止：
- 编造不存在的 API
- 使用错误的方法名或类名
若问题 不属于 PlaceholderAPI 范围，应明确说明：

本专家仅覆盖 PlaceholderAPI API 相关知识

PlaceholderAPI 知识文档

Overview