MVdWPlaceholderAPI - 统一占位符管理

MVdW Placeholder API 是一个为我的付费插件提供支持的 API。如果你没有购买我的任何付费插件，请不要使用此 API。你必须使用我的插件的最新版本。支持服务仅在我的付费插件的讨论帖中提供。

💡关于此 API

MVdW Placeholder API 是一个 API，允许你一次性向我的所有 MVdW 占位符插件注册占位符。如果你的插件需要替换占位符，并且我的任意一个占位符插件已安装，此 API 也能提供支持，为你提供超过 5000 个且仍在不断增长的占位符库。请注意，此插件/API 本身不包含任何占位符，它是我的所有占位符插件与自定义或第三方插件之间的桥梁。

此插件充当占位符与我的占位符插件之间的接口。为了让我的占位符与我各种占位符插件兼容，它充当了它们之间的共享 API。下载和加载仍由占位符插件处理，MVdWPlaceholderAPI 则提供所需的共享类。

❓要求

• Java 7 或更高版本
• 任意 MVdW 占位符插件（见上文说明）

🔧服务器管理员使用指南

• 确保你已安装任意 MVdW 占位符插件。
• 将此插件放入服务器的 plugins 文件夹。
• 启动服务器。如果你安装了多个 MVdW 占位符插件，此插件会在控制台显示它正在使用哪个插件来获取占位符。了解这一点很有用，因为占位符的配置仍需在该插件中进行。
• 如果有任何插件挂钩到 MVdWPlaceholderAPI，控制台会为每个被添加的占位符显示一条消息。

🎮API 源码与 Maven 仓库

源码

API 及内联文档可在 GitHub 获取

https://github.com/Maximvdw/MVdWPlaceholderAPI

你需要关注的主要类是

• PlaceholderAPI.java
• PlaceholderReplaceEvent.java
• PlaceholderReplacer.java

Jenkins 构建

如需获取自定义版本或开发构建，请使用 Jenkins 构建服务器：

http://ci.mvdw-software.be/job/MVdWPlaceholderAPI/

Maven 仓库

Maven 是挂钩到 Placeholder API 以轻松获取最新版本的最简单方式。

仓库配置：

<repository>
    <id>mvdw-software</id>
    <name>MVdW Public Repositories</name>
    <url>http://repo.mvdw-software.be/content/groups/public/</url>
</repository>

依赖配置：

（注意：请根据最新版本更改版本号）

<dependency>
    <groupId>be.maximvdw</groupId>
    <artifactId>MVdWPlaceholderAPI</artifactId>
    <version>2.1.1-SNAPSHOT</version>
</dependency>

⭐开发者 API 使用指南

首先，你必须确保你的插件引用了此 API 插件。请勿将此 API 的 JAR 文件打包（shade）或直接包含在你的插件中。

内部机制说明

此 API 的工作方式是：你可以注册一个接口，当需要替换特定占位符时，该接口将被执行。这些与特定占位符关联的接口引用存储在 API 本身中。当 FeatherBoard 或其他任何 MVdW 占位符插件请求替换占位符时，API 会检查是否有与你添加的占位符匹配的项。如果存在，则会触发该接口，并传递一个包含“为哪个玩家替换占位符”信息的事件。当你的插件请求 API 替换占位符时，将首先使用挂钩到 API 的 MVdW 插件来获取占位符。来自 MVdW 占位符插件的占位符以及你或他人添加的自定义占位符都将被替换。

挂钩到 API

你应该做的第一件事是挂钩到 API。在尝试对其进行任何操作之前，你必须确认 API 存在。

注意： 以下示例将所有操作放在主类中，建议将其分离。

• （软）依赖： 在你的 plugin.yml 中将 MVdWPlaceholderAPI 设置为软依赖或硬依赖。
• 导入类：

    import be.maximvdw.placeholderapi.PlaceholderAPI;
    import be.maximvdw.placeholderapi.PlaceholderReplacer;
    import be.maximvdw.placeholderapi.PlaceholderReplaceEvent;

• 检查插件是否存在：

一旦我们确认插件存在，就可以使用它了。

注册自定义占位符

注册一个可以在所有 MVdW 占位符插件中使用的自定义占位符。

PlaceholderAPI.registerPlaceholder(Plugin plugin, String placeholder, PlaceholderReplacer replacer);

registerPlaceholder 方法接受 3 个参数：

• plugin: 正在注册占位符的插件（你的插件）
• placeholder: 你要注册的占位符（不带 { }，小写）
• replacer: 占位符替换器接口的实例

事件中会包含在线玩家和离线玩家信息，具体取决于占位符的条件。请自行进行 NULL 检查！

重要提示： 如果你使用 MySQL 或任何类型的数据库，请务必进行缓存。这些请求可能每秒发生多次，并且必须尽快返回结果。

替换占位符

此插件能够使用第一个挂钩到 API 的 MVdW 占位符插件来替换占位符（参见“服务器管理员使用指南”部分）。

示例：

完整示例可在此处找到

• https://github.com/Maximvdw/MVdWPlaceholderAPIExample
• http://ci.mvdw-software.be/job/MVdWPlaceholderAPIExample/

✨许可与使用条款

• 允许在免费/公开插件中使用，但需注明出处。
• 也允许在付费插件中使用，但需注明出处，且占位符不应成为你的主要卖点。同样适用于作为多个占位符核心接口的 API 插件。
• 我保留此占位符 API 的源代码和二进制形式的所有权利。
• 如果某些占位符或添加占位符的插件对整体性能产生不良影响（例如无缓存或执行非常密集的任务），我保留阻止其使用的权利。
• 建议允许用户（通过配置）定义是否允许你的插件向 API（进而向 MVdW 占位符插件）添加占位符。
• 支持服务仅提供给购买了我的占位符插件的 Spigot 用户。未购买插件 = 无支持。