# ratatui-cj

**Repository Path**: iJetLi/ratatui-cj

## Basic Information

- **Project Name**: ratatui-cj
- **Description**: rust ratatui库的仓颉实现
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ratatui-cj

Ratatui-cj (_ˌræ.təˈtu.i_) 是 [Ratatui](https://github.com/ratatui/ratatui) 的 [仓颉](https://cangjie-lang.cn/) 语言移植版——一个用于构建终端用户界面（TUI）的框架。它提供了一种简单灵活的方式在终端中创建基于文本的用户界面，可用于命令行应用、仪表盘和其他交互式控制台程序。

## 项目结构

本项目是一个 [cjpm](https://cangjie-lang.cn/docs/package/cjpm) 工作区，包含以下包：

| 包名 | 说明 |
|------|------|
| `ratatui_core` | 核心类型（`Rect`、`Frame` 等） |
| `ratatui_style` | 样式、颜色、修饰符 |
| `ratatui_symbols` | Unicode 符号和边框集 |
| `ratatui_text` | `Line`、`Span`、`Text` 类型 |
| `ratatui_buffer` | 终端缓冲区和单元格操作 |
| `ratatui_layout` | 布局引擎（`Layout`、`Constraint` 等） |
| `ratatui_backend` | 后端抽象（`Backend`、`TestBackend`） |
| `ratatui_widgets` | 内置组件（Block、Tabs、Paragraph、Table、Chart 等） |
| `ratatui_terminal` | 终端管理和渲染 |
| `ratatui_examples` | 示例应用 |

## 快速开始

### 前置条件

- [仓颉 SDK](https://cangjie-lang.cn/)（0.53+）
- cjpm 包管理器

### 构建

```shell
cjpm build
```

### 运行测试

```shell
cjpm test
```

### Hello World

```cangjie
package my_app

import ratatui_core.*
import ratatui_text.*
import ratatui_terminal.*
import ratatui_widgets.*
import ratatui_backend.*

public func renderApp(frame: Frame): Unit {
    let greeting = Paragraph.new(Text.raw("Hello World!"))
    frame.renderWidgetRef(greeting, frame.area())
}
```

## 组件

Ratatui-cj 提供以下内置组件：

- **Block** — 带边框、标题和内边距的容器
- **Paragraph** — 渲染文本，支持对齐和换行
- **Tabs** — 标签栏，支持自定义内边距、分隔符和高亮样式
- **Table** — 数据表格，支持行、列和表头
- **List** — 可滚动列表，支持高亮和选择
- **Chart** — 折线图和柱状图
- **Gauge** / **LineGauge** — 进度指示器
- **BarChart** — 柱状图可视化
- **Scrollbar** — 垂直和水平滚动条
- **Canvas** — 2D 绘图画布
- **Calendar** — 月历显示
- **Sparkline** — 迷你内联图表
- **Shadow** — 阴影效果
- **Clear** — 清除矩形区域

## 示例应用

`ratatui_examples` 包含多个示例应用：

### 应用示例

```shell
cjpm run --name ratatui_examples -- app-hello-world
cjpm run --name ratatui_examples -- app-minimal
cjpm run --name ratatui_examples -- app-demo
cjpm run --name ratatui_examples -- app-demo2
cjpm run --name ratatui_examples -- app-constraints
cjpm run --name ratatui_examples -- app-constraint-explorer
cjpm run --name ratatui_examples -- app-chart
cjpm run --name ratatui_examples -- app-canvas
cjpm run --name ratatui_examples -- app-calendar-explorer
cjpm run --name ratatui_examples -- app-color-explorer
cjpm run --name ratatui_examples -- app-colors-rgb
cjpm run --name ratatui_examples -- app-custom-widget
cjpm run --name ratatui_examples -- app-flex
cjpm run --name ratatui_examples -- app-gauge
cjpm run --name ratatui_examples -- app-hyperlink
cjpm run --name ratatui_examples -- app-inline
cjpm run --name ratatui_examples -- app-input-form
cjpm run --name ratatui_examples -- app-modifiers
cjpm run --name ratatui_examples -- app-mouse-drawing
cjpm run --name ratatui_examples -- app-panic
cjpm run --name ratatui_examples -- app-popup
cjpm run --name ratatui_examples -- app-release-header
cjpm run --name ratatui_examples -- app-scrollbar
cjpm run --name ratatui_examples -- app-table
cjpm run --name ratatui_examples -- app-todo-list
cjpm run --name ratatui_examples -- app-tracing
cjpm run --name ratatui_examples -- app-user-input
cjpm run --name ratatui_examples -- app-weather
cjpm run --name ratatui_examples -- app-widget-ref-container
cjpm run --name ratatui_examples -- app-advanced-widget-impl
cjpm run --name ratatui_examples -- app-volatility-surface
```

### 组件示例

```shell
cjpm run --name ratatui_examples -- widget-block
cjpm run --name ratatui_examples -- widget-barchart
cjpm run --name ratatui_examples -- widget-barchart-grouped
cjpm run --name ratatui_examples -- widget-calendar
cjpm run --name ratatui_examples -- widget-canvas
cjpm run --name ratatui_examples -- widget-chart
cjpm run --name ratatui_examples -- widget-collapsed-borders
cjpm run --name ratatui_examples -- widget-gauge
cjpm run --name ratatui_examples -- widget-line-gauge
cjpm run --name ratatui_examples -- widget-list
cjpm run --name ratatui_examples -- widget-logo
cjpm run --name ratatui_examples -- widget-paragraph
cjpm run --name ratatui_examples -- widget-scrollbar
cjpm run --name ratatui_examples -- widget-shadow
cjpm run --name ratatui_examples -- widget-sparkline
cjpm run --name ratatui_examples -- widget-table
cjpm run --name ratatui_examples -- widget-tabs
```

## 与 Rust 版本的差异

本项目是对 Rust [Ratatui](https://github.com/ratatui/ratatui) 库的忠实移植，针对仓颉语言和生态做了适配：

- **包管理**：使用 `cjpm` 代替 `cargo`
- **命名规范**：方法使用 `camelCase`（仓颉规范）而非 `snake_case`（Rust 规范）
- **错误处理**：使用 `Option<T>` 和异常代替 `Result<T, E>`
- **Unicode 宽度**：使用仓颉 `unicode_width` 包（0.1.0）
- **终端后端**：使用 `crossterm` 仓颉移植版进行终端操作

## 致谢

本项目移植自 [Ratatui](https://github.com/ratatui/ratatui)，而 Ratatui 是从 [tui-rs](https://crates.io/crates/tui) 分叉而来。特别感谢 Ratatui 的贡献者以及最初创建 tui-rs 的 Florian Dehau。

## 许可证

本项目基于 [MIT 许可证](./LICENSE) 开源。