設定插件

警告

这些文档是为 SpongeAPI 7 编写的，可能已经过时。如果你觉得你可以帮助更新它们，请提交一个 PR！

在你允許的情況下，設定檔使插件能夠儲存資料，也使伺服器管理員能夠輕易控制插件的特定部分。Sponge 使用 Configurate 來讓你能夠輕易操作設定檔。這些頁面將解釋如何利用 Configurate 來充分利用設定檔。

小訣竅

参见 Configurate 的官方 wiki 以获取更深层次的关于使用其组件的信息。

備註

Sponge 利用一種名為 HOCON 的設定格式，一個 JSON 的超集，作為儲存設定檔的預設格式。本指南的剩餘部分將假設你也使用 HOCON 。參閱 HOCON 介紹以獲取更多關於 HOCON 格式的資訊。透過設定系統使用不同格式的設定檔是相似的。因此若你使用另一種格式來代替，應該不會構成太多問題。

快速入門

建立一個預設的插件設定

使用 SpongeAPI 的插件可以選擇使用一個或多個設定檔。設定檔讓插件能夠儲存資料，也讓伺服器管理員能夠自定義插件選項（如果適用）。

取得你的預設插件設定

SpongeAPI 提供的 DefaultConfig Annotation 可用於一個欄位（Field）或 Setter 方法，搭配 Path 類別來取得你插件的預設設定檔。

你可以通过在某个 ConfigurationLoader<CommentedConfigurationNode> 的字段上加 @DefaultConfig 注解的方式来存取默认配置文件。要注意的是，ConfigurationLoader 不会加载你的 jar 自带的默认配置，除非你明确要求加载。

@DefaultConfig 這個 Annotation 需要一個布林值 sharedRoot。若你將 sharedRoot 設為 true，那麼它回傳的路徑將位於一個共享的設定資料夾，在這情況下，你的插件的設定檔名稱將為 your_plugin_id.conf（其中「your_plugin_id」將被取代為你的插件所指定的 ID）。

小訣竅

參閱主要插件類別以獲取設定你的插件 ID 的更多資訊。

若你將 sharedRoot 設為 false，那麼回傳的路徑將會是在你插件的資料夾中名為 {pluginname}.conf 的檔案。

如果你不確定該將 sharedRoot 設為什麼，請考慮以下幾項：

如果你打算擁有多個設定檔（複雜的插件），將其值設定為 false。
如果你打算只擁有一個設定檔（不太複雜的插件），將其值設定為 true。

你也可以取得一個指向設定資料夾而非特定檔案的 Path 實例，只要使用 ConfigDir Annotation 注入即可。將 sharedRoot 設為 false 時，會是插件資料夾；設為 true 時，會是共享的設定資料夾。

備註

儘管可能取得一個 File 而非 Path，Configurate（與 Sponge）建議使用 Path。

範例——在欄位（Field）使用 @DefaultConfig

import java.nio.file.Path;
import com.google.inject.Inject;
import org.spongepowered.api.config.ConfigDir;
import org.spongepowered.api.config.DefaultConfig;
import org.spongepowered.configurate.CommentedConfigurationNode;
import org.spongepowered.configurate.loader.ConfigurationLoader;

@Inject
@DefaultConfig(sharedRoot = true)
private Path defaultConfig;

@Inject
@DefaultConfig(sharedRoot = true)
private ConfigurationLoader<CommentedConfigurationNode> configManager;

@Inject
@ConfigDir(sharedRoot = false)
private Path privateConfigDir;

警告

當你的插件在第一次運行時，回傳的設定檔與資料夾的路徑可能還未存在。若你將所有讀檔／寫檔委託給 Configurate，那你不必擔心不存在的路徑，函式庫會適當的處理這些情況。

備註

YAML 格式（http://yaml.org/spec/1.1/）與 JSON 格式（https://www.json.org/）也被支援，但 Sponge 插件設定檔格式的首選是 HOCON。可以透過使用 YAMLConfigurationLoader（或 GsonConfigurationLoader）讀取舊設定檔，並使用 HoconConfigurationLoader 將它們儲存，來將 YAML（或 JSON）自動轉換為 HOCON。