# Box3EasyGUI

**Repository Path**: box3/box3easygui

## Basic Information

- **Project Name**: Box3EasyGUI
- **Description**: Box3EasyGUI是一款开源的box3简易gui管理工具
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2023-07-02
- **Last Updated**: 2025-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Box3EasyGUI.js
## 简介
Box3EasyGUI.js是box3的一款简易的gui管理框架，通过采用js操控元素，旨在抛开繁琐的xml代码，实现对用户的gui进行交互和控制。
## 安装和使用
在地图的代码中新建一个名为Box3EasyGUI.js的文件。并在主代码index.js中输入以下代码进行导入：
```javascript
//导入Box3EasyGUI
const {Box3EasyGUI} = require("./Box3EasyGUI.js");
```
接下来，将下载的Box3EasyGUI.js（[下载链接](https://gitee.com/box3/box3easygui/blob/master/index.js)）的代码复制到地图中的Box3EasyGUI.js文件中。此时，Box3EasyGUI已经在你的地图安装完成了，把这段代码粘贴到主代码试试吧：
```javascript
const { Box3EasyGUI } = require("./Box3EasyGUI.js");          //导入Box3EasyGUI.js
console.clear();
world.onPlayerJoin(async ({ entity }) => {
    var mygui = new Box3EasyGUI("myGUI", entity);
    entity.gui = mygui;           //创建一个gui对象
    var dom = mygui.document;
    var x = dom.createXml("label", {
        height: 20,
        width: 100,
        color: "#fff",
        fontSize: 18,
        x: 10,
        y: 35,
        id:"x"
    });                                                     //创建元素
    var y = dom.createXml("label", {
        height: 20,
        width: 100,
        color: "#fff",
        fontSize: 18,
        x: 10,
        y: 60,
        id:"y"
    });                                                     //创建元素
    var z = dom.createXml("label", {
        height: 20,
        width: 100,
        color: "#fff",
        fontSize: 18,
        x: 10,
        y: 85,
        id:"z"
    });                                                     //创建元素
    var group = dom.createXml("group", {
        width: 240,
        height: 170,
        borderColor: "rgba(0,0,0,0)",
        backgroundColor: "rgba(0,0,0,0.45)",
        right:20,
        top:50
    }).appendChild(dom.createXml("label", {
        height: 20,
        width: 100,
        color: "#fff",
        fontSize: 20,
        x: 10,
        y: 10,
        text: "玩家坐标"
    })).appendChild(x).appendChild(y).appendChild(z);         //将创建好的元素插入group中     
    dom.appendChild(group);                                  //将元素插入document中
    mygui.render();                                            //渲染gui
    //创建按钮
    var button = dom.createXml("button",{
        text:"记录",
        x:10,
        y:120,
        percentWidth:90,
        height:30,
        color:"#fa0"
    });
    //添加事件处理
    button.addEventListener("click",function({entity:e}){
        e.player.directMessage(e.position);
    })
    group.appendChild(button);                                   //插入按钮
    mygui.reload();                             //刷新
});
//循环显示玩家坐标
world.onTick(()=>{
    world.querySelectorAll('player').forEach((e)=>{
        if(e.gui){
            let dom = e.gui.document;
            let x = dom.getElementById("x");
            let y = dom.getElementById("y");
            let z = dom.getElementById("z");
            x.setAttribute("text","x："+Math.floor(e.position.x));  //设置元素文本
            y.setAttribute("text","y："+Math.floor(e.position.y));
            z.setAttribute("text","z："+Math.floor(e.position.z));
        }
    })
})
```
## 文档
### · Class Box3EasyGUI
在Box3EasyGUI.js中，我们使用Box3EasyGUI类来创建一个gui对象：
```javascript
var gui = new Box3EasyGUI("myGUI",entity);//创建gui对象
```
其中，第一个参数是gui的名称，第二个参数是要添加gui的玩家实体对象。
#### · render
Box3EasyGUI中，render方法用于渲染用户的gui：
```javascript
gui.render();         //渲染gui
```
#### · reload
reload方法用于重新渲染gui，在对元素进行插入等修改时，可以通过此方法进行重新渲染：
```javascript
gui.reload();        //刷新gui
```
### · Box3EasyGUI.document
document是Box3EasyGUI的文档对象，是特殊的元素对象，我们通过在文档中操控元素来控制用户的gui，类似于浏览器js中的document对象。下面，将介绍document常用的几个方法。
#### · createXml
创建一个xml元素。<br/>
参数：name, attributes<br/>
返回值：GUINode
```javascript
gui.document.createXml("label",{
    text:"Hello,world",
    height:20,
    width:100,
    x:100,
    y:50,
    color:"#fff",
    id:"label",
    name:"hi"
})
```
#### · getElementById
获取制定id的元素，仅限定该文档的范围。<br/>
参数：id<br/>
返回值：GUINode<br/>
```javascript
//广播该元素的内容
world.say(gui.document.getElementById("label"));
```
#### · getElementsByName
获取所有指定名称的元素，仅限定该文档范围。</br>
参数：name<br/>
返回值：GUINode[]
```javascript
//获取第一个名称为hi的元素
var x = gui.document.getElementsByName("hi")[0];
```
### Class GUINode
GUINode是Box3EasyGUI中的元素对象，Box3EasyGUI中将使用元素对象来操控用户的显示。<br/>
下面，将介绍几个常用的方法和属性：
#### · attributes
类型：Array<br/>
元素的所有属性，该属性是一个数组。
#### · appendChild
向元素中插入新的子元素，该方法将会返回新的元素对象。<br/>
参数：node<br/>
返回值：GUINode
#### · addEventListener
为元素添加事件侦听处理。<br/>
参数：event,listener<br/>
```javascript
//点击元素广播玩家的名称
element.addEventListener("click",function({entity}){
    world.say(entity.player.name);
})
```
#### · setAttribute
设置元素的属性。该方法用于动态修改元素属性，相对gui.reload，效率更高。<br/>
参数：a,b<br/>
```javascript
element.setAttribute("text","Hello,world");
```
#### · removeAttribute
删除元素属性。该方法可以动态删除元素的属性。<br/>
参数：a<br/>
```javascript
element.removeAttribute("text");
```
#### · show
该方法用于显示元素。
#### · hide
该方法用于隐藏元素。<br/>
<br/>
本人能力有限，代码可能有所欠缺，请各位大佬多多指教。<br/>
如有问题，也请大家指出。