Skip to content

Latest commit

 

History

History

gui

README.md

GUI 模块文档

GUI 是新一代的 Minecraft 插件 GUI 开发框架，基于现代化的架构设计，提供强大而灵活的用户界面开发能力。与 Core 模块深度集成，原生支持 i18n 国际化和 MiniMessage/Legacy 格式解析。

🌟 核心特性

🌐 原生 i18n 支持

GUI 模块与 Core 的 Message 模块深度集成，支持：

  • 直接使用 i18n 模板：name("<%gui.button.confirm%>") 而不是 name(plugin.messager.sprintf("<%gui.button.confirm%>"))
  • 自动格式解析：支持 MiniMessage 和 Legacy 格式的自动识别和转换
  • 统一的文本处理：所有文本都通过 GuiManager 的 textPreprocessor 处理

🏗️ 现代化架构

  • Session系统：类似浏览器的会话管理，支持页面栈和导航
  • 组件化设计：可复用的UI组件，支持复杂布局
  • 事件冒泡：从item到component到page的事件传播机制
  • 生命周期管理：自动资源管理，防止内存泄漏

🔧 丰富的组件

  • SingleSlotComponent：单槽组件，最基础的UI元素
  • RectFillComponent：矩形填充组件，填充矩形区域
  • BorderFillComponent：边框填充组件，专门用于创建边框装饰
  • PatternFillComponent：模式填充组件，基于字符模式的布局
  • PaginatedComponent：统一分页组件，支持有限分页和无限滚动
  • ScrollableComponent：滚动组件，支持垂直滚动
  • StorageComponent：存储组件，允许物品操作

📊 强大的数据处理

  • DataProvider系统：统一的数据提供器接口
  • 自动模式识别：根据数据特性自动选择有限/无限分页
  • 多种缓存策略：单页、多页、激进缓存
  • 异步数据加载：支持本地数据和远程API
  • 加载状态管理：友好的加载中和错误状态显示

📚 文档导航

🚀 快速开始

📖 教程指南

📚 API参考

📋 开发指南

🎯 示例代码

📖 完整导航

🚀 快速预览

创建简单GUI（展示i18n集成）

class MyPlugin : BasePlugin() {
    override fun onPluginEnable() {
        // 使用推荐的openPage方法创建GUI
        openPage(InventoryType.CHEST, 27, player) {
            // 直接使用i18n模板，支持MiniMessage和Legacy格式
            title("<%gui.example.title%>")

            // 添加按钮
            slotComponent(x = 4, y = 2) {
                render {
                    item(Material.EMERALD) {
                        // 直接使用i18n模板，无需手动sprintf
                        name("<%gui.button.confirm%>")
                        lore("<%gui.button.confirm_hint%>")
                    }
                }
                onLeftClick {
                    // 需要参数替换时仍使用messager
                    player.sendMessage(plugin.messager.sprintf("<%gui.message.confirmed%>", player.name))
                    this@openPage.close() // 关闭页面
                }
            }
        }
    }
}

i18n语言文件示例

# lang/zh_CN.yml
gui:
  example:
    title: "<green>示例GUI</green>"
  button:
    confirm: "<green>确认</green>"
    confirm_hint: "<gray>点击确认操作</gray>"
  message:
    confirmed: "<green>{0} 已确认操作！</green>"

📦 依赖要求

  • Minecraft: 1.20.1+
  • Java: 17+
  • Core模块: 必需（提供基础功能）
  • Paper: 推荐（更好的性能和API支持）

🚀 开始使用

  1. 快速上手：阅读 快速入门 在5分钟内创建第一个GUI
  2. 理解概念：学习 核心概念 掌握设计理念
  3. 跟随教程：按顺序完成 教程指南 中的内容
  4. 查阅参考：使用 API文档 查找具体接口
  5. 学习示例：参考 示例代码 了解最佳实践

🔗 相关链接

💡 获取帮助

开始你的GUI模块开发之旅吧！ 🎉