Configuration API Reference

点击此处浏览原文

本页面已存在其他语言的内容，请协助翻译为本地化的中文。

• 点击此处开始翻译。
• 如本模板出现在原文存档页面，请注意更新主页面后，仍需要去除此处该模板。
• 如当前页面已经没有需要翻译的内容，请删去待翻译模板。
• 有标题的大篇幅文章，如果短时间内无法全部翻译，请先把所有的标题翻译出来，以便之后的贡献者选择与翻译章节内容。

Configuration API是一个能够帮助开发者快速解析与编辑配置文件的工具，它让配置文件更简单、更容易读写。无论是什么，这个API可以帮助你更容易的存储你插件的配置信息。目前只有这个 YAML configurations 可以用。然而这个API被设计有广泛的拓展性，这意味着它允许你实现其他需要实现的东西。

Configuration API存在于 org.bukkit.configuration 和 org.bukkit.configuration.file 这两个包中。如果是创建在 1.1-R5 版本之前的插件，就只能用老版本并且与本文截然不同的API了，这些老版API在老版本的org.bukkit.util.configuration包中。这些内容彼此互不兼容，并且因为老的方法太过时了，所以在新版中已被删去。

本文假定你对面向对象思想、Java与Bukkit插件编写的核心思想有着相当深的了解与认识。 本文并非JavaDocFileConfiguration Class的替代品。

（译者注：上方链接因过时，已经替换到了最新的新版链接当中，内容稍微与原文有所不符，但影响不大）

基本论述

配置文件对象

当你的插件主类继承 JavaPlugin 类时也会继承父类 JavaPlugin 类的方法和属性。 在被继承的方法中, getConfig() 返回的是一个 FileConfiguration类型的对象。这个对象就代表你插件数据文件夹里的config.yml 文件。

你的插件在第一次调用getConfig()方法时，会从你插件的jar文件中读取相应的config.yml 文件，同时从jar中的config.yml文件里加载相应的默认数据。 需要注意的是，在第一次使用之后若再次调用getConfig()方法，只会返回内存中保存的FileConfiguration 对象，而并非磁盘上保存的最新的，并且你对这个对象进行的修改并不会被保存，除非你手动保存。同理，在第一次调用getConfig()方法之后，对磁盘上的config.yml文件的修改不会被同步给这个对象。如果在 plugins 文件夹中对应的插件文件夹里不存在 config.yml ，这时会等价于存在一个空的config.yml文件, 也会加载一个空的FileConfiguration对象。

如果你在利用getConfig()的返回值，请不要把它赋给一个变量来使用
如果需要这样的话，一定要记住在重载配置文件后，再把 getConfig() 方法的返回值分配给那个变量
保险起见，推荐你尽可能的直接用getConfig()方法，而不是将其分配给一个变量

键

一个配置文件由键值对构成，键是一个字符串。键对应的值可能是一个 ConfigurationSection 对象或是其他形式的数据. getKeys(boolean) 方法会返回一个存有当前FileConfigurationSection所有键的集合，布尔值决定着是否递归地返回集合，如果值为true，将返回指定部分的所有键与所有对应子键, 如果为false则只会返回指定部分的所有键（不含子键）。 若要获取特定部分的所有键，需调用特定部分ConfigurationSection对象的 getKeys(boolean) 方法。 你可使用getConfigurationSection(String)方法来获取这个部分。

getKeys(boolean)方法返回的是一个字符串集合

路径

Configuration API 中使用路径（Path）来构成一个独立的键值对。 一个路径是一层层的键的组合，被用来联系所对应的值。 每一层都用路径分隔符区分开来，路径分隔符通常是 '.' (段落)。 举个例子，下面的YMAL文件有着下面这些组路径。

key: value
one:
  two: value
  three:
    - values
    - values
    - values
  four: 
    five: value
  *:
    six: value
    seven: value

• key
• one
• one.two
• one.three
• one.four
• one.four.five
• one.*
• one.*.six
• one.*.seven

默认值

你的插件jar中应该为用户准备一个默认的config.yml文件。当config.yml丢失或是不完整的情况发生时，要获取的值将会从jar内的 config.yml文件来获取。被准备的文件必须被命名为 config.yml ，且应当放在与 plugin.yml相同目录下。你应该在jar里的config.yml里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。

this.saveDefaultConfig()

如果你想动态的把一对键值作为默认值，你可以利用addDefault(String, Object) 方法和 addDefaults(Map<String,Object>) 方法。

有时如果你想添加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。

this.getConfig().options().copyDefaults(true)

创建一份config.yml的拷贝

你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

获得值

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在这里找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

• getBoolean(String) 获取键对应的类型为boolean的值
• getInt(String) 获取键对应的类型为 int 的值
• getString(String) 获取键对应的类型为 String 的值
• getList(String) 获取键对应的类型为 List 的值
• getStringList(String)

HashMaps

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a HashMap, a ConfigurationSection must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.

this.getConfig().getConfigurationSection("path.to.map").getValues(false)

设定值

Writing values involves invoking the set(String, Object) method on an instance of Configuration. Unlike the different get methods that FileConfiguration has, there is only one set method. Not all objects can be set, only primitive types, String, Lists, and types that implement ConfigurationSerializable, such as Vector and ItemStack, can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:

// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);

HashMaps

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The context above is to minimize unpredictability.

To set a HashMap, a ConfigurationSection must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod

this.getConfig().createSection(String path, Map< String, Object > map)

保存文件

如果你对一个 FileConfiguration 对象进行了修改操作，或者改变了某些 Lists，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。

this.saveConfig();

从磁盘中重载配置文件

如果你怀疑用户在插件数据文件夹里修改了config.yml，并且那些数据并没有更新在内存里。你可以用 reloadConfig() 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。

this.reloadConfig();

<references />

高级

The following are some more advanced topics, meant for more advanced plugins. If you only require the default config.yml, creating custom methods for reading, and saving, you will not need to go this far.

菜单

Every FileConfiguration instance is associated with a FileConfigurationOptions object. The FileConfigurationOptions object controls the behavior of the FileConfiguration it is associated with. FileConfiguration's options() method returns the FileConfigurationOption's responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example copyDefaults() which returns a boolean and copyDefaults(boolean) which returns it self, but has a side effect which changes the state.

CopyDefaults

The copyDefaults option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

PathSeperator

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

Header

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

copyHeader

If copyHeader() returns true then the header will be copied on save, from the default source.

自定义配置文件

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 JavaPlugin 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

JavaPlugin 镜像的实现

javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

ClickHere

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

private FileConfiguration customConfig = null;
private File customConfigFile = null;

实现重载

然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。

public void reloadCustomConfig() {
    if (customConfigFile == null) {
    customConfigFile = new File(getDataFolder(), "customConfig.yml");
    }
    customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

    // Look for defaults in the jar
    Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
    if (defConfigStream != null) {
        YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
        customConfig.setDefaults(defConfig);
    }
}

实现获取

Next, you need to write the getter method. Check if customConfig is null, if it is load from disk. 接下来，您需要编写getter方法。如果customconfig是从磁盘加载，请检查它是否为null。

public FileConfiguration getCustomConfig() {
    if (customConfig == null) {
        reloadCustomConfig();
    }
    return customConfig;
}

实现保存

Finally, write the save method, which saves changes and overwrites the file on disk.

public void saveCustomConfig() {
    if (customConfig == null || customConfigFile == null) {
        return;
    }
    try {
        getCustomConfig().save(customConfigFile);
    } catch (IOException ex) {
        getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
    }
}

实施默认覆盖

Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.

public void saveDefaultConfig() {
    if (customConfigFile == null) {
        customConfigFile = new File(getDataFolder(), "customConfig.yml");
    }
    if (!customConfigFile.exists()) {            
         plugin.saveResource("customConfig.yml", false);
     }
}

序列化与反序列化对象

在 Configuration API 中，上面提及的可以存储的对象均实现（implements）了 ConfigurationSerializable 接口。 对象序列化可以有助我们保存和读取数据，来让插件开发者集中开发插件的其他部分。 它真正的使一些任务变得简单明了了，就例如存储一个 Location 对象到YAML文件当中， 开发者可以序列化一个包装类，用以提供取用 Location 对象的方法。

Classes, 除了implementing the ConfigurationSerializable interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

• A constructor that accepts a single Map.
• A static method "deserialize" that accepts a single Map and returns the class.
• A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:

ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)

{{{1}}} Do not use a static block to execute the above; if you do so, it will not be called a second time when /reload is used and you will encounter errors due to it not being registered!

Aliases

When classes are serialized they are marked with their fully qualified name.

You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the SerializableAs annotation to the class implementing ConfigurationSerializable.

@SerializableAs(String)

When registering a class with an alias, the alias must be provided on registration.

ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)

使用样例

下面是一个使用了新版Configuration API的样例插件，它可以显示MOTD信息给进入服务器的玩家，并且可以让玩家使用指令获取规则（rule）。此处为了让代码行数达到最佳，代码没有采用适当的风格和插件布局。

import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;


public class SimpleMOTD extends JavaPlugin {

    @Override
    public void onEnable() {
        // 如果没有默认 config.yml 文件，保存一个默认配置副本
        this.saveDefaultConfig();
        
        // 注册新的监听器
        getServer().getPluginManager().registerEvents(new Listener() {
            
            @EventHandler
            public void playerJoin(PlayerJoinEvent event) {
                // 当玩家进入服务器时发送 config.yml 文件里的信息
                event.getPlayer().sendMessage(this.getConfig().getString("message"));
            }
        }, this);

        // 给获取规则指令（rules）设置命令执行器（Command Executor）
        this.getCommand("rules").setExecutor(new CommandExecutor() {
            
            public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
                // 当指令被执行，发送 config.yml 里的规则信息给输入指令的人
                List<String> rules = this.getConfig().getStringList("rules");
                for (String s : rules){
                    sender.sendMessage(s);
                }
                return true;
            }
        });
    }
}

插件jar文件中的默认 config.yml 文件

# default config.yml
message: Hello World and Welcome! :)
rules:
  - Play Nice
  - Respect others
  - Have Fun