# YAML API
YAML API 是一个专门的库，简化了在 Bukkit/Spigot/Paper 插件中使用 YAML 配置文件。它提供了一个强大的且一致的接口，用于加载、保存、更新和管理基于 YAML 的配置，并具有高级的配置部分和可配置单元的映射功能。
---
## 概述
**YAML API** 包提供了一组工具，旨在有效地处理 YAML 配置文件。它抽象了文件 I/O 和基于反射的配置解析的复杂性，使您能够专注于在插件中使用配置数据。
主要组件包括：
- **YAMLFile**: 用于加载、保存和更新 YAML 配置文件。
- **ResourceUtils**: 处理资源和文件操作的实用方法。
- **Configurable & ConfigurableFile**: 提供对底层 `FileConfiguration` 易于访问的接口和类。
- **ConfigurableUnit**: 表示配置单元的接口，对于在配置中处理权限或组非常有用。
- **Mappable, SectionMappable, UnitMappable & HashMappable**: 一组接口和类，用于将配置部分和单元映射到 Java 集合。
- **YAMLUpdater**: 一个类，更新 YAML 文件，通过合并默认值并保留注释。
---
## 主要特性
- **统一的配置管理**:
提供一致的 API，用于读取、写入和更新 YAML 配置文件。
- **动态映射和转换**:
支持将配置部分映射到自定义单元和集合，从而更容易地处理复杂的配置结构。
- **资源和文件实用工具**:
包括帮助类，用于简化文件加载、资源保存和目录管理。
- **注释保留和更新**:
YAMLUpdater 处理合并默认配置值，同时保留现有注释。
- **基于反射的解析**:
使用反射动态访问配置部分和值，确保跨服务器版本的兼容性。
---
## 用法示例
以下是一个示例，演示如何使用 YAML API 加载、更新和处理配置文件。
### 示例：使用 ConfigurableFile 和 YAMLFile
```java
package com.example.myplugin;
import me.croabeast.file.ConfigurableFile;
import me.croabeast.file.YAMLFile;
import org.bukkit.configuration.file.FileConfiguration;
import org.bukkit.plugin.java.JavaPlugin;
import java.io.IOException;
public class MyPlugin extends JavaPlugin {
private ConfigurableFile config;
@Override
public void onEnable() {
try {
// 创建一个新的配置文件，位于 "config" 文件夹中
config = new ConfigurableFile(this, "config", "settings")
// 可选地，覆盖方法来控制可更新性或其他行为
{
@Override
public boolean isUpdatable() {
// 从配置中检索“update”键以确定是否允许更新
return get("update", false);
}
};
// 如果不存在，则保存默认配置
config.saveDefaults();
// 更新配置文件（合并默认值并保留注释）
config.update();
} catch (IOException e) {
e.printStackTrace();
}
// 访问配置值
String prefix = config.get("lang-prefix", "&e MyPlugin »&7");
getLogger().info("语言前缀: " + prefix);
}
}
```
### 示例：使用 Mappable 和 SectionMappable
```java
package com.example.myplugin;
import me.croabeast.file.SectionMappable;
import me.croabeast.file.ConfigurableFile;
import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.plugin.java.JavaPlugin;
public class MyPlugin extends JavaPlugin {
private ConfigurableFile config;
@Override
public void onEnable() {
try {
config = new ConfigurableFile(this, "config", "settings");
config.saveDefaults();
config.update();
} catch (Exception e) {
e.printStackTrace();
}
// 假设我们有一个名为“advancements”的配置部分
ConfigurationSection section = config.getConfiguration().getConfigurationSection("advancements");
if (section != null) {
// 从配置部分创建一个 SectionMappable
SectionMappable.Set sectionMap = SectionMappable.asSet(section.getValues(false));
// 根据需要处理映射的配置
getLogger().info("加载的成就: " + sectionMap);
}
}
}
```
---
## Maven / Gradle 安装
要将 YAML API 添加到项目中，请将以下仓库和依赖项添加到您的构建配置中。将 `${version}` 替换为所需的版本标签。
### Maven
将仓库和依赖项添加到您的 `pom.xml`：
```xml
croabeast-repo
https://croabeast.github.io/repo/
me.croabeast
YAML-API
${version}
compile
```
### Gradle
将仓库和依赖项添加到您的 `build.gradle`：
```groovy
repositories {
maven {
url "https://croabeast.github.io/repo/"
}
}
dependencies {
implementation "me.croabeast:YAML-API:${version}"
}
```
将 `${version}` 替换为适当的模块版本。
---
## 结论
**YAML API** 是一个强大的库，用于管理 Bukkit/Spigot/Paper 插件中的 YAML 配置。它简化了文件操作，映射和更新，同时保留注释并确保跨服务器版本的兼容性。无论您是构建简单的配置系统还是处理复杂的嵌套设置，YAML API 都为您提供了有效地管理插件配置所需的工具。
祝您编码愉快！
— *CroaBeast*
