ConsoleLib

一个用 C++ 编写的跨平台控制台操作库。

ConsoleLib 提供 Windows / Linux 下的控制台初始化、原始键盘输入、后台按键轮询、ANSI 真彩色输出、清屏和毫秒级休眠等功能，并同时产出静态库和动态库。

特性

• 控制台原始模式 / 原生模式初始化与恢复
• 后台键盘输入线程，轮询并记录按键
• 24 位 ANSI 真彩色输出
• 清屏
• 毫秒级跨平台休眠 sleep_ms
• 安全的 quit 退出
• 同时生成静态库和动态库

平台产物

平台	静态库	动态库
Linux	libConsoleLib.a	libConsoleLib.so
Windows	ConsoleLib.lib	ConsoleLib.dll

环境要求

• CMake 3.10+（使用 CMakePresets.json 时建议 3.28+）
• 支持 C++17 的编译器（Clang / GCC / MSVC）
• 使用默认 preset 时需要 Ninja

目录结构

ConsoleLib/
├── CMakeLists.txt
├── CMakePresets.json
├── ConsoleLib.cpp
├── include/
│   └── ConsoleLib.h
├── example/
│   ├── CMakeLists.txt
│   ├── CMakePresets.json
│   ├── build.sh
│   ├── build.bat
│   ├── helloworld/
│   │   ├── CMakeLists.txt
│   │   └── main.cpp
│   └── keyinput/
│       ├── CMakeLists.txt
│       └── main.cpp
└── docs/
    └── image.png

快速开始

方式一：使用 CMake Presets（推荐）

# 项目根目录
./build.sh

等价命令：

cmake --preset Clang
cmake --build --preset Clang -j

构建产物默认在 build/。

Windows 下可运行：

build.bat

方式二：手动构建

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j

单独构建示例

cd example
./build.sh

或：

cd example
cmake --preset Clang
cmake --build --preset Clang -j
./build/helloworld/helloworld
./build/keyinput/keyinput

示例

HelloWorld

example/helloworld/main.cpp：

#include <ConsoleLib.h>

using namespace ConsoleLib;

signed main() {
  initConsole();
  clearConsole();
  printToConsole("HelloWorld!\r\n");
  printToConsole("Red", 0xff0000);
  printToConsole("Green", 0x00ff00);
  printToConsole("Blue", 0x0000ff);
  quit(0);
}

输出效果见 docs/image.png。

按键输入（含方向键）

example/keyinput/main.cpp 展示了 getConsoleKeyInput() 与方向键、Home、End、F1 ~ F4 以及普通可打印字符的检测：

#include <ConsoleLib.h>

using namespace ConsoleLib;

signed main() {
  initConsole();
  clearConsole();
  printToConsole("Press arrow keys, q or ESC to quit.\r\n");

  while (true) {
    auto &keys = getConsoleKeyInput();

    if (keys[KEY_UP]) {
      printToConsole("UP\r\n");
    }
    if (keys[KEY_DOWN]) {
      printToConsole("DOWN\r\n");
    }
    if (keys[KEY_LEFT]) {
      printToConsole("LEFT\r\n");
    }
    if (keys[KEY_RIGHT]) {
      printToConsole("RIGHT\r\n");
    }

    if (keys[KEY_q] || keys[KEY_ESCAPE]) {
      break;
    }

    sleep_ms(16);
  }

  quit(0);
}

集成到你的项目

静态库

add_subdirectory(ConsoleLib)
target_link_libraries(your_target PRIVATE ConsoleLib)

动态库

add_subdirectory(ConsoleLib)
target_link_libraries(your_target PRIVATE ConsoleLib_shared)

ConsoleLib 目标已通过 target_include_directories(... PUBLIC ...) 暴露 include/ 目录，因此直接包含即可：

#include <ConsoleLib.h>

API 参考

函数	说明
void initConsole()	初始化控制台并启动后台输入线程
void stopInputThread()	停止后台输入线程
void restoreConsoleMode()	恢复终端原始模式 / Windows 控制台模式
void RawPrint(std::string_view text)	直接输出文本，不做颜色处理
void printToConsole(std::string_view data)	打印文本
void printToConsole(std::string_view data, Color color)	打印指定颜色的文本
void clearConsole()	清屏并将光标移动到左上角
char getinput()	读取一个输入字符
std::array<bool, KEYCODE_COUNT> &getConsoleKeyInput()	返回并清空按键状态表，下标为 Keycode
bool isKeyPressed(Keycode key)	查询某个按键当前是否被按下
void sleep_ms(unsigned int ms)	休眠指定毫秒数
void setInputFrequency(std::uint8_t frequency)	设置输入轮询频率（Hz）
std::uint8_t getInputFrequency()	获取当前输入轮询频率
void quit(int exitCode)	停止线程、恢复终端并退出进程

Color 为 uint32_t，格式为 0xRRGGBB。

按键码

Keycode 为 SDL 风格的按键码：

• ASCII 字符直接使用其 ASCII 值，例如 KEY_a、KEY_0、KEY_SPACE
• 特殊键从 128 开始，例如 KEY_UP、KEY_DOWN、KEY_LEFT、KEY_RIGHT、KEY_HOME、KEY_END、KEY_F1 ~ KEY_F4

常量	含义
ASCII_TABLE_SIZE	ASCII 范围大小，固定为 128
KEYCODE_COUNT	按键状态表大小
DEFAULT_CONSOLE_INPUT_FREQUENCY	默认输入轮询频率（50 Hz）

getConsoleKeyInput() 返回长度为 KEYCODE_COUNT 的 std::array<bool, KEYCODE_COUNT>，下标即 Keycode；调用后内部按键记录会被清空。isKeyPressed(Keycode) 仅查询、不会清空记录。

说明

• initConsole() 会将终端切换到非回显的原始模式；程序结束前请调用 quit() 或 restoreConsoleMode()，否则终端状态可能无法恢复。
• quit() 已包含 stopInputThread() 和 restoreConsoleMode()。
• getinput() 仅返回单个 ASCII 字符；方向键、功能键等特殊键请使用 getConsoleKeyInput() 或 isKeyPressed()。