Skip to content

label

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

label

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
assets/shaders
assets/shaders
 
 
CMakeLists.txt
CMakeLists.txt
 
 
README.md
README.md
 
 
label.cpp
label.cpp
 
 

README.md

🏷️ Label Component - 标签组件

状态：✅ 已完成
难度：⭐
代码行数：~280 行

📋 组件概述

Label（标签）组件是最基础的文本显示组件，用于渲染静态或动态文本。支持多种对齐方式、字体大小、颜色和背景样式，是构建 UI 界面的基础元素。

核心功能

  • ✅ 文本对齐：左对齐、居中对齐、右对齐
  • ✅ 字体大小：支持任意字体大小（8px - 28px+）
  • ✅ 自定义颜色：支持 RGBA 颜色
  • ✅ 背景样式：可选的背景矩形
  • ✅ 多标签：同时显示多个独立标签
  • ✅ 简单布局：基于坐标的精确定位

🎨 视觉效果

对齐方式演示

左对齐：
  LEFT ALIGNED:
  THIS IS A SAMPLE
  ANOTHER LINE

居中对齐：
      CENTER ALIGNED:
       CENTERED TEXT

右对齐：
              RIGHT ALIGNED:
           ALIGNED TO RIGHT

颜色和背景

  • 白色文字 + 蓝色背景：标题效果
  • 灰色文字：副标题和说明文本
  • 黄色文字：强调和分类标签
  • 青色文字：节标题
  • 粉色文字：特殊提示
  • 绿色文字 + 深绿背景：小尺寸文本示例

🔧 技术实现

1. Label 数据结构

struct Label {
    const char* text;        // 文本内容
    float x;                 // X 坐标
    float y;                 // Y 坐标
    float size;              // 字体大小
    float color[4];          // 文字颜色 (RGBA)
    float bgColor[4];        // 背景颜色 (RGBA)
    bool hasBackground;      // 是否显示背景
    Alignment align;         // 对齐方式
    float width;             // 标签宽度（用于背景）
};

2. 对齐方式

enum class Alignment {
    LEFT,       // 左对齐：x 是文本起始位置
    CENTER,     // 居中：x 是文本中心位置
    RIGHT       // 右对齐：x 是文本结束位置
};

3. 文本宽度估算

// 估算文本宽度
float charWidth = size * 0.6f;       // 字符宽度系数
float spacing = size * 0.15f;        // 字符间距
float estimatedWidth = textLength * (charWidth + spacing);

4. 对齐实现

switch (align) {
    case Alignment::LEFT:
        textX = x;                           // 左对齐
        break;
    case Alignment::CENTER:
        textX = x - estimatedWidth * 0.5f;   // 居中
        break;
    case Alignment::RIGHT:
        textX = x - estimatedWidth;          // 右对齐
        break;
}

5. 背景绘制

if (hasBackground) {
    float bgX = textX - padding;
    float bgY = textY - padding;
    float bgW = estimatedWidth + padding * 2;
    float bgH = size + padding * 2;
    renderer->drawRectangle(bgX, bgY, bgW, bgH, bgColor);
}

📝 使用示例

基本用法

// 创建左对齐标签
labels[0] = {
    "LEFT TEXT",
    -200.0f, 0.0f,              // 左上角坐标
    14.0f,                       // 字体大小
    {1.0f, 1.0f, 1.0f, 1.0f},   // 白色文字
    {0.0f, 0.0f, 0.0f, 0.0f},   // 无背景
    false,
    Alignment::LEFT,
    200.0f
};

// 创建居中标签（带背景）
labels[1] = {
    "CENTERED TEXT",
    0.0f, 0.0f,                  // 屏幕中心
    20.0f,                       // 较大字体
    {1.0f, 1.0f, 1.0f, 1.0f},   // 白色文字
    {0.2f, 0.3f, 0.5f, 1.0f},   // 蓝色背景
    true,                        // 显示背景
    Alignment::CENTER,
    300.0f
};

// 创建右对齐标签
labels[2] = {
    "RIGHT TEXT",
    200.0f, 0.0f,                // 右上角坐标
    12.0f,                       // 字体大小
    {0.8f, 0.8f, 0.8f, 1.0f},   // 灰色文字
    {0.0f, 0.0f, 0.0f, 0.0f},   // 无背景
    false,
    Alignment::RIGHT,
    200.0f
};

绘制标签

void drawLabel(const Label& label) {
    // 1. 计算文本实际位置（根据对齐方式）
    float textX = calculateTextX(label);
    
    // 2. 绘制背景（如果需要）
    if (label.hasBackground) {
        drawBackground(label, textX);
    }
    
    // 3. 绘制文本
    renderer->drawText(label.text, textX, label.y, 
                      label.color, label.size);
}

🎮 交互控制

按键 功能
Space 暂停/继续动画
R 重置时间
ESC 退出程序

显示信息

  • 左上角：标签数量和运行时间
  • 右上角：暂停状态指示
  • 底部：操作提示

💡 设计特点

1. 简单易用

  • 声明式配置
  • 最少的代码
  • 清晰的数据结构

2. 灵活布局

  • 支持三种对齐方式
  • 相对坐标定位
  • 独立的背景控制

3. 样式丰富

  • 任意字体大小
  • 自定义颜色
  • 可选背景矩形

4. 性能优良

  • 纯 CPU 计算
  • 无复杂算法
  • 高效渲染

📚 学习要点

1. 文本渲染

// 使用 drawText API
renderer->drawText(
    "Hello",           // 文本
    100.0f, 50.0f,    // 位置
    color,            // 颜色
    16.0f             // 大小
);

2. 对齐算法

  • 左对齐：直接使用 X 坐标
  • 居中：X - 宽度/2
  • 右对齐：X - 宽度

3. 背景处理

  • 先绘制背景矩形
  • 再绘制文本
  • 添加适当的内边距

4. 颜色管理

float white[4] = {1.0f, 1.0f, 1.0f, 1.0f};
float blue[4] = {0.2f, 0.3f, 0.5f, 1.0f};
float transparent[4] = {0.0f, 0.0f, 0.0f, 0.0f};

🔄 扩展建议

短期扩展

  1. 自动换行：支持固定宽度的文本换行
  2. 文本截断：超长文本添加省略号
  3. 动画效果：淡入淡出、滚动等
  4. 阴影效果：文字阴影或描边

长期扩展

  1. 富文本：支持颜色标记、粗体、斜体
  2. 垂直对齐：顶部、中部、底部对齐
  3. 可编辑：点击编辑文本内容
  4. 图标支持：文本前后添加图标

📊 性能指标

指标 数值
标签数量 10 个
绘制调用 ~12 次/帧
FPS ~240
内存占用 <100 KB
CPU 使用 <2%

⚠️ 注意事项

  1. ✅ 简单位图字体系统，支持基本字符
  2. ✅ 坐标系统相对于屏幕中心
  3. ✅ 文本宽度为估算值，可能不完全准确
  4. ✅ 背景宽度可手动指定以获得更好效果
  5. ✅ 不支持多行文本自动换行（需手动创建多个标签）

🗂️ 文件结构

label/
├── label.cpp                    # 主要实现（~280 行）
├── CMakeLists.txt              # 构建配置
├── assets/
│   └── shaders/
│       ├── triangle.vert       # 顶点着色器（共享）
│       ├── triangle.frag       # 片段着色器（共享）
│       └── spv/
│           ├── triangle_vert.spv
│           └── triangle_frag.spv
└── README.md                   # 本文档

🚀 快速开始

编译

cd examples/cpp/label
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

运行

cd native
.\build\Release\bitui_native.exe .\build\Release\label.dll

测试要点

  • ✅ 检查三种对齐方式是否正确
  • ✅ 验证不同字体大小的显示
  • ✅ 确认背景矩形正确绘制
  • ✅ 测试键盘交互（Space, R, ESC）
  • ✅ 观察暂停/继续功能

🎓 适用场景

基础应用

  • 静态文本显示
  • 标题和副标题
  • 提示信息
  • 状态显示

UI 组件

  • 按钮文本
  • 菜单项文本
  • 工具提示
  • 标签页标题

数据显示

  • 统计数据
  • 实时信息
  • 调试输出
  • 性能指标

🤝 相关组件

  • Text：更高级的文本渲染（动画、效果）
  • Button：可点击的标签
  • Tooltip：悬停提示标签
  • Badge：小型标记标签

📖 API 依赖

API 说明 状态
drawText() 文本渲染 ✅ 已实现
drawRectangle() 矩形背景 ✅ 已实现
setClearColor() 设置背景色 ✅ 已实现
IInput 键盘输入 ✅ 已实现
IWindow 窗口控制 ✅ 已实现

维护者：Bit Project 团队
最后更新：2025-10-12
版本：v1.0.0