yhy/AuOnlineReward
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 修正使用说明md文件

Browse Source
This commit is contained in:
yhy
2026-06-02 16:39:36 +08:00
parent 3dd0e0a27d
commit 161fc0d0ed
2 changed files with 0 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
使用手册.md → README.md
View File

459
使用手册案例.md
View File

@@ -1,459 +0,0 @@
<<<<<<< HEAD
# 1.LangUtil 是什么？
LangUtil 是一个 Minecraft 1.12.2 Bukkit / Spigot 多语言管理插件。
它的作用不是替代业务插件，而是给其他插件提供统一的语言 API：
- 每个插件维护自己的语言文件
- 玩家可以切换自己的语言
- 不同玩家可以看到不同语言
- 修改语言文件后可以不重启服务器直接重载
- 支持物品名称、物品 lore、普通消息、占位符和颜色代码
简单理解：
```yml
LangUtil = 公共语言管理器
其他插件 = 自己提供 lang 文件
玩家 = 自己选择 zh_CN / en_US 等语言
```
------
# 2.目录结构
## LangUtil 自己的数据
玩家语言选择会保存到：
```yml
plugins/LangUtil/player-language.yml
```
格式示例：
```yml
player-language:
550e8400-e29b-41d4-a716-446655440000: zh_CN
```
## 其他插件的语言文件
其他插件必须把语言文件放在自己的插件目录下：
```yml
plugins/OtherPlugin/lang/zh_CN.yml
plugins/OtherPlugin/lang/en_US.yml
```
注意：
```yml
语言文件不是放在 LangUtil 的 lang 目录
语言文件是放在调用 register 的插件自己的 lang 目录
```
------
# 3.其他插件如何注册？
其他插件需要依赖 LangUtil。
## plugin.yml
```yml
depend:
- LangUtil
```
## 插件入口
```java
import com.io.yaohun.langutil.LangUtil;
import org.bukkit.plugin.java.JavaPlugin;
public final class OtherPlugin extends JavaPlugin {
@Override
public void onEnable() {
LangUtil.register(this);
}
}
```
当执行：
```java
LangUtil.register(this);
```
LangUtil 会读取：
```yml
plugins/OtherPlugin/lang/*.yml
```
------
# 4.语言文件怎么写？
## zh_CN.yml
```yml
message:
reload: "&a语言文件已重载"
no-permission: "&c你没有权限使用该命令。"
item:
flame-sword:
name: "&c烈焰长剑"
lore:
- "&7伤害: &c{damage}"
- "&7品质: &6{quality}"
- ""
- "&e右键释放火焰"
```
## en_US.yml
```yml
message:
reload: "&aLanguage files reloaded"
no-permission: "&cYou do not have permission."
item:
flame-sword:
name: "&cFlame Sword"
lore:
- "&7Damage: &c{damage}"
- "&7Quality: &6{quality}"
- ""
- "&eRight-click to release fire"
```
文件名就是语言 ID：
```yml
zh_CN.yml → zh_CN
en_US.yml → en_US
```
------
# 5.玩家命令
## 查看可用语言
```yml
/lang
```
玩家会看到当前已经加载的语言 ID。
## 切换语言
```yml
/lang zh_CN
/lang en_US
```
切换后会按玩家 UUID 保存。
玩家退出服务器再进入，仍然保持上次选择。
## 重载语言文件
```yml
/lang reload
```
修改语言文件后，不需要重启服务器，执行该命令即可重新读取所有已注册插件的语言文件。
控制台也可以执行：
```yml
lang reload
```
------
# 6.权限节点
```yml
langutil.use # 允许玩家使用 /lang 查看和切换语言
langutil.reload # 允许使用 /lang reload
```
推荐配置：
```yml
普通玩家: langutil.use
管理员: langutil.use + langutil.reload
```
------
# 7.API 调用
## 获取普通消息
```java
String message = LangUtil.get(player, this, "message.reload");
```
## 发送普通消息
```java
LangUtil.send(player, this, "message.reload");
```
## 发送消息并播放音效
```java
LangUtil.send(player, this, "message.reload", Sound.LEVEL_UP);
```
## 使用占位符
```java
Map<String, String> placeholders = new HashMap<String, String>();
placeholders.put("damage", "12");
placeholders.put("quality", "史诗");
String name = LangUtil.get(player, this, "item.flame-sword.name", placeholders);
```
语言文件：
```yml
item:
flame-sword:
name: "&c烈焰长剑"
```
结果：
```yml
烈焰长剑
```
------
# 8.物品 name 和 lore 怎么做？
物品 name 是字符串，可以用：
```java
LangUtil.get(player, this, "item.flame-sword.name", placeholders);
```
物品 lore 是 List，可以用：
```java
LangUtil.getList(player, this, "item.flame-sword.lore", placeholders);
```
完整示例：
```java
Map<String, String> placeholders = new HashMap<String, String>();
placeholders.put("damage", "12");
placeholders.put("quality", "史诗");
ItemMeta meta = item.getItemMeta();
meta.setDisplayName(LangUtil.get(player, this, "item.flame-sword.name", placeholders));
meta.setLore(LangUtil.getList(player, this, "item.flame-sword.lore", placeholders));
item.setItemMeta(meta);
```
------
# 9.推荐封装方式
为了让业务代码更短，其他插件可以自己封装一个 `Lang` 工具类。
```java
public final class Lang {
private static JavaPlugin plugin;
private Lang() {
}
public static void init(JavaPlugin javaPlugin) {
plugin = javaPlugin;
LangUtil.register(javaPlugin);
}
public static void send(CommandSender sender, String path) {
LangUtil.send(sender, plugin, path);
}
public static String get(CommandSender sender, String path) {
return LangUtil.get(sender, plugin, path);
}
public static List<String> getList(CommandSender sender, String path) {
return LangUtil.getList(sender, plugin, path);
}
}
```
插件启动时：
```java
Lang.init(this);
```
业务代码：
```java
Lang.send(player, "message.reload");
```
------
# 10.重载机制说明
LangUtil 不会每次发送消息都读取本地 YAML。
语言文件读取时机：
```yml
插件启动 register 时
/lang reload 时
再次调用 register 时
```
平时调用：
```java
LangUtil.get(...)
LangUtil.getList(...)
LangUtil.send(...)
```
都是从内存缓存读取。
这样可以避免每次发消息都读磁盘，降低主线程压力。
------
# 11.异常与回退规则
## 玩家没有选择语言
默认使用：
```yml
zh_CN
```
## 玩家选择的语言文件不存在
回退：
```yml
zh_CN
```
## zh_CN 也不存在
返回 path 原文：
```java
LangUtil.get(player, this, "message.not-found");
```
返回：
```yml
message.not-found
```
## lore 不存在
返回单行 List：
```yml
- item.xxx.lore
```
## YAML 格式错误
控制台会输出：
```yml
插件名
语言文件名
错误原因
```
不会因为单个语言文件错误导致服务器关闭。
------
# 12.实战使用流程
## 第一步：安装 LangUtil
把插件放入服务器：
```yml
plugins/LangUtil-1.2.0.jar
```
启动服务器。
## 第二步：业务插件依赖 LangUtil
```yml
depend:
- LangUtil
```
## 第三步：业务插件注册语言文件
```java
LangUtil.register(this);
```
## 第四步：创建语言文件
```yml
plugins/OtherPlugin/lang/zh_CN.yml
plugins/OtherPlugin/lang/en_US.yml
```
## 第五步：玩家切换语言
```yml
/lang zh_CN
/lang en_US
```
## 第六步：业务插件发送消息
```java
LangUtil.send(player, this, "message.reload");
```
## 第七步：修改语言后重载
```yml
/lang reload
```
------
# 13.注意事项
- 推荐始终使用带 `JavaPlugin plugin` 参数的 API。
- 不推荐使用 `LangUtil.get(String path)`，因为它无法稳定判断读取哪个插件的语言。
- 其他插件必须先调用 `LangUtil.register(this)`，否则读取不到自己的语言文件。
- 语言文件必须放在调用注册方法的插件自己的 `lang` 目录。
- 物品 lore 必须用 YAML List 格式编写。
- 修改语言文件后必须执行 `/lang reload` 才会进入缓存。
=======
# LangUtil
>>>>>>> 12c7b3f43c6113b170b9e83dedf75650d51b9040