UI渲染 (_ui)

此文档描述了 SCE-Universe_Java_Edition 项目中用于控制台界面的 UI 渲染系统。该系统提供了一套基于文本的 UI 组件，支持颜色高亮和结构化内容展示，以实现命令行应用程序的用户交互。

概述

_ui UI 渲染系统是一个轻量级的、自定义的控制台用户界面框架。它允许应用程序开发者以结构化的方式定义和显示文本内容，包括标题、正文、提示、列表、选项和用户输入字段。通过使用 ANSI 转义码，该系统能够在支持此功能的终端中渲染带颜色的文本，从而提升用户体验和信息的可读性。

该系统的核心在于将 UI 内容抽象为 Tiles 对象列表，并在渲染前对这些 Tiles 进行预处理，最终按顺序将它们打印到控制台。它专注于提供一种简单而有效的方式来构建和管理控制台应用程序的视觉输出和基本输入处理。

架构

UI 渲染系统主要由以下核心组件构成：

加载图表中...

Source:

UI_core.java

ui_header.java

Tiles.java

type.java

Color.java

rgb.java

fmt.java

组件说明:

ui_header: 抽象基类，定义了 UI 渲染系统的核心接口和一些共享的静态状态（如 article 列表）。
UI_core: ui_header 的具体实现类，包含了创建、处理和渲染 UI 元素的所有业务逻辑。它是应用程序与 UI 渲染系统交互的主要入口。
Tiles: UI 元素的基本单元，封装了元素的类型 (type)、文本内容 (textContent) 和颜色 (rgb)。所有要显示在控制台的内容都首先被转换为 Tiles 对象。
type: 包含了用于标识 Tiles 对象类型的常量（如 TEXT, TITLE, HINT 等）。
Color: 提供了一组预定义的 rgb 颜色常量，方便开发者使用标准颜色。
fmt 包: 包含 rgb 和 fmt 类，负责实际的控制台文本格式化和输出。rgb 类将 RGB 值转换为 ANSI 转义码，fmt 类则使用这些转义码打印带颜色的文本。
控制台 (Console): UI 内容的最终输出目的地和用户输入来源。
操作系统 (OS): UI_core 通过调用 cls() 方法与操作系统交互，实现控制台清屏功能。

主要功能与实现

UI 渲染系统的核心功能围绕着 Tiles 列表的构建、预处理和最终渲染。

UI 元素构建

UI_core 提供了多种 insert 方法，用于向内部维护的 List<Tiles> article 中添加不同类型的 UI 元素。article 是一个静态列表，存储了所有待渲染的 UI 元素。

java

public class UI_core extends ui_header {
    // ...
    public void insertTitle(String textContent,rgb color){
        ensureArticle();
        article.add(new Tiles(type.TITLE,textContent,color));
        if(isBuild)isBuild = false;
    }
    public void insertText(String textContent){
        ensureArticle();
        article.add(new Tiles(type.TEXT,textContent,Color.DEFAULT));
        if(isBuild)isBuild = false;
    }
    public void insertHint(String textContent){
        ensureArticle();
        article.add(new Tiles(type.HINT,textContent,Color.GREEN));
        if(isBuild)isBuild=false;
    }
    public void insertInput(boolean isPause){
        ensureArticle();
        if(!isPause){
            article.add(new Tiles(type.INPUT,"# ",Color.YELLOW));
        }
        else {
            article.add(new Tiles(type.INPUT,"按下回车继续...",Color.YELLOW));
        }
        if (isBuild)isBuild=false;
    }
    public void insertOption(String textContent,int index){
        ensureArticle();
        String fullOption = "[" + String.valueOf(index) + "]" + textContent;
        article.add(new Tiles(type.OPTION,fullOption,Color.DEFAULT));
        if(isBuild)isBuild= false;
    }
    // ...
}

Source: UI_core.java

UI 内容预处理 (`build()` 方法)

在内容被渲染到控制台之前，build() 方法会对 article 列表中的 Tiles 进行一次预处理。这个过程会根据 Tiles 的类型添加额外的格式化元素，例如为标题添加下划线、为列表项添加序号、为提示信息添加特殊符号等。

java

public boolean build(){
    int index =0;
    ensureArticle();
    if(!isBuild){
        ListIterator<Tiles> it = article.listIterator();
        if(buildLine !=0){
            buildLine++;
        }
        // ... (跳过已构建的行)
        while(it.hasNext()){
            Tiles t =it.next();
            try{
                switch(t.type){
                    case type.TITLE:
                        it.add(new Tiles(type.NEWLINE,""));
                        Tiles prev = it.previous(); // 回到 NEWLINE 前的 TITLE
                        int len = prev.textContent.length();
                        it.next(); // 回到 NEWLINE 后
                        it.add(new Tiles(type.TEXT, "-".repeat(len))); // 插入标题下划线
                        it.add(new Tiles(type.NEWLINE,""));
                        buildLine +=3;
                        break;
                    case type.LIST:
                        // ... 插入列表前缀
                        break;
                    case type.HINT:
                        // ... 添加提示符号
                        break;
                    case type.TEXT:
                    case type.OPTION:
                        it.add(new Tiles(type.NEWLINE,"")); // 文本和选项后添加换行
                        buildLine +=2;
                        break;
                    // ... 其他类型处理
                }
            } catch(Exception e) {
                System.out.println("UI.build ：未知错误");
            }
        }
    }
    isBuild =true;
    return true;
}

Source: UI_core.java

UI 内容渲染 (`run()` 方法)

run() 方法是实际执行 UI 渲染的核心。它首先确保 article 列表已经经过 build() 方法的预处理，然后遍历列表中的每个 Tiles 对象，并根据其类型和颜色将其打印到控制台。

java

public boolean run() throws Exception
{
    ensureArticle();
    if (isBuild)
    {
        return true;
    }
    if (!build())
    {
        throw(new Exception("ui::run ：构建失败"));
    }
    for (var it : article)
    {
        switch (it.type)
        {
            case type.TITLE:
            case type.TEXT:
            case type.HINT:
            case type.LIST:
            case type.OPTION:
            case type.INPUT:
            case type.SPAN:
            case type.OPTION_WITHOUT_NEWLINE:
                post(it.textContent, it.color); // 调用 post 方法打印带颜色文本
                break;
            case type.NEWLINE:
                System.out.println(); // 打印换行
                break;
            default:
                throw(new Exception("ui.run ：不存在的类型"));
        }
    }
    return true;
}

protected void post(String textContent,rgb color)
{
    // print without newline; run() will handle newlines and NEWLINE tiles
    fmt.print(fmt.fg(color), "{}", textContent);
};

Source: UI_core.java, UI_core.java

颜色和格式化 (`fmt` 包)

fmt 包负责将颜色信息转换为终端可识别的 ANSI 转义码，并进行实际的控制台输出。 rgb 类将 R、G、B 值转换为 \033[38;2;R;G;Bm 格式的 24 位真彩色 ANSI 序列。 fmt.print 方法接收这个颜色控制字符串和文本内容，打印到 System.out，并在文本结束后使用 \033[0m 重置终端颜色。

java

// src/cn/oraclestar/sce/system/UI/fmt/rgb.java
public class rgb {
    public int R=0;
    public int G=0;
    public int B=0;
    public rgb(int R,int G, int B){
        this.R = R;
        this.G = G;
        this.B = B;
    };
    @Override
    public String toString(){
        return "\033[38;2;"+String.valueOf(R)+";"+String.valueOf(G)+";"+String.valueOf(B)+"m";   
    }
}

Source: rgb.java

java

// src/cn/oraclestar/sce/system/UI/fmt/fmt.java
public class fmt {
    public static void print(String Controllor,String format,String text){
        // use print (no automatic newline) to avoid duplicate blank lines;
        // caller (post/display) decides when to print newline.
        System.out.print(Controllor + text);
        System.out.print("\033[0m"); // Reset color
    };
    // ...
}

Source: fmt.java

核心流程

以下序列图展示了 UI 渲染系统从内容插入到最终在控制台显示的完整生命周期。

加载图表中...

Source:

UI_core.java

ui_header.java

fmt.java

使用示例

创建并渲染一个简单的页面

java

// 假设这是应用程序中的某个页面逻辑
package cn.oraclestar.sce.system.pages;

import cn.oraclestar.sce.system.UI.UI_core;
import cn.oraclestar.sce.system.UI.Color;

public class main {
    public void showWelcomePage() throws Exception {
        UI_core ui = new UI_core(); // 或通过其他方式获取 UI_core 实例
        ui.cls(); // 清屏

        ui.insertTitle("欢迎来到 SCE-Universe", Color.YELLOW);
        ui.insertNewLine();
        ui.insertText("这是一个基于控制台的应用程序。", Color.DEFAULT);
        ui.insertHint("请选择一个选项继续。", Color.GREEN);
        ui.insertNewLine();
        ui.insertOption("开始游戏", 1, Color.BLUE);
        ui.insertOption("查看设置", 2, Color.DEFAULT);
        ui.insertOption("退出", 3, Color.RED);
        ui.insertNewLine();
        ui.insertInput(false, Color.YELLOW); // 提示用户输入
        
        ui.run(); // 渲染所有添加的 UI 元素

        String input = ui.getUserInput();
        System.out.println("您输入了: " + input); // 处理用户输入
        
        ui.reset(); // 清空当前页面内容以便下一次渲染
    }
}

Source: main.java (示例代码基于对该文件和 UI_core 的理解创建，部分代码结构参考了 UI_core 的用法)

清屏功能

cls() 方法用于清除控制台屏幕，提供更清晰的 UI 体验。它会自动检测操作系统类型。

java

public static void cls(){
    try{
        String os = System.getProperty("os.name").toLowerCase();
        if(os.contains("win")){
            new ProcessBuilder("cmd","/c","cls").inheritIO().start().waitFor();
        } else {
            new ProcessBuilder("clear").inheritIO().start().waitFor();
        } 
    }catch (Exception e){
        e.printStackTrace();
    };
};

Source: ui_header.java

API 参考

`UI_core` 类

`insertTitle(String textContent, rgb color)`

插入一个标题文本。标题在渲染时会自动在其下方生成一条与标题等长的分隔线。 参数:

textContent (String): 标题的文本内容。
color (rgb): 标题的颜色。

`insertText(String textContent)`

插入一段普通文本，使用默认颜色。 参数:

textContent (String): 文本内容。

`insertHint(String textContent, rgb color)`

插入一段提示信息。提示信息在渲染时会以特殊符号（如 ×, !, -, +）包裹。 参数:

textContent (String): 提示文本内容。
color (rgb): 提示文本的颜色。特定颜色（红、黄、绿）会对应不同的提示符号。

`insertInput(boolean isPause, rgb color)`

插入一个用户输入提示或暂停提示。 参数:

isPause (boolean): 如果为 true，则显示 "按下回车继续..."，否则显示 "# " 作为输入提示。
color (rgb): 提示文本的颜色。

`insertOption(String textContent, int index, rgb color)`

插入一个带编号的选项。 参数:

textContent (String): 选项的文本内容。
index (int): 选项的编号，显示为 [index]。
color (rgb): 选项文本的颜色。

`insertNewLine()`

插入一个新行。

`run()`

处理并渲染所有已插入的 UI 元素到控制台。 返回: boolean - 如果成功渲染则为 true。 抛出: Exception - 如果构建或渲染过程中发生错误。

`getUserInput()`

从控制台读取用户的单行输入。 返回: String - 用户输入的文本。

`erase(int line)`

擦除 article 列表中指定行号的 UI 元素。 参数:

line (int): 要擦除的 UI 元素在列表中的索引。 抛出: Exception - 如果行号超出范围。

`reset()` (静态方法)

清除所有已插入的 UI 元素，重置内部状态，为新的页面渲染做准备。

`cls()` (静态方法)

清除控制台屏幕。

`Tiles` 类

Tiles 类是 UI 元素的内部表示，通常不直接由外部调用。 字段:

public int type: UI 元素的类型，对应 type 类中的常量。
public String textContent: 元素的文本内容。
public rgb color: 元素的颜色。

`type` 类

定义了 Tiles 元素的常量类型：TEXT, HINT, TITLE, LIST, NEWLINE, OPTION, INPUT, SPAN, OPTION_WITHOUT_NEWLINE。

`Color` 类

提供了预定义的 rgb 颜色常量，例如 Color.RED, Color.GREEN, Color.YELLOW, Color.DEFAULT 等。

`rgb` 类

表示一个 RGB 颜色值。 构造函数:

rgb(int R, int G, int B): 创建一个指定 R、G、B 值的颜色对象。 方法:
toString(): 返回对应的 ANSI 24 位真彩色转义码字符串。

UI渲染 (_ui)

概述

架构

主要功能与实现

UI 元素构建

UI 内容预处理 (`build()` 方法)

UI 内容渲染 (`run()` 方法)

颜色和格式化 (`fmt` 包)

核心流程

使用示例

创建并渲染一个简单的页面

清屏功能

API 参考

`UI_core` 类

`insertTitle(String textContent, rgb color)`

`insertText(String textContent)`

`insertHint(String textContent, rgb color)`

`insertInput(boolean isPause, rgb color)`

`insertOption(String textContent, int index, rgb color)`

`insertNewLine()`

`run()`

`getUserInput()`

`erase(int line)`

`reset()` (静态方法)

`cls()` (静态方法)

`Tiles` 类

`type` 类

`Color` 类

`rgb` 类

相关链接

Sources

On this page

UI渲染 (_ui)

概述

架构

主要功能与实现

UI 元素构建

UI 内容预处理 (build() 方法)

UI 内容渲染 (run() 方法)

颜色和格式化 (fmt 包)

核心流程

使用示例

创建并渲染一个简单的页面

清屏功能

API 参考

UI_core 类

insertTitle(String textContent, rgb color)

insertText(String textContent)

insertHint(String textContent, rgb color)

insertInput(boolean isPause, rgb color)

insertOption(String textContent, int index, rgb color)

insertNewLine()

run()

getUserInput()

erase(int line)

reset() (静态方法)

cls() (静态方法)

Tiles 类

type 类

Color 类

rgb 类

相关链接

Sources

On this page

UI 内容预处理 (`build()` 方法)

UI 内容渲染 (`run()` 方法)

颜色和格式化 (`fmt` 包)

`UI_core` 类

`insertTitle(String textContent, rgb color)`

`insertText(String textContent)`

`insertHint(String textContent, rgb color)`

`insertInput(boolean isPause, rgb color)`

`insertOption(String textContent, int index, rgb color)`

`insertNewLine()`

`run()`

`getUserInput()`

`erase(int line)`

`reset()` (静态方法)

`cls()` (静态方法)

`Tiles` 类

`type` 类

`Color` 类

`rgb` 类