DHAPI
DHAPI 类内的多种方法阐释
DHAPI 类在 2.0.12 被添加。它的目的就是成为 DecentHolograms API 的主要用法,提供了创建、编辑与删除悬浮字、悬浮字页或行而无需直接与这些内容交互的方法。
创建悬浮字
DHAPI 类提供了 createHologram 方法来创建悬浮字,且可自由决定悬浮字是否永久存在,或是否带有默认文本。
基础的 createHologram 方法
最基础的代码看起来会像这样:
DHAPI.createHologram(String, Location);第一个参数即为悬浮字的名称,第二个参数则为悬浮字所在的位置(需传入一个 org.bukkit.Location 对象)
使用这个方法可以创建一个悬浮字,且它的第一行是配置文本中设定的“默认文本”。 除此之外这个悬浮字还是非持久的,因此它不会被保存至 YAML 文件,而且会在插件重载/服务器重启之后消失。
创建永久悬浮字
若要让悬浮字变成永久状态,我们同样可以使用 createHologram 方法,但要在它的末尾加上一个布尔值:
DHAPI.createHologram(String, Location, boolean);在这里填入 true 可以告诉 DecentHolograms,这条悬浮字是永久的,需要存进它在 holograms 下的 YAML 文件里。在这之后,这条悬浮字就会在插件启用时自动载入。
重要!
调用 createHologram 时若指定的悬浮字名称已存在,则会抛出一个错误。 若要避免这种情况,请先在调用方法前检查相同的悬浮字是否已存在。
public void createHologram(String name, Location location){
if(DHAPI.getHologram(name) != null)
return;
DHAPI.createHologram(name, location);
}添加初始文本
createHologram 方法也有提供了一种设定初始内容的方法,可以覆盖配置文件中提供的默认文本。 下为方法示例:
DHAPI.createHologram(String, Location, List<String>);当然,就像第一个例子的那样,这不会创建一个持久显示的悬浮字。但是,肯定有方法能让我们这么做:
DHAPI.createHologram(String, Location, boolean, List<String>);就像第二个例子那样,在这里填入 true 会让悬浮字能持久显示。
获取悬浮字
若要通过这个类编辑悬浮字,首先你要获得一个 Hologram 实例。这可以通过 getHologram 方法实现:
DHAPI.getHologram(String);如果给定名称对应的悬浮字不存在,这个方法会返回 null。
获取悬浮字页
DeceneHolograms 允许悬浮字有多页不同的文本。所以肯定有在悬浮字实例上获取 HologramPage 实例的方法。
方法本身很容易看懂:
DHAPI.getHologramPage(Hologram, int);int 处填入的应该为不小于 0 的整数,表示获取悬浮字的索引。
重要提醒
- 方法可能会返回
null,因此提供的页码应该不小于 0,且小于页码总数。 - 除非手动移除,否则悬浮字实例总会有一个序号为 0 的
HologramPage实例。
获取悬浮字行
因为一个悬浮字能有多页,因此 DHAPI 提供的 getHologramLine 方法会需要一个 HologramPage 实例。 上一部分已经提及了如何获取 HologramPage 实例。
在你获取了有效的 HologramPage 实例之后,你可以使用 getHologramLine 方法:
DHAPI.getHologramLine(HologramPage, int);int 处填入的应该为不小于 0 的整数,表示获取悬浮字的索引。
除此之外,你还可以直接对着返回的 HologramPage 实例使用 getLine 方法。
需要注意的是,正如上文警告过的那样,这个方法也可能会返回 null。 所以这个方法同样需要在使用 HologramPage 之前做好非空检查。
编辑悬浮字行
这里有多种方法编辑悬浮字,例如添加一行、编辑一行或者移除一行。
添加新行
为了将一行文本加入悬浮字,你需要使用 addHologramLine 方法。最基本的使用方式看起来会像这样:
DHAPI.addHologramLine(Hologram, String);这会向悬浮字的第一页添加一行文本。
如果你的如果你的悬浮字有很多页,并且你想要给除了第一页之外的其他页加上文本,你就可以用到下面这种方法:
DHAPI.addHologramLine(Hologram, int, String);int 处填入的应该为不小于 0 的整数,表示获取悬浮字的索引。需要注意的是,序号从 0 开始计数,例如第一页的序号为 0,第二页的序号为 1。
提示
你可以将 String 参数替换为 org.bukkit.Material 或 org.bukkit.ItemStack 示例。 这会按你提供的 Material / ItemStack 创建一个悬浮物品。 如果你传入的参数为后者,则某些 NBT 可能不会被加入。前者不包含任何 NBT 值。
覆盖已有行
你可以将某一行悬浮字改为其他内容,甚至将一整页悬浮字的内容都覆盖。
若要覆盖指定行文本,你可以使用下列方法:
DHAPI.setHologramLine(Hologram, int, String);int 处填入的应该为不小于 0 的整数,表示获取悬浮字的索引。需要注意的是,序号从 0 开始计数,例如第一页的序号为 0,第二页的序号为 1。
如果你的如果你的悬浮字有很多页,并且你想要给除了第一页之外的其他页加上文本,你就可以用到下面这种方法:
DHAPI.setHologramLine(Hologram, int, int, String);int 处填入的应该为不小于 0 的整数,表示获取悬浮字页的索引(同样以 0 起始)。第二个 int 填入的则是悬浮字行的索引。
提示
你可以将 String 参数替换为 org.bukkit.Material 或 org.bukkit.ItemStack 示例。 这会按你提供的 Material / ItemStack 创建一个悬浮物品。 如果你传入的参数为后者,则某些 NBT 可能不会被加入。前者不包含任何 NBT 值。
最后你也可以编辑整页的文本。若要这么做,你可以使用 setHologramLines 方法(注意末尾的 s)方法:
DHAPI.setHologramLines(Hologram, List<String>);与之前的例子一样,这个方法会修改第一页悬浮字。你可以使用如下方法来批量修改指定页的悬浮字行:
DHAPI.setHologramLines(Hologram, int, List<String>)插入新行
你可以通过这个方法将悬浮字插入指定行的位置。
最基本的方法看起来像这样:
DHAPI.insertHologramLine(Hologram, int, String);这会向悬浮字的第一页指定行号(以 0 起始)插入一行新文本。
与上文方法相似,这个方法也提供了一种能让你在其他页插入文本的方法:
DHAPI.insertHologramLine(Hologram, int, int, String);int 处填入的应该为不小于 0 的整数,表示获取悬浮字页的索引(同样以 0 起始)。第二个 int 填入的则是悬浮字行的索引。
提示
你可以将 String 参数替换为 org.bukkit.Material 或 org.bukkit.ItemStack 示例。 这会按你提供的 Material / ItemStack 创建一个悬浮物品。 如果你传入的参数为后者,则某些 NBT 可能不会被加入。前者不包含任何 NBT 值。
移除已有行
移除一行悬浮字也特别简单:
DHAPI.removeHologramLine(Hologram, int);这会向悬浮字的第一页指定行号(以 0 起始)删除一行现存文本。
若要移除其他页的悬浮字行,请使用这个方法:
DHAPI.removeHologramLine(Hologram, int, int);这将会移除指定页(第二页,以 0 起始的序号)指定行号(第三个参数)的悬浮字。
提示
与 List#remove 方法相似,删除方法会返回一个 HologramLine 实例,其中含有你删除的内容,这样你就可以把它用在其他地方。
编辑悬浮字页
DecentHolograms 提供了显示多页悬浮字的功能。
当然也提供了编辑与管理这些内容的方法。
添加新页
向悬浮字添加新的一页非常简单,只需调用 addHologramPage 方法:
DHAPI.addHologramPage(Hologram);这会添加一页悬浮字,初始内容则是来自 config.yml 设置中的预留文本。
若要创建包含自定义内容的一页悬浮字,你需要使用这个方法:
DHAPI.addHologramPage(Hologram, List<String>);插入新页
悬浮字页可通过 insertHologramPage 方法插入:
DHAPI.insertHologramPage(Hologram, int);这个方法将会在指定序号(以 0 起始)的悬浮字前加入一个新的 HologramPage 实例。被添加的 HologramPage 只会拥有 config.yml 设置中的预留文本。
当然也可以像上文那样为新加入的一页设定文本,方法如下:
DHAPI.insertHologramPage(Hologram, int, List<String>);删除已有页
移除一页悬浮字可以通过调用 removeHologramPage 实现:
DHAPI.removeHologramPage(Hologram, int)这个方法会返回一个包含被移除内容的 HologramPage 实例,这样你就可以把它用在其他地方。
提供的页码序号(以 0 起始)应该不小于 0,且小于页码总数,否则会返回 null。
SnowCutieOwO