HtmlCraft API

模组

· 作者 Yifei061004

一个 HTML/CSS 渲染引擎,为 Minecraft GUI 提供基于 Web 的界面构建能力。

0 本站下载 0 关注 更新于 3 个月前

最新 1.0.0-26.1.2fabric · 26.1.2 · Fabric

一键开服(送7天)

HtmlCraft API

适用于 Minecraft 1.20.1 Forge 的 HTML/CSS GUI 渲染引擎

简介

HtmlCraft API 是一个轻量级的 HTML/CSS 渲染引擎,将 Web 前端技术引入 Minecraft GUI 开发中。开发者无需学习复杂的 Minecraft GUI API(如 GuiGraphics、Widget、AbstractContainerScreen 等),只需编写 HTML + CSS 即可构建精美的游戏界面。


特性

特性 描述
HTML 解析 常用 HTML 标签、属性、嵌套结构、HTML 实体(命名/十进制/十六进制)
CSS 样式 类选择器、ID 选择器、标签选择器、内联样式
布局引擎 Block 布局、Flexbox、CSS Grid
视觉效果 线性渐变、圆角、阴影模拟、透明度
交互 按钮点击事件、鼠标滚轮滚动、命中测试
模板引擎 {{variable}} 替换、数据绑定上下文
线程安全 ConcurrentHashMap、CopyOnWriteArrayList

依赖要求

依赖项 版本
Minecraft 1.20.1
Forge 47.x
Java 17

安装

作为模组依赖

将 htmlcraftapi-1.0.0-1.20.1forge.jar 放入 mods 文件夹。

作为开发依赖

添加到你的 build.gradle:

dependencies {
    implementation files('libs/htmlcraftapi-1.0.0-1.20.1forge.jar')
}

快速入门

1. 通过 Builder 创建 Screen

import com.htmlcraft.api.HtmlRendererAPI;
import com.htmlcraft.api.binding.DataContext;
import com.htmlcraft.api.screen.HtmlScreen;
import net.minecraft.network.chat.Component;

DataContext data = new DataContext();
data.set("title", "My Interface");
data.set("content", "Hello, Minecraft!");

HtmlScreen screen = HtmlRendererAPI.createScreen(Component.literal("My Screen"))
    .html("<div class='container'>" +
          "  <h1>{{title}}</h1>" +
          "  <p>{{content}}</p>" +
          "  <button id='btn-ok'>OK</button>" +
          "</div>")
    .css(".container { padding: 20px; background: #1a1a2e; border-radius: 10px; }" +
         "h1 { color: #e94560; font-size: 16px; }" +
         "p { color: #ffffff; }" +
         "#btn-ok { background: #0f3460; color: #ffffff; border-radius: 6px; padding: 8px; }")
    .data(data)
    .onClick(event -> {
        if ("btn-ok".equals(event.element().getId())) {
            System.out.println("Player clicked the OK button");
        }
    })
    .build();

Minecraft.getInstance().setScreen(screen);

2. 继承 HtmlScreen 以创建自定义 Screen

public class MyScreen extends HtmlScreen {

    public MyScreen() {
        super(Component.literal("My Screen"));
    }

    @Override
    protected String getHtml() {
        return "<div class='root'>Custom content</div>";
    }

    @Override
    protected String getCss() {
        return ".root { padding: 16px; background: #2d2d44; }";
    }
}

核心 API

HtmlRendererAPI

提供用于创建 HTML Screen 的 Builder 模式的统一入口点。

方法 描述
createScreen(Component title) 创建一个 Screen 构建器

HtmlRendererAPI.Builder

用于配置 HTML、CSS、数据和事件的链式构建器。

方法 描述
html(String html) 设置 HTML 内容
css(String css) 设置 CSS 样式表
data(DataContext context) 设置模板数据上下文
onClick(Consumer<ClickEvent> handler) 设置点击事件回调
build() 构建 HtmlScreen 实例

HtmlScreen

抽象 HTML 渲染 Screen 基类,继承自 Minecraft Screen。

方法 描述
getHtml() 抽象方法,子类提供 HTML 内容
getCss() 重写以提供 CSS 样式
setClickHandler(Consumer<ClickEvent>) 设置点击事件处理程序
setPreferredSize(int w, int h) 设置内容区域大小(居中布局)
rebuild() 重建渲染管线(数据更改后刷新)
getRootLayout() 获取布局根节点
getPipeline() 获取渲染管线

HtmlScreen.ClickEvent

包含被点击元素和坐标的点击事件。

方法 描述
element() 被点击的 DOM 元素
button() 鼠标按键(0=左键,1=右键,2=中键)
x() / y() 点击坐标

DataContext

模板变量上下文,线程安全。

方法 描述
set(String key, Object value) 设置一个变量
get(String key) 获取一个变量
getString(String key) 获取字符串值
has(String key) 检查变量是否存在
clear() 清除所有变量

HtmlElement

DOM 元素节点。

方法 描述
tagName() 获取标签名称
getId() 获取 id 属性
hasClass(String) 检查是否包含指定类
getAttribute(String) 获取属性值
children() 获取子节点

支持的 CSS 属性

布局

属性 值
display block / flex / inline / grid / none
flex-direction row / column
justify-content flex-start / center / flex-end / space-between / space-around
align-items flex-start / center / flex-end / stretch
gap 像素值
grid-template-columns repeat(N, 1fr)

盒模型

属性 描述
width / height 像素值、auto
padding 像素值
margin 像素值
border-width 像素值

视觉效果

属性 值
background #RRGGBB / #AARRGGBB / #RRGGBBAA
background (渐变) linear-gradient(to bottom, #color1, #color2)
color 文本颜色
border-color 边框颜色
border-radius 圆角半径(像素)
box-shadow offsetX offsetY blur spread #color
opacity 0.0 - 1.0

文本

属性 值
font-size 像素值
text-align left / center / right

位置与溢出

属性 值
position static / relative / absolute / fixed
overflow-x / overflow-y visible / hidden / scroll / auto
z-index 整数

模板引擎

在 HTML 中使用 {{variable}} 占位符。它们在 init() 期间通过 TemplateEngine.render() 使用 DataContext 中的值进行替换。

DataContext data = new DataContext();
data.set("player_name", "Steve");
data.set("level", 30);

// HTML 模板
String html = "<div>Player: {{player_name}} | Level: {{level}}</div>";

特殊字符会自动转义为 HTML 实体以防止注入。


渲染管线

HTML String
    ↓
HtmlParser (解析为 DOM 树)
    ↓
StyleSheet + CssParser (加载 CSS 规则)
    ↓
StyleCalculator (计算每个元素的最终样式)
    ↓
LayoutEngine (执行布局,生成 LayoutNode 树)
    ↓
RenderPipeline (生成并执行渲染命令)
    ↓
GuiGraphics (绘制到 Minecraft 屏幕)

包结构

com.htmlcraft.api
├── HtmlCraftAPI.java          // Mod 主类
├── HtmlRendererAPI.java       // 公共入口点 + Builder
├── core/
│   ├── HtmlDocument.java      // HTML 文档
│   ├── HtmlElement.java       // DOM 元素节点
│   ├── HtmlNode.java          // DOM 节点接口
│   └── HtmlText.java          // DOM 文本节点
├── parser/
│   ├── HtmlParser.java        // HTML 解析器
│   └── CssParser.java         // CSS 解析器
├── style/
│   ├── StyleSheet.java        // CSS 样式表
│   ├── StyleCalculator.java   // 样式计算器
│   └── ComputedStyle.java     // 计算后的样式
├── layout/
│   ├── LayoutEngine.java      // 布局引擎
│   └── LayoutNode.java        // 布局节点
├── render/
│   ├── RenderPipeline.java    // 渲染管线
│   ├── RenderContext.java     // 渲染上下文
│   ├── RenderCommand.java     // 渲染命令接口
│   └── commands/              // 具体渲染命令
│       ├── FillRectCommand.java
│       ├── DrawTextCommand.java
│       ├── DrawBorderCommand.java
│       └── BlitTextureCommand.java
├── binding/
│   ├── DataContext.java       // 数据绑定上下文
│   └── TemplateEngine.java    // 模板引擎
└── screen/
    └── HtmlScreen.java        // HTML 渲染屏幕基类

点击事件

可点击的元素包括:

  • <button> 标签
  • <a> 标签
  • 带有 id 属性的任何元素

点击会触发 ClickEvent 回调。使用 event.element().getId() 来识别被点击的元素。


滚动支持

具有 overflow-y: scroll 或 overflow-y: auto 的元素会自动响应鼠标滚轮滚动。每次滚动步长移动 20 像素。


许可证

LGPL-2.1

作者

Yifei

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源