DecentHolograms API 文档

概述

DecentHolograms 是一个 Minecraft 插件，提供创建和管理悬浮字的功能。其 API 允许开发者创建、编辑和管理悬浮字。

包名和依赖

主包名: com.github.decentsoftware-eu:decentholograms
版本: 2.8.6
依赖类型: 硬依赖（插件需要 DecentHolograms 才能正常工作）

API 核心类

DHAPI 类

在 2.0.12 版本中添加，是 DecentHolograms API 的主要用法，提供创建、编辑与删除悬浮字、悬浮字页或行的方法，无需直接与这些内容交互。

创建悬浮字

基础创建方法

DHAPI.createHologram(String name, Location location);

第一个参数：悬浮字名称
第二个参数：位置（org.bukkit.Location 对象）
创建非持久悬浮字，不会保存到 YAML 文件，插件重载/服务器重启后消失
第一行使用配置中的"默认文本"

创建永久悬浮字

DHAPI.createHologram(String name, Location location, boolean persistent);

第三个参数：true 表示永久悬浮字，会保存到 holograms 下的 YAML 文件
插件启用时自动载入

重要注意事项

如果指定名称的悬浮字已存在，会抛出错误
建议先检查悬浮字是否存在：

public void createHologram(String name, Location location) {
    if(DHAPI.getHologram(name) != null)
        return;
    DHAPI.createHologram(name, location);
}

添加初始文本

DHAPI.createHologram(String name, Location location, List<String> lines);
DHAPI.createHologram(String name, Location location, boolean persistent, List<String> lines);

可以覆盖配置文件中的默认文本
第二个版本创建持久悬浮字

获取悬浮字

获取悬浮字实例

DHAPI.getHologram(String name);

返回 Hologram 实例
如果不存在返回 null

获取悬浮字页

DHAPI.getHologramPage(Hologram hologram, int pageIndex);

返回 HologramPage 实例
pageIndex 应该不小于 0
可能返回 null，需要检查页码是否有效
悬浮字实例总有一个序号为 0 的 HologramPage 实例（除非手动移除）

获取悬浮字行

DHAPI.getHologramLine(HologramPage page, int lineIndex);

返回 HologramLine 实例
lineIndex 应该不小于 0
可能返回 null，需要非空检查
也可以直接使用 HologramPage 的 getLine() 方法

编辑悬浮字行

添加新行

DHAPI.addHologramLine(Hologram hologram, String text);
DHAPI.addHologramLine(Hologram hologram, int pageIndex, String text);

第一个方法向第一页添加文本
第二个方法向指定页添加文本
pageIndex 从 0 开始计数（0=第一页，1=第二页）

提示：String 参数可以替换为：

org.bukkit.Material – 创建悬浮物品（不包含 NBT）
org.bukkit.ItemStack – 创建悬浮物品（某些 NBT 可能不会被加入）

覆盖已有行

DHAPI.setHologramLine(Hologram hologram, int lineIndex, String text);
DHAPI.setHologramLine(Hologram hologram, int pageIndex, int lineIndex, String text);
DHAPI.setHologramLines(Hologram hologram, List<String> lines);
DHAPI.setHologramLines(Hologram hologram, int pageIndex, List<String> lines);

可以覆盖单行或整页内容
setHologramLines 方法（注意末尾的 s）可以批量修改

插入新行

DHAPI.insertHologramLine(Hologram hologram, int lineIndex, String text);
DHAPI.insertHologramLine(Hologram hologram, int pageIndex, int lineIndex, String text);

在指定位置插入新行
lineIndex 从 0 开始计数

移除已有行

DHAPI.removeHologramLine(Hologram hologram, int lineIndex);
DHAPI.removeHologramLine(Hologram hologram, int pageIndex, int lineIndex);

移除指定行
返回 HologramLine 实例，包含被删除的内容

编辑悬浮字页

添加新页

DHAPI.addHologramPage(Hologram hologram);
DHAPI.addHologramPage(Hologram hologram, List<String> lines);

第一个方法添加使用 config.yml 中预留文本的新页
第二个方法添加包含自定义内容的新页

插入新页

DHAPI.insertHologramPage(Hologram hologram, int pageIndex);
DHAPI.insertHologramPage(Hologram hologram, int pageIndex, List<String> lines);

在指定页码前插入新页
pageIndex 从 0 开始计数

删除已有页

DHAPI.removeHologramPage(Hologram hologram, int pageIndex);

移除指定页
返回包含被移除内容的 HologramPage 实例
页码应该不小于 0 且小于页码总数，否则返回 null

事件系统

DecentHologramsEvent

最基础的事件，所有其他事件都从此继承
可以用作其他基于 DecentHolograms 事件的全部捕获
推荐使用更具体的事件，或使用 instanceof 检查获取更详细的事件实例
不会影响服务器中的任何外部方法

DecentHologramsReloadEvent

在 /dh reload 命令重载服务器后触发
如果插件需要注意 DecentHolograms 的重载（例如刷新通过其他方法添加的特殊内容），这个事件很有用
不会影响服务器中的任何外部方法

HologramClickEvent

在玩家左/右键点击悬浮字时触发
事件可被取消，允许进一步处理相关内容

提供的方法：

getPlayer() – 返回点击了悬浮字的玩家
getHologram() – 返回被点击的悬浮字名称
getHologramPage() – 返回被点击的悬浮字页码
getClickType() – 返回点击类型（使用左右键点击，及点击时是否按住了 Shift）
getEntityId() – 返回被点击实体的类型

使用建议

依赖管理：在 plugin.yml 或 paper-plugin.yml 中添加 DecentHolograms 为软依赖
错误处理：所有获取方法都可能返回 null，需要进行非空检查
持久化：需要保存的悬浮字应使用持久化创建方法
事件处理：根据需求选择合适的事件进行监听和处理

注意事项

悬浮字名称必须唯一，重复创建会抛出错误
页码和行号都从 0 开始计数
所有获取方法都需要进行非空检查
持久悬浮字会保存到 YAML 文件，非持久悬浮字在重启后消失
可以使用 Material 或 ItemStack 创建悬浮物品.

文档来自SnowCutieOwO – wiki

Overview