ApricityUI

ApricityUI

使用 HTML + CSS + JS 构建 UI。语法尽可能遵循 Web 标准。

概览

ApricityUI 围绕一个目标打造：创建一个易上手、便捷且功能广泛的 UI 框架。因此，它以经典的 HTML + CSS + JS 三件套为核心。

目前，JS 部分依赖 KubeJS（可选），这意味着整合包作者只需很低的学习成本，就能绘制自己想要的任意 UI。
门槛有多低？你甚至可以让 AI 为你生成所有与 ApricityUI 相关的内容。Web 框架足够普及，AI 对它们也很熟悉——生成的效果甚至可能比你亲手绘制的更好，而且你仍然看得懂。

需要自定义 UI 的模组也可以依赖 ApricityUI，构建高度可扩展的界面；JS 和 Java API 的功能基本相当。
这种可扩展性体现在哪里？嵌套遮罩、平滑滚动、圆角边框、磨砂玻璃背景、自定义动画、自定义字体、GIF 播放，甚至还能让滤镜、遮罩和阴影彼此嵌套。其他地方需要数百甚至数千行代码实现的功能，在这里只需几行。

ApricityUI 的语法基本固定，并尽可能贴近 Web 标准，因此你可以自由升级，也能跨游戏版本使用，无需担心兼容性问题。

从 1.2.5 版本开始，ApricityUI 还可以调用操作系统内置的 WebView，让你在游戏内嵌入真实的网站或网页，并且只接受硬件输入（也支持视频播放）。

如果你不确定什么是 Web 框架，至少记住它的三个广为人知的优点：

• 功能丰富，从简单的形状绘制到嵌套渲染效果都能实现——ApricityUI 甚至可以将内容渲染到世界中的方块上。
• 易于上手：我见过的大多数速成教程都不到三小时（最短的只有十分钟），而且 AI 对这套技术栈了如指掌。
• 易于调试：几乎所有内容都能即时热重载，便捷的开发工具还支持可视化调试。ApricityUI 两者兼备。

注意：ApricityUI 不捆绑 Chrome 运行时。它完全由 Java 从零构建；截至 1.2.4 版本，jar 文件仅有 2.5 MB，不会额外下载任何内容，使用安全。

展示

内置纯 CSS 主题

内置了 Ore 和 AE 主题，之后还会推出更多带有 Minecraft 风格（或刻意摒弃 Minecraft 风格）的通用主题。它们使用相同的 CSS 命名方案，因此切换主题十分顺畅。

• Limitless Vehicle 3D 打印机
  

• Auto Seam Blend 编辑器
  

随心所欲地绘制

它与 Minecraft 的渲染系统完全集成——你想在哪里绘制都可以。仅用 KubeJS 就足以自定义物品提示框和轮盘菜单。

• 东方足道屿物品提示框
  

• 简易轮盘菜单（由 SurpTalent 制作）
  

Canvas

Canvas 支持足以胜任图表、SVG 绘制、复杂的嵌套效果、涂鸦板等日常工作。

• Building Shop 股票市场
  
• Auto Seam Blend 绘图板
  

世界窗口

HTML 可以在世界中的指定位置渲染，并可配置角度、方块穿透、交互距离、视距、摄像机跟随、LOD 等细节。

• 东方足道屿 女仆足部按摩
  

• 生物生命值条与物品展示（作者：୧⍤⃝无月）
  

Minecraft 原生元素

以 HTML 方式管理容器槽位、物品、流体、纹理、模型、精灵动画、翻译键及其他原生元素。

• Building Shop 建筑材料商店
  

• Cobblemon Skin Manager（作者：卡杨巴）
  

富文本编辑器

可以通过数据驱动的方式构建富文本编辑器。

• 内置富文本编辑器示例
  

WebView

为了让不同模组的 UI 能够保持独立，同时又能彼此交互，ApricityUI 使用多文档架构。这使得 iframe 标签大多失去了用武之地，而且 Minecraft 很少需要嵌套界面——因此目前 ApricityUI 的 iframe 标签完全用于嵌入 WebView。

简单来说，使用 iframe 标签创建文档时，实际上会打开一个 WebView，并将其内容绘制到屏幕外的 iframe 区域中。

WebView 的缺点显而易见：无论通过 Java 还是 KubeJS，都很难找到优雅的方式与它进行逻辑交互，因此 ApricityUI 目前只会向其转发硬件输入。

它的内存占用较高，因此不适合用于覆盖层和世界窗口。

少数环境（例如 Linux）完全不附带 WebView，但这个模组绝不会内嵌 WebView。

它的优点是可以部分弥补 ApricityUI 对浏览器标准支持不完整的问题。它能够渲染与游戏关系不大的复杂网页，也可以直接打开外部网站——例如实时文档、更新日志、模组教程视频——还支持构建游戏内影院。

面向开发者

注意：所有文档和技能都内置于模块文件中，可直接使用 AI。

使用 ApricityUI 无需了解源代码。如有需要，可使用官方 Maven 仓库：

repositories {
    maven {
        url "https://maven.sighs.cc/repository/maven-public/"
    }
}
dependencies {
    implementation 'com.sighs:ApricityUI-forge-1.20.1:1.2.7'
}

使用 AI 开发 Web 应用非常简单——甚至不需要 SKILL，ApricityUI 也是如此。

举个简单的例子：用一句话就能生成一个界面。

不断生成随机设计，直到选中喜欢的方案，再基于静态模板进行调整，是一种高效的工作流程。

新生成的静态模板可以直接导入资源管理器并预览；图片、音频、字体等静态资源也都可以预览，右键菜单还提供快速引用功能。

为避免按键冲突，从 1.2.4 开始，资源管理器的快捷键默认不再绑定——调试前请自行绑定。

从 1.2.4 开始，jar 文件中已包含完整文档；配置文件还提供自动截图选项（最多保留 20 张），以及文件变更时立即重新加载对应界面的选项。这些功能都是为 AI 设计的。

在 AI 编程代理中，可以这样描述，让它不断迭代设计：

任务是创建或修改 UI；只能修改 HTML/CSS/JS。
请遵循随附文档中的指南。
已知：文件夹 run/screenshots/aui 每秒输出一张游戏截图；静态资源会自动监视，变更时触发重新加载。
测试流程：编辑 html/css/js 文件 -> 查看日志中的重新加载提示 -> 等待三秒，然后检查 screenshots 文件夹中的最新截图 -> 判断是否符合要求；如果不符合就继续修改，符合则停止。
目标 HTML 文件：run/apricity/test/quest.html
所需效果：游戏内任务列表，现代扁平风格，红白配色
参考图片：run/screenshots/image_614748742442633.png

完整的 SKILL 文档见官方文档，完整文档也已随 jar 文件打包。

在 Minecraft 中，复杂的 UI 需求并不常见。通常让 AI 阅读随附文档，就足以一次性完成大多数设计；搭配内置主题，效果已经很不错。

界面大致完成后，可以打开类似浏览器的调试工具——从 1.2.4 开始，这些工具也默认不绑定快捷键。

在 DevTools 中，你可以定位并选取页面元素，直接编辑样式和内容，并支持撤销与重做；之后可以保存样式或完整 DOM 内容。

不支持的功能、语法错误、内部异常等问题的日志，也会同步显示在 DevTools 控制台中。

你也可以从Codepen借用现成的样式。如果需要的 CSS 属性尚未支持，可以在 Github 上提交问题。

资源分发

ApricityUI 支持将 HTML、CSS、Javascript、TTF/OTF 字体以及包括 GIF 在内的大多数图片格式用作静态资源；音频和视频支持计划中。
资源存放在版本实例的 apricity 文件夹和资源包中。资源包的优先级较低，但默认全局样式和内置字体随模组自身资源提供。
对于整合包开发者，推荐将资源放在 apricity 文件夹中。热重载默认绑定到 END 键，通常不到一秒即可完成。

详情请参阅官方文档中的资源管理器章节。

如果你想打包并分享，资源包或普通压缩包都可以。由于资源包还需要重新加载游戏，因此推荐使用普通压缩包。
对于依赖 ApricityUI 的模组，资源包形式更合适：默认加载路径中包含优先级最高的开发资源包路径，使用起来非常方便。
另一种方式是使用网络资源，例如图床或开源静态托管网站。ApricityUI 支持异步加载网络资源——只要别用它做坏事就行。

ApricityUI 还提供了一种复古的“服务器向客户端发送 HTML 并进行渲染”的工作流，让你可以完全通过服务器管理客户端 UI。

想了解更多？

• ApricityUI 还实现了浏览器风格的缩放功能：在页面上按住 CTRL 并滚动滚轮即可放大或缩小，让玩家能够适应任意窗口尺寸。
• KubeJS 是可选前置库。不安装它就无法运行 HTML 中编写的 JavaScript，也无法使用控制台——不过对模组开发者来说这通常无关紧要，因为 DOM 操作可以用 Java 完成。
• 热重载速度很快：包含 20 个不同的 QQ 头像和 3 种自定义字体（包括内联 JS）时，重新加载整个文档也只需约一秒。如果你编写 KubeJS 客户端脚本，甚至可以用它来省些功夫——不过资源路径没有 PJS 补全。请注意，这种重载不会重新加载资源包。
• ApricityUI 在正常使用时没有明显的性能瓶颈，在 26.1 及更高版本中几乎无需担心性能问题。不过作者无法测试所有情况——如果你遇到突然卡顿，请立即反馈。
• Vue 和 Svelte 等现代前端框架的轻量级移植版正在积极开发中。kltyton 已经为一个简单的 Vue 版本提交了 PR，之后也会加入 Svelte。感兴趣的话，欢迎加入群聊！

展示

• win98
  

• Machine-Max 载具设置
  

• FindMe 同伴管理