chuan
54a71c1645
- add README and public API boundary documentation - configure package metadata and CI validation
52 lines
2.2 KiB
Markdown
52 lines
2.2 KiB
Markdown
# 公开 API 和内部边界
|
|
|
|
本文档用于说明 TinyTUI 当前可被应用代码依赖的公开边界，以及后续重构时应尽量保持稳定的区域。
|
|
|
|
## 应用侧稳定入口
|
|
|
|
应用代码优先依赖以下命名空间：
|
|
|
|
- `TinyTUI.Components`：组件接口和内置组件
|
|
- `TinyTUI.Runtime`：运行时入口和 overlay 操作
|
|
- `TinyTUI.Terminal`：真实终端会话
|
|
- `TinyTUI.Rendering`：渲染器和渲染选项
|
|
- `TinyTUI.Text`：ANSI 感知宽度、截断、切片和换行
|
|
- `TinyTUI.Input`：输入事件、按键名称和 keybinding
|
|
- `TinyTUI.Autocomplete`：自动补全 provider 契约
|
|
- `TinyTUI.Terminal.Images`：终端图像服务和能力检测
|
|
|
|
## 推荐组合
|
|
|
|
真实终端应用建议使用：
|
|
|
|
```csharp
|
|
using var terminal = new ConsoleTerminalSession();
|
|
var parser = new DefaultInputParser();
|
|
var textMeasurer = new TerminalTextMeasurer();
|
|
var renderer = new DifferentialRenderer(terminal, textMeasurer);
|
|
using var runtime = new TuiRuntime(terminal, parser, renderer);
|
|
```
|
|
|
|
测试或嵌入场景可以替换 `ITerminalSession`、`ITerminalOutput`、`IInputParser`、`IRenderer` 或 `ITextMeasurer`，但仍保持 runtime 和组件不直接写终端。
|
|
|
|
## 组件约束
|
|
|
|
组件只负责 `Render(int width)` 返回行数组，输入组件通过 `HandleInput(TuiInputEvent input)` 接收规范化输入事件。
|
|
|
|
组件不应该直接调用 `Console.Write` 或依赖真实终端尺寸。需要终端宽度时使用 render 传入的 `width`，需要截断或换行时使用 `ITextMeasurer`。
|
|
|
|
可缓存组件应该在 `Invalidate()` 中清理缓存。runtime 会在焦点切换、resize 和显式失效时调用该入口。
|
|
|
|
## 仍在演进的区域
|
|
|
|
以下能力已具备基础形态，但公开契约后续仍可能细化：
|
|
|
|
- Kitty keyboard protocol 的完整协商和 release 事件
|
|
- Runtime 级全局 input listener 和 keybinding 配置
|
|
- Overlay 多层焦点恢复和复杂样式 segment 保持
|
|
- Unicode RGI emoji 精确宽度和 CJK 标点断行
|
|
- 终端图像 cell size 查询、resize 重新布局和 Kitty image 生命周期同步
|
|
- 正式 benchmark 和多场景 Example 拆分
|
|
|
|
如果应用需要提前依赖这些能力，建议通过接口注入或封装适配层隔离变更。
|