Terminal.Gui UI Catalog 技术解析与使用指南

Terminal.Gui UI Catalog 技术解析与使用指南

Terminal.Gui Cross Platform Terminal UI toolkit for .NET 项目地址: https://gitcode.com/gh_mirrors/te/Terminal.Gui

概述

Terminal.Gui 是一个强大的.NET控制台用户界面框架，而UI Catalog则是其官方提供的综合性示例库。这个库不仅展示了Terminal.Gui的各种功能和概念，还为开发者提供了可直接参考的实现代码。

UI Catalog的设计目标

1. 功能展示：直观呈现Terminal.Gui的核心功能与高级特性
2. 代码示例：提供标准化的实现范例，帮助开发者快速上手
3. 可扩展性：采用模块化设计，便于开发者贡献新的示例场景

为什么需要UI Catalog

传统的demo.cs示例文件存在明显局限性：

• 功能展示不够系统化
• 缺乏详细的概念解释
• 单文件结构不利于协作开发

UI Catalog通过场景(Scenario)的模块化设计，完美解决了这些问题。

核心架构解析

场景(Scenario)机制

UI Catalog的核心是场景机制，每个功能示例都是一个独立的场景类，继承自基类Scenario。这种设计带来以下优势：

1. 隔离性：每个场景独立运行，互不干扰
2. 可发现性：通过分类系统方便查找
3. 一致性：统一的基础设施和运行环境

运行流程

1. 主程序通过反射动态加载所有场景
2. 用户选择场景后，框架会：
   • 初始化Terminal.Gui环境
   • 创建基础窗口
   • 调用场景的Setup方法

使用指南

基本使用方式

可以通过两种方式运行UI Catalog：

1. 交互式运行：

   dotnet run
   

   启动后通过UI选择场景

2. 直接运行指定场景：

   UICatalog.exe Buttons
   

场景导航

主界面分为两个区域：

• 左侧：场景分类列表
• 右侧：当前分类下的场景列表

支持的操作：

• 回车键：运行选中场景
• 双击：运行场景
• ESC键：退出当前场景

开发新场景指南

基础步骤

1. 在Scenarios目录下创建新类
2. 继承Scenario基类
3. 添加必要的元数据属性
4. 实现Setup方法

代码模板

[ScenarioMetadata(Name: "示例名称", Description: "功能描述")]
[ScenarioCategory("控件分类")]
class CustomScenario : Scenario 
{
    public override void Setup()
    {
        // 在这里添加你的控件和逻辑
        Win.Add(new Button() {
            Text = "点击测试",
            X = Pos.Center(),
            Y = Pos.Center(),
            Clicked = () => MessageBox.Query(20, 7, "提示", "操作成功?", "是", "否")
        });
    }
}

高级开发技巧

1. 自定义初始化：重写Init方法
2. 完全控制：重写Run方法
3. 使用原生API：直接访问Application.Top
4. 添加辅助窗口：通过Win属性添加子窗口

最佳实践

1. 命名规范：场景名称应简洁明了
2. 注释说明：详细解释场景的用途和实现
3. 分类合理：选择最贴切的现有分类
4. 错误处理：考虑边界情况和异常处理

调试技巧

1. 使用Debug.WriteLine输出调试信息
2. 通过Application.RequestStop优雅退出
3. 利用Pos和Dim类进行精确定位
4. 测试不同终端尺寸下的显示效果

应用场景

UI Catalog不仅适合学习Terminal.Gui，还可用于：

• 快速验证UI设计想法
• 测试特定终端环境下的兼容性
• 作为项目模板快速开发新功能
• 创建可交互的API文档

通过掌握UI Catalog的使用和扩展方法，开发者可以更高效地构建基于Terminal.Gui的控制台应用程序。

Terminal.Gui Cross Platform Terminal UI toolkit for .NET 项目地址: https://gitcode.com/gh_mirrors/te/Terminal.Gui