TUI应用开发教程完全由ai生成，所使用的提示词存放在：github.com/hhk-png/cyc… code。
可以直接查看 github.com/hhk-png/cyc… 来阅读全部的章节
文章封面来自：bing.ioliu.cn/。
第八章 流式响应与动画
8.1 TUI 中的动画基础
终端动画的核心原理是快速更新屏幕内容。利用 ANSI 转义码和 blessed 的渲染机制，我们可以实现丰富的动画效果。
8.1.1 简单动画示例
// 一个简单的字符旋转动画
const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
let i = 0;
const timer = setInterval(() => {
process.stdout.write(`\r${frames[i++ % frames.length]} 加载中...`);
}, 100);
// 3 秒后停止
setTimeout(() => {
clearInterval(timer);
process.stdout.write('\r✅ 完成! \n');
}, 3000);
关键点： \r（回车符）将光标移回行首，使下一帧覆盖当前行——这就是终端动画的核心机制。
8.1.2 终端动画 vs GUI 动画
| 维度 | GUI 动画 | TUI 动画 |
|---|---|---|
| 渲染方式 | 像素级重绘 | 字符级覆盖 |
| 帧率 | 60fps | 10-30fps（合理范围） |
| 资源消耗 | GPU 加速，高功耗 | CPU 轻量，几乎无 GPU |
| 实现复杂度 | 复杂（CSS/Canvas） | 简单（定时器 + 字符） |
| 动画能力 | 无限（渐变、3D） | 有限（旋转、进度、闪烁） |
8.2 打字机效果（流式文本输出）
打字机效果是大模型对话 TUI 中最核心的动画——文本逐字出现，模拟 LLM 的真实生成过程。
8.2.1 基础实现
/**
* 打字机效果：逐字更新 UI
* 每次调用更新完整文本（而非追加字符），确保 UI 一致性
*/
private updateAssistantMessage(content: string): void {
if (!this.currentAssistantMsgEl) {
// 首次创建消息元素
this.currentAssistantMsgEl = blessed.box({
parent: this.chatBox,
top: 0,
left: 0,
width: '100%-2',
height: 'shrink',
content: `{green-fg}{bold}🤖 AI{/bold}{/green-fg}\n${this.escapeTags(content)}`,
style: { fg: 'white', bg: '#1a1a1a' },
tags: true,
wrap: true,
shrink: true,
});
this.addSpacer();
} else {
// 增量更新：替换内容，保留元素引用
this.currentAssistantMsgEl.setContent(
`{green-fg}{bold}🤖 AI{/bold}{/green-fg}\n${this.escapeTags(content)}`
);
}
// 每次更新后自动滚动到底部
this.chatBox.setScrollPerc(100);
this.screen.render();
}
8.2.2 渲染性能优化
频繁调用 screen.render() 在字符密集时会有性能问题，以下是三种优化方案：
方案 1：节流渲染（Throttle）
private lastRenderTime = 0;
private readonly MIN_RENDER_INTERVAL = 33; // ~30fps
private throttledRender(): void {
const now = Date.now();
if (now - this.lastRenderTime >= this.MIN_RENDER_INTERVAL) {
this.screen.render();
this.lastRenderTime = now;
}
}
方案 2：批处理更新（Batch）
private batchTimeout: ReturnType<typeof setTimeout> | null = null;
private pendingContent = '';
private batchUpdate(chunk: string): void {
this.pendingContent += chunk;
if (!this.batchTimeout) {
this.batchTimeout = setTimeout(() => {
this.flushBatch();
}, 50); // 每 50ms 批量刷新一次
}
}
private flushBatch(): void {
if (this.pendingContent) {
this.updateAssistantMessage(this.pendingContent);
this.pendingContent = '';
}
this.batchTimeout = null;
}
方案 3：差分更新（利用 smartCSR）
// blessed 内置 smartCSR 自动处理差分更新
// 只需确保：
const screen = blessed.screen({
smartCSR: true, // 开启智能光标保存/恢复
fullUnicode: true, // 完整 Unicode 支持（emoji/CJK）
fastCSR: true, // 快速 CSR 模式
});
// 剩下的 blessed 会自动处理
8.2.3 流式文本的光标指示
流式输出中的光标（▊）能增强"正在生成中"的感知：
// 在流式文本末尾添加闪烁光标
private updateAssistantMessage(content: string): void {
// 在流式模式末尾添加光标指示器
const displayContent = this.state === 'streaming'
? content + '▊' // 使用半块字符作为光标
: content;
// ... 更新 UI
}
8.2.4 打字机效果变体
基础逐字输出虽然可用，但缺乏表现力。以下是多种打字机变体，可为不同场景选择合适节奏。
速度模式：加速、减速、波浪
type SpeedPattern = 'uniform' | 'accelerating' | 'decelerating' | 'wave';
/**
* 根据速度模式和总进度计算当前字符的延迟
* @param index 当前字符索引
* @param total 字符总数
* @param baseDelay 基础延迟 (ms)
* @param pattern 速度模式
*/
function getTypewriterDelay(
index: number,
total: number,
baseDelay: number,
pattern: SpeedPattern = 'uniform',
): number {
const progress = index / Math.max(total - 1, 1);
switch (pattern) {
case 'accelerating':
// 从慢到快：开头 2x 延迟，结尾 0.5x 延迟
return baseDelay * (2 - 1.5 * progress);
case 'decelerating':
// 从快到慢：开头 0.5x 延迟，结尾 2x 延迟
return baseDelay * (0.5 + 1.5 * progress);
case 'wave':
// 波浪节奏：快慢交替，模拟自然语言韵律
return baseDelay * (0.6 + 0.8 * Math.sin(progress * Math.PI * 4) ** 2);
case 'uniform':
default:
return baseDelay;
}
}
// 使用示例
async function* acceleratedTypewriter(text: string): AsyncGenerator<LLMEvent> {
for (let i = 0; i < text.length; i++) {
yield { type: 'text', content: text[i] };
const delay = getTypewriterDelay(i, text.length, 20, 'accelerating');
await delay(delay);
}
}
标点暂停
在句号、逗号、问号后插入更长的停顿，让阅读体验更自然：
const PUNCTUATION_PAUSE: Record<string, number> = {
'.': 200, // 句号 — 较长停顿
'!': 250, // 感叹号 — 强调停顿
'?': 250, // 问号 — 思考停顿
',': 120, // 逗号 — 短停顿
';': 120, // 分号 — 短停顿
':': 100, // 冒号 — 短暂停顿
'\n': 300, // 换行 — 段落停顿
};
async function* typewriterWithPunctuationPause(
text: string,
charDelay: number = 25,
): AsyncGenerator<LLMEvent> {
for (let i = 0; i < text.length; i++) {
const ch = text[i];
yield { type: 'text', content: ch };
const extraPause = PUNCTUATION_PAUSE[ch] ?? 0;
await delay(charDelay + extraPause);
}
}
逐词分块 vs 逐字分块
对比两种分块策略对用户体验的影响：
/**
* 逐词分块：每块包含一个或多个完整词语
* 优点：阅读流畅，语义完整
* 缺点：首字延迟较长
*/
async function* wordByWord(text: string): AsyncGenerator<LLMEvent> {
const words = text.split(/(\s+)/); // 保留空白分隔符
for (const word of words) {
if (word.length === 0) continue;
yield { type: 'text', content: word };
await delay(40 + Math.random() * 30);
}
}
/**
* 逐字分块：每次输出一个字符
* 优点：实时感强，模拟 LLM token 生成
* 缺点：阅读体验破碎
*/
async function* charByChar(text: string): AsyncGenerator<LLMEvent> {
for (const ch of text) {
yield { type: 'text', content: ch };
await delay(15 + Math.random() * 25);
}
}
/**
* 混合策略：短词逐词输出，长词逐字输出
* 平衡流畅度与实时感
*/
async function* hybridTypewriter(text: string): AsyncGenerator<LLMEvent> {
const words = text.split(/(\s+)/);
for (const word of words) {
if (word.length === 0) continue;
if (word.length <= 2) {
// 短词（2 字符以内）：整体输出
yield { type: 'text', content: word };
await delay(30 + Math.random() * 20);
} else {
// 长词：前几个字符快速逐字，最后整体
const fastChars = word.slice(0, -1);
for (const ch of fastChars) {
yield { type: 'text', content: ch };
await delay(10 + Math.random() * 15);
}
yield { type: 'text', content: word.slice(-1) };
await delay(30 + Math.random() * 30);
}
}
}
随机速度变化与种子控制
可复现的随机延迟变化，用于测试和一致体验：
/**
* 带种子的伪随机数生成器 (Mulberry32)
*/
function createSeededRandom(seed: number): () => number {
let s = seed | 0;
return () => {
s = (s + 0x6d2b79f5) | 0;
let t = Math.imul(s ^ (s >>> 15), 1 | s);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
async function* typewriterWithSeed(
text: string,
seed: number = 42,
minDelay: number = 10,
maxDelay: number = 40,
): AsyncGenerator<LLMEvent> {
const rng = createSeededRandom(seed);
for (const ch of text) {
yield { type: 'text', content: ch };
await delay(minDelay + rng() * (maxDelay - minDelay));
}
}
退格修正模拟
模拟人类输入时发现错误、删除并重新输入的效果：
async function* typewriterWithBackspace(
text: string,
mistakeProbability: number = 0.05,
): AsyncGenerator<LLMEvent> {
const backspaceChar = '\b'; // 使用退格序列
let buffer = '';
for (let i = 0; i < text.length; i++) {
const ch = text[i];
// 模拟输入错误
if (Math.random() < mistakeProbability) {
// 输入一个错误字符
const wrongChar = String.fromCharCode(
97 + Math.floor(Math.random() * 26)
);
yield { type: 'text', content: wrongChar };
await delay(80 + Math.random() * 60);
// 退格删除
yield { type: 'text', content: backspaceChar };
await delay(100 + Math.random() * 50);
// 重新输入正确字符
yield { type: 'text', content: ch };
await delay(60 + Math.random() * 40);
} else {
yield { type: 'text', content: ch };
await delay(15 + Math.random() * 35);
}
}
}
选择指南
| 变体 | 场景 | 推荐延迟 |
|---|---|---|
| 加速模式 | 代码生成（开头慢，后续快） | baseDelay 15-25ms |
| 减速模式 | 故事叙述（开头抓人，尾韵悠长） | baseDelay 20-30ms |
| 波浪模式 | 诗歌/歌词（韵律感） | baseDelay 15-20ms |
| 标点暂停 | 正式文档/对话 | charDelay 20-30ms |
| 逐词分块 | 长文本/翻译 | 每词 40-80ms |
| 混合策略 | 通用最佳体验 | 默认推荐 |
| 退格修正 | 模拟人类输入/教程演示 | mistakeProbability 0.03-0.08 |
8.3 Spinner 动画
Spinner 是 TUI 中最常见的"加载中"指示器，用于 AI 思考阶段。
8.3.1 字符序列大全
// 各种风格的 Spinner 序列
const SPINNER_SETS = {
// ── 旋转类 ──
dots: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
line: ['-', '\\', '|', '/'],
arc: ['◜', '◠', '◝', '◞', '◡', '◟'],
circle: ['◐', '◓', '◑', '◒'],
triangle: ['◢', '◣', '◤', '◥'],
// ── 弹跳类 ──
bounce: ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'],
// ── 时钟类 ──
clock: ['🕐', '🕑', '🕒', '🕓', '🕔', '🕕', '🕖', '🕗', '🕘', '🕙', '🕚', '🕛'],
// ── 条形类 ──
bar: ['▁', '▃', '▄', '▅', '▆', '▇', '█', '▇', '▆', '▅', '▄', '▃', '▁'],
// ── 方块类 ──
squares: ['▖', '▘', '▝', '▗'],
// ── 箭头类 ──
arrows: ['←', '↖', '↑', '↗', '→', '↘', '↓', '↙'],
};
8.3.2 在 blessed 中实现 Spinner
class Spinner {
private timer: ReturnType<typeof setInterval> | null = null;
private element: Widgets.BoxElement | null = null;
private frameIndex = 0;
private static readonly FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
constructor(
private parent: Widgets.BoxElement,
private screen: Widgets.Screen,
private frames: string[] = Spinner.FRAMES,
private interval: number = 100,
) {}
start(text: string = 'AI 思考中...'): void {
if (this.element) return; // 防止重复启动
this.element = blessed.box({
parent: this.parent,
top: 0, left: 0,
width: '100%-2', height: 1,
content: '',
style: { fg: 'yellow', bg: '#1a1a1a' },
tags: true,
});
this.frameIndex = 0;
this.timer = setInterval(() => {
if (!this.element) return;
this.frameIndex = (this.frameIndex + 1) % this.frames.length;
this.element.setContent(
` {yellow-fg}{bold}${this.frames[this.frameIndex]} ${text}{/bold}{/yellow-fg}`
);
this.screen.render();
}, this.interval);
this.parent.setScrollPerc(100);
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
if (this.element) {
this.parent.remove(this.element);
this.element = null;
this.screen.render();
}
}
setText(text: string): void {
if (this.element) {
this.element.setContent(
` {yellow-fg}{bold}${this.frames[this.frameIndex]} ${text}{/bold}{/yellow-fg}`
);
this.screen.render();
}
}
}
8.3.3 多种动画的组合流程
阶段 1: [思考中]
⠋ AI 思考中... ← Spinner 动画，持续旋转
⠙ AI 思考中...
⠹ AI 思考中...
... (每 100ms 更新)
阶段 2: [过渡]
Spinner 停止并移除
消息容器被创建（空）
阶段 3: [输出中]
🤖 AI
你好！有什么可以帮助 ← 打字机效果，逐字出现
你的吗？▊
... (每 20-50ms 追加)
阶段 4: [完成]
🤖 AI
你好！有什么可以帮助 ← 静态文本，光标消失
你的吗？
8.4 进度条动画
除了 Spinner，进度条是另一种常见的动画形式。
8.4.1 使用 blessed 内置进度条
const progressBar = blessed.progressbar({
parent: container,
top: 0, left: 0,
width: '100%-4', height: 1,
style: {
bar: { bg: 'green' },
filled: { bg: 'green' },
},
pch: '■', // 填充字符
value: 0, // 0-100
});
// 模拟进度
let progress = 0;
const timer = setInterval(() => {
progress += Math.random() * 10;
if (progress > 100) progress = 100;
progressBar.setProgress(progress);
screen.render();
if (progress >= 100) clearInterval(timer);
}, 200);
8.4.2 自定义进度条
function createCustomProgressBar(
screen: Widgets.Screen,
parent: Widgets.BoxElement,
label: string,
color: string,
width: number = 40
) {
const bar = blessed.box({
parent,
top: 0, left: 2,
width: width + 4, height: 3,
border: { type: 'line', fg: color },
label: ` ${label} `,
tags: true,
style: { fg: 'white', bg: 'black' },
});
return {
update(progress: number) {
const filled = Math.round((progress / 100) * width);
const empty = width - filled;
const pct = String(Math.round(progress)).padStart(3);
bar.setContent(
` {${color}-fg}{bold}${'▓'.repeat(filled)}{/bold}` +
`${'░'.repeat(empty)}{/${color}-fg} ${pct}%`
);
screen.render();
},
};
}
8.4.3 工具执行进度条
在工具调用场景中，进度条可以展示工具执行进度：
class ToolProgressBar {
private bar: ReturnType<typeof createCustomProgressBar>;
private statusText: Widgets.BoxElement;
constructor(
parent: Widgets.BoxElement,
screen: Widgets.Screen,
toolName: string,
) {
this.bar = createCustomProgressBar(screen, parent, ` ${toolName} `, 'cyan', 30);
this.statusText = blessed.box({
parent,
top: 0, left: 2,
width: '100%-4', height: 1,
content: '',
style: { fg: '#888888', bg: '#1a1a1a' },
});
}
update(progress: number, status: string): void {
this.bar.update(progress);
this.statusText.setContent(` ${status}`);
}
complete(result: string): void {
this.bar.update(100);
this.statusText.setContent(` {green-fg}✅ ${result}{/green-fg}`);
}
error(err: string): void {
this.bar.update(0);
this.statusText.setContent(` {red-fg}❌ ${err}{/red-fg}`);
}
}
8.5 LLM 流式协议详解
大模型 API 使用多种流式传输协议。理解这些协议有助于设计更好的 TUI 交互。
8.5.1 Server-Sent Events (SSE)
SSE 是大多数 LLM API（OpenAI、Anthropic）使用的标准流式协议：
GET /v1/messages HTTP/1.1
Accept: text/event-stream
← data: {"type": "content_block_delta", "delta": {"text": "你好"}}
← data: {"type": "content_block_delta", "delta": {"text": "！"}}
← data: {"type": "content_block_stop"}
← data: [DONE]
/**
* 解析 SSE 流
*/
async function* parseSSE<T>(
response: Response,
): AsyncGenerator<T> {
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() || ''; // 保留未完成的行
for (const line of lines) {
if (line.startsWith('data: ')) {
const data = line.slice(6);
if (data === '[DONE]') return;
try {
yield JSON.parse(data) as T;
} catch {
// 忽略解析错误
}
}
}
}
}
8.5.2 Anthropic Stream Events
Anthropic API 的事件类型更丰富，适合 TUI 展示：
type AnthropicStreamEvent =
| { type: 'message_start'; message: { id: string; model: string } }
| { type: 'content_block_start'; index: number; content_block: { type: string } }
| { type: 'content_block_delta'; index: number; delta: { type: string; text?: string } }
| { type: 'content_block_stop'; index: number }
| { type: 'message_delta'; delta: { stop_reason: string }; usage: { output_tokens: number } }
| { type: 'message_stop' }
| { type: 'ping' };
/**
* 将 Anthropic 流事件转换为统一 LLMEvent
*/
async function* anthropicToLLMEvent(
stream: AsyncGenerator<AnthropicStreamEvent>,
): AsyncGenerator<LLMEvent> {
for await (const event of stream) {
switch (event.type) {
case 'message_start':
yield { type: 'thinking' };
break;
case 'content_block_delta':
if (event.delta.type === 'text_delta' && event.delta.text) {
yield { type: 'text', content: event.delta.text };
}
break;
case 'message_delta':
yield { type: 'meta', tokens: event.usage?.output_tokens };
break;
case 'message_stop':
yield { type: 'done' };
break;
}
}
}
8.5.3 OpenAI Chat Completion Chunks
type OpenAIChunk = {
id: string;
choices: Array<{
delta: {
content?: string;
tool_calls?: Array<{
index: number;
id?: string;
function?: { name?: string; arguments?: string };
}>;
};
finish_reason: string | null;
}>;
};
async function* openaiToLLMEvent(
stream: AsyncGenerator<OpenAIChunk>,
): AsyncGenerator<LLMEvent> {
for await (const chunk of stream) {
const choice = chunk.choices[0];
if (!choice) continue;
const delta = choice.delta;
if (delta.content) {
yield { type: 'text', content: delta.content };
}
if (delta.tool_calls) {
for (const tool of delta.tool_calls) {
if (tool.function?.name) {
yield {
type: 'tool_call',
name: tool.function.name,
args: tool.function.arguments
? JSON.parse(tool.function.arguments)
: {},
};
}
}
}
if (choice.finish_reason === 'stop') {
yield { type: 'done' };
}
}
}
8.5.4 Mock 流适配器
在开发阶段，使用 Mock 流模拟上述协议：
/**
* Mock LLM 流 —— 模拟真实 API 的流式事件
*/
async function* mockLLMStream(prompt: string): AsyncGenerator<LLMEvent> {
// 1. 思考阶段
yield { type: 'thinking' };
await delay(300 + Math.random() * 300);
// 2. 检测并匹配场景
if (prompt.includes('天气') || prompt.includes('weather')) {
yield* mockWeatherScenario(prompt);
} else if (prompt.includes('计算') || /\d+\s*[+\-*/]\s*\d+/.test(prompt)) {
yield* mockCalculateScenario(prompt);
} else if (prompt.includes('错误') || prompt.includes('error')) {
yield { type: 'error', message: '模拟错误：服务暂时不可用' };
} else {
yield* mockChatScenario(prompt);
}
// 3. 完成
yield { type: 'done' };
}
/**
* 逐字生成文本的辅助函数
*/
async function* typeText(text: string, minDelay = 15, maxDelay = 30): AsyncGenerator<LLMEvent> {
for (const ch of text) {
yield { type: 'text', content: ch };
await delay(minDelay + Math.random() * (maxDelay - minDelay));
}
}
8.6 流式文本的性能优化
8.6.1 综合优化方案
| 技术 | 说明 | 效果 |
|---|---|---|
| 节流渲染（Throttle） | 限制渲染帧率 (16-50ms) | 减少 CPU 使用，省电 |
| 差分更新（smartCSR） | 只输出变化区域 | 减少终端 IO |
| 批量写入（Batch） | 收集变化一次性刷新 | 减少渲染次数 |
| 降低 Spinner 频率 | 100-150ms 即可 | 减少无谓渲染 |
| 使用 setInterval | 优于 requestAnimationFrame | 更可控 |
| 元素复用 | 更新内容而非创建/销毁 | 减少 GC 压力 |
8.6.2 性能量化参考
// 不优化：50ms 间隔渲染 1000 次
// CPU: 约 15-20% 单核
// 终端输出: 约 5MB 数据
// 优化后：33ms 节流 + 批处理
// CPU: 约 3-5% 单核
// 终端输出: 约 1MB 数据
8.6.3 综合渲染管理器
class StreamRenderManager {
private lastRenderTime = 0;
private readonly MIN_INTERVAL = 33;
private batchBuffer: string[] = [];
private batchTimer: ReturnType<typeof setTimeout> | null = null;
private readonly BATCH_INTERVAL = 50;
constructor(
private renderFn: (content: string) => void,
private screen: Widgets.Screen,
) {}
/** 添加流式文本片段 */
addChunk(chunk: string): void {
this.batchBuffer.push(chunk);
if (!this.batchTimer) {
this.batchTimer = setTimeout(() => this.flush(), this.BATCH_INTERVAL);
}
}
/** 批量刷新到 UI */
private flush(): void {
if (this.batchBuffer.length === 0) {
this.batchTimer = null;
return;
}
const content = this.batchBuffer.join('');
this.batchBuffer = [];
// 节流渲染
const now = Date.now();
if (now - this.lastRenderTime >= this.MIN_INTERVAL) {
this.renderFn(content);
this.lastRenderTime = now;
}
this.batchTimer = null;
}
/** 强制刷新（流结束时调用） */
flushAll(): void {
if (this.batchTimer) {
clearTimeout(this.batchTimer);
this.batchTimer = null;
}
if (this.batchBuffer.length > 0) {
const content = this.batchBuffer.join('');
this.batchBuffer = [];
this.renderFn(content);
}
this.screen.render();
}
}
8.7 完整的动画生命周期
在 examples/llm-chat.ts 中，动画的完整生命周期如下：
// 1. 用户发送消息后立即启动 Spinner
this.state = 'thinking';
this.startSpinner('AI 思考中...'); // ← 动画开始
// 2. 收到第一个文本 token
this.stopSpinner(); // ← Spinner 动画停止
this.state = 'streaming';
this.updateAssistantMessage(''); // ← 创建消息容器
// 3. 流式更新 — 打字机效果
for await (const event of stream) {
if (event.type === 'text') {
this.renderManager.addChunk(event.content); // 批处理添加
}
if (event.type === 'tool_call') {
this.renderManager.flushAll(); // 刷新剩余文本
this.showToolCall(event.name, event.args);
}
}
// 4. 生成完成
this.renderManager.flushAll(); // 确保所有文本已渲染
this.state = 'idle'; // ← 回到静态状态
8.8 聚焦感知动画
当终端失去焦点时暂停动画，减少 CPU 消耗：
// 在 Screen 级别监听焦点事件
process.stdout.write('\x1b[?1004h'); // 启用焦点事件
let isFocused = true;
process.stdin.on('data', (data: Buffer) => {
const str = data.toString();
// 焦点事件序列
if (str === '\x1b[I') {
isFocused = true;
// 恢复动画
}
if (str === '\x1b[O') {
isFocused = false;
// 暂停动画
}
});
// 修改动画循环，只在聚焦时渲染
private spinnerTick(): void {
if (!isFocused) return; // 失去焦点时不更新
// ... 更新动画帧
}
8.8.1 跨平台焦点检测
xterm 焦点事件（\x1b[I / \x1b[O）在 Windows 终端上不一定支持。以下提供回退方案：
type FocusDetector = {
onFocus: (cb: () => void) => void;
onBlur: (cb: () => void) => void;
start: () => void;
stop: () => void;
};
function createFocusDetector(): FocusDetector {
const focusCbs: Array<() => void> = [];
const blurCbs: Array<() => void> = [];
// 尝试启用 xterm 焦点事件
let useXtermEvents = true;
try {
process.stdout.write('\x1b[?1004h');
} catch {
useXtermEvents = false;
}
// Windows 回退：检测终端窗口可见性
let visibilityTimer: ReturnType<typeof setInterval> | null = null;
let wasFocused = true;
const onData = (data: Buffer) => {
const str = data.toString();
if (str === '\x1b[I') focusCbs.forEach(cb => cb());
if (str === '\x1b[O') blurCbs.forEach(cb => cb());
};
return {
onFocus: (cb) => focusCbs.push(cb),
onBlur: (cb) => blurCbs.push(cb),
start: () => {
if (useXtermEvents) {
process.stdin.on('data', onData);
}
// Windows 回退：通过定时检测窗口状态
// 使用 child_process 检查窗口句柄活动状态
if (process.platform === 'win32') {
visibilityTimer = setInterval(() => {
// 简化检测：如果超过 500ms 没有终端输出活动，认为失去焦点
// 实际应用可调用 Windows API 检测窗口状态
}, 1000);
}
},
stop: () => {
process.stdin.removeListener('data', onData);
if (visibilityTimer) {
clearInterval(visibilityTimer);
visibilityTimer = null;
}
try {
process.stdout.write('\x1b[?1004l'); // 关闭焦点事件
} catch {
// 忽略
}
},
};
}
8.8.2 blessed 焦点集成
利用 blessed 的 Screen 事件实现更自然的集成：
class FocusAwareAnimationManager {
private isFocused = true;
private savedFrameIndex = 0;
private savedElapsed = 0;
private animationStartTime = 0;
private pausedIndicator: Widgets.BoxElement | null = null;
private pauseTimer: ReturnType<typeof setInterval> | null = null;
constructor(private screen: Widgets.Screen) {
// blessed screen 的 focus/blur 事件
// 注意：blessed 的 focus 事件通常用于元素焦点，
// 但可以通过全局 keypress 和终端事件组合实现
this.screen.on('keypress', () => {
if (!this.isFocused) {
// 任何按键输入都表明终端已重新获得焦点
this.handleFocus();
}
});
}
/** 整合 xterm 焦点事件到 blessed */
integrateWithTerminal(): void {
process.stdout.write('\x1b[?1004h');
process.stdin.on('data', (data: Buffer) => {
const str = data.toString();
if (str === '\x1b[I') this.handleFocus();
if (str === '\x1b[O') this.handleBlur();
});
}
/** 失去焦点：保存状态，暂停动画 */
private handleBlur(): void {
if (!this.isFocused) return;
this.isFocused = false;
// 记录当前帧信息供恢复使用
this.savedElapsed = Date.now() - this.animationStartTime;
this.showPausedIndicator();
this.emitPauseEvent();
}
/** 恢复焦点：还原状态，继续动画 */
private handleFocus(): void {
if (this.isFocused) return;
this.isFocused = true;
this.hidePausedIndicator();
this.emitResumeEvent();
}
/** 在屏幕角落显示暂停指示器 */
private showPausedIndicator(): void {
if (this.pausedIndicator) return;
this.pausedIndicator = blessed.box({
parent: this.screen,
bottom: 0,
right: 0,
width: 14,
height: 1,
content: ' {yellow-fg}⏸ PAUSED{/yellow-fg} ',
tags: true,
style: { bg: '#333333' },
});
this.screen.render();
}
private hidePausedIndicator(): void {
if (this.pausedIndicator) {
this.screen.remove(this.pausedIndicator);
this.pausedIndicator = null;
this.screen.render();
}
}
/** 持久化存储帧状态 */
saveFrameState(frameIndex: number): void {
this.savedFrameIndex = frameIndex;
this.animationStartTime = Date.now();
}
getSavedFrameState(): { frameIndex: number; elapsed: number } {
return {
frameIndex: this.savedFrameIndex,
elapsed: this.savedElapsed,
};
}
get isActive(): boolean {
return this.isFocused;
}
// 供外部订阅的事件
private pauseCbs: Array<() => void> = [];
private resumeCbs: Array<() => void> = [];
onPause(cb: () => void): void { this.pauseCbs.push(cb); }
onResume(cb: () => void): void { this.resumeCbs.push(cb); }
private emitPauseEvent(): void {
this.pauseCbs.forEach(cb => cb());
}
private emitResumeEvent(): void {
// 恢复到暂停前的帧
this.resumeCbs.forEach(cb => cb());
}
}
8.8.3 节流 vs 暂停策略
| 策略 | 行为 | 适用场景 |
|---|---|---|
| 暂停 | 完全停止定时器，恢复时从保存状态继续 | CPU 敏感环境、笔记本电池模式 |
| 节流 | 将 FPS 降至 1-2fps，继续更新但极慢 | 需要保持"活动"视觉、监控场景 |
| 降质 | 停止动画帧更新，但继续文本追加 | 流式输出中失去焦点时 |
type BlurStrategy = 'pause' | 'throttle' | 'degrade';
class AdaptiveAnimationController {
private strategy: BlurStrategy = 'pause';
private focused = true;
private originalInterval = 100;
private currentTimer: ReturnType<typeof setInterval> | null = null;
constructor(
private animate: () => void,
private focusManager: FocusAwareAnimationManager,
) {
this.focusManager.onPause(() => this.onBlur());
this.focusManager.onResume(() => this.onFocus());
}
setStrategy(s: BlurStrategy): void {
this.strategy = s;
}
private onBlur(): void {
this.focused = false;
if (this.strategy === 'pause') {
this.stopTimer();
} else if (this.strategy === 'throttle') {
this.restartTimer(1000); // 降低到 1fps
}
// 'degrade' 策略保持原样：只停止动画帧，文本继续
}
private onFocus(): void {
this.focused = true;
this.restartTimer(this.originalInterval);
}
private stopTimer(): void {
if (this.currentTimer) {
clearInterval(this.currentTimer);
this.currentTimer = null;
}
}
private restartTimer(interval: number): void {
this.stopTimer();
this.currentTimer = setInterval(() => {
this.animate();
}, interval);
}
}
8.9 实验：自定义动画效果
尝试在 llm-chat.ts 中替换 Spinner 动画风格：
// 使用弹跳风格
const bounceFrames = ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'];
// 或使用时钟风格（注意：emoji 需要真彩色支持）
const clockFrames = ['🕐', '🕑', '🕒', '🕓', '🕔', '🕕', '🕖', '🕗', '🕘', '🕙', '🕚', '🕛'];
选择 Spinner 的建议：
- dots: 最通用，所有终端都支持
- line: 最轻量，适合性能敏感场景
- clock: 视觉新颖，但需要 emoji 支持
- bar: 适合进度相关的加载指示
8.10 动画性能测量
量化每种动画类型的性能开销，帮助识别瓶颈。
8.10.1 FPS 计数器叠加层
class FPSCounter {
private frameCount = 0;
private lastMeasureTime = Date.now();
private currentFPS = 0;
private element: Widgets.BoxElement;
constructor(screen: Widgets.Screen) {
this.element = blessed.box({
parent: screen,
top: 0,
right: 0,
width: 14,
height: 1,
content: ' FPS: -- ',
style: { fg: 'green', bg: '#222222' },
tags: true,
});
}
/** 每帧调用一次 */
tick(): void {
this.frameCount++;
const now = Date.now();
const elapsed = now - this.lastMeasureTime;
if (elapsed >= 1000) {
this.currentFPS = Math.round((this.frameCount * 1000) / elapsed);
this.frameCount = 0;
this.lastMeasureTime = now;
const color = this.currentFPS >= 25 ? 'green' :
this.currentFPS >= 15 ? 'yellow' : 'red';
this.element.setContent(
` {${color}-fg}FPS: ${String(this.currentFPS).padStart(2)}{/${color}-fg} `
);
}
}
get fps(): number {
return this.currentFPS;
}
show(): void { this.element.show(); }
hide(): void { this.element.hide(); }
destroy(): void { this.element.detach(); }
}
8.10.2 帧时序直方图
class FrameTimingHistogram {
private timestamps: number[] = [];
private readonly MAX_SAMPLES = 120; // 最近 120 帧
private element: Widgets.BoxElement;
constructor(parent: Widgets.BoxElement) {
this.element = blessed.box({
parent,
top: 0, left: 0,
width: 30, height: 6,
label: ' Frame Timing (ms) ',
border: { type: 'line', fg: 'cyan' },
tags: true,
style: { fg: 'white', bg: 'black' },
});
}
recordFrame(): void {
const now = Date.now();
if (this.timestamps.length > 0) {
const delta = now - this.timestamps[this.timestamps.length - 1];
if (delta > 0) {
this.timestamps.push(delta);
}
} else {
this.timestamps.push(0);
}
if (this.timestamps.length > this.MAX_SAMPLES) {
this.timestamps = this.timestamps.slice(-this.MAX_SAMPLES);
}
this.renderHistogram();
}
private renderHistogram(): void {
const deltas = this.timestamps.slice(1); // 跳过第一个 0
if (deltas.length === 0) return;
const min = Math.min(...deltas);
const max = Math.max(...deltas);
const avg = deltas.reduce((a, b) => a + b, 0) / deltas.length;
// 将时序分布可视化为条形直方图
const buckets = [0, 8, 16, 33, 50, 100, 200];
const counts = new Array(buckets.length).fill(0);
for (const d of deltas) {
for (let i = buckets.length - 1; i >= 0; i--) {
if (d >= buckets[i]) {
counts[i]++;
break;
}
}
}
const total = deltas.length;
const lines = buckets.map((b, i) => {
const pct = total > 0 ? (counts[i] / total) * 100 : 0;
const barLen = Math.round(pct / 5);
const bar = '█'.repeat(barLen);
const label = `${String(b).padStart(3)}+`;
return ` ${label} ${bar} ${counts[i]}`;
});
const content = [
` Min:${String(min).padStart(3)}ms Avg:${String(Math.round(avg)).padStart(3)}ms Max:${String(max).padStart(3)}ms`,
' --- Distribution ---',
...lines,
].join('\n');
this.element.setContent(content);
}
}
8.10.3 各动画类型渲染开销
/**
* 性能基准测试：对比不同动画类型的渲染开销
*/
async function benchmarkAnimations(screen: Widgets.Screen): Promise<void> {
const testBox = blessed.box({
parent: screen,
top: 0, left: 0,
width: 50, height: 5,
style: { bg: 'black' },
});
const results: Array<{ name: string; avgRenderMs: number; fps: number }> = [];
// 1. Spinner 动画开销
const spinner = new Spinner(testBox, screen);
const spinnerTimes: number[] = [];
spinner.start('测试');
for (let i = 0; i < 50; i++) {
const start = performance.now();
screen.render();
spinnerTimes.push(performance.now() - start);
await delay(100);
}
spinner.stop();
results.push({
name: 'Spinner',
avgRenderMs: average(spinnerTimes),
fps: 1000 / average(spinnerTimes),
});
// 2. 打字机效果开销
const textBox = blessed.box({
parent: testBox,
top: 0, left: 0,
width: '100%', height: 3,
style: { fg: 'white', bg: 'black' },
});
const typewriterTimes: number[] = [];
for (let i = 0; i < 100; i++) {
textBox.setContent('A'.repeat(i + 1));
const start = performance.now();
screen.render();
typewriterTimes.push(performance.now() - start);
}
results.push({
name: 'Typewriter',
avgRenderMs: average(typewriterTimes),
fps: 1000 / average(typewriterTimes),
});
// 3. 进度条动画开销
const progressTimes: number[] = [];
const pBar = blessed.progressbar({
parent: testBox,
top: 0, left: 0,
width: '100%', height: 1,
});
for (let v = 0; v <= 100; v++) {
pBar.setProgress(v);
const start = performance.now();
screen.render();
progressTimes.push(performance.now() - start);
}
results.push({
name: 'ProgressBar',
avgRenderMs: average(progressTimes),
fps: 1000 / average(progressTimes),
});
// 输出结果
console.table(results);
testBox.detach();
screen.render();
}
function average(arr: number[]): number {
return arr.reduce((a, b) => a + b, 0) / arr.length;
}
8.10.4 内存使用追踪
class MemoryTracker {
private totalContentLength = 0;
private elementCount = 0;
private accumulationHistory: number[] = [];
private element: Widgets.BoxElement;
constructor(parent: Widgets.BoxElement) {
this.element = blessed.box({
parent,
top: 0, left: 0,
width: 40, height: 4,
label: ' Memory ',
border: { type: 'line', fg: 'magenta' },
tags: true,
style: { fg: 'white', bg: 'black' },
});
}
/** 追踪累积文本量 */
trackContent(length: number): void {
this.totalContentLength += length;
this.accumulationHistory.push(this.totalContentLength);
// 仅保留最近 100 个采样点
if (this.accumulationHistory.length > 100) {
this.accumulationHistory.shift();
}
}
trackElementAdded(): void { this.elementCount++; }
trackElementRemoved(): void { this.elementCount = Math.max(0, this.elementCount - 1); }
/** 估算内存占用（粗略） */
private estimateMemoryBytes(): number {
// 每个字符约 2 字节（UTF-16）
const textMemory = this.totalContentLength * 2;
// 每个 blessed 元素约 2KB 基础开销
const elementMemory = this.elementCount * 2048;
return textMemory + elementMemory;
}
updateDisplay(): void {
const memBytes = this.estimateMemoryBytes();
const memKB = (memBytes / 1024).toFixed(1);
const contentKB = ((this.totalContentLength * 2) / 1024).toFixed(1);
this.element.setContent(
` Content: ${this.totalContentLength} chars (${contentKB}KB)\n` +
` Elements: ${this.elementCount}\n` +
` Estimated: ${memKB}KB total`
);
}
}
8.10.5 性能分析技巧
- 使用
performance.now()而非Date.now()获得亚毫秒级精度，适合测量单帧渲染时间 - 监控
screen.render()耗时 — 在 render 前后打点，耗时超过 50ms 表示需要优化 - 关注元素数量 — blessed 在元素超过 500 时渲染性能显著下降，考虑虚拟滚动
- 避免频繁的
setContent调用 — 合并多次更新为一次批量 setContent - 使用
screen.debug日志 — blessed 支持screen.debug = true输出调试信息到日志文件 - 测量终端 IO — 大量 ANSI 序列输出会导致终端"喘不过气"；使用
process.stdout.write计数监控
8.11 过渡动画
在不同 UI 状态间添加平滑过渡，提升视觉连贯性。
8.11.1 字符密度淡入淡出
利用空格到完整字符的密度变化实现淡入效果：
/**
* 淡入效果：从纯空格逐渐过渡到目标文本
* @param element 目标 blessed 元素
* @param targetText 最终显示的文本
* @param steps 过渡步数（越高越平滑）
* @param interval 每步间隔 (ms)
*/
async function fadeIn(
element: Widgets.BoxElement,
screen: Widgets.Screen,
targetText: string,
steps: number = 10,
interval: number = 30,
): Promise<void> {
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
// 将每个字符从空格逐步过渡到完整字符
const fadedText = targetText.split('').map(ch => {
if (ch === ' ' || ch === '\n') return ch;
// 使用密度字符模拟渐变：' ' -> '░' -> '▒' -> '▓' -> ch
const densityChars = [' ', '░', '▒', '▓'];
const densityIndex = Math.min(
Math.floor(progress * densityChars.length),
densityChars.length - 1,
);
if (progress < 0.3) {
// 低进度：仅显示密度字符
return ch.match(/\w/) ? densityChars[densityIndex] : ch;
} else if (progress < 0.7) {
// 中进度：密度字符混合目标字符
return Math.random() < progress
? ch
: densityChars[densityIndex];
} else {
// 高进度：逐渐显示完整字符
return ch;
}
}).join('');
element.setContent(fadedText);
screen.render();
await delay(interval);
}
// 确保最终内容精确
element.setContent(targetText);
screen.render();
}
/**
* 淡出效果：从完整文本过渡到空白
*/
async function fadeOut(
element: Widgets.BoxElement,
screen: Widgets.Screen,
steps: number = 8,
interval: number = 25,
): Promise<void> {
const currentContent = element.getContent();
await fadeIn(element, screen, '', steps, interval);
}
8.11.2 从右侧滑入工具卡片
/**
* 工具调用卡片从右侧滑入
*/
async function slideInFromRight(
element: Widgets.BoxElement,
screen: Widgets.Screen,
slideWidth: number = 30,
duration: number = 200,
): Promise<void> {
const steps = 10;
const interval = duration / steps;
// 保存原始 left 值，假设为绝对数值或百分比
const originalLeft = element.left;
element.left = slideWidth; // 从右侧外开始
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
// 缓出效果：快速开始，慢速结束
const eased = 1 - Math.pow(1 - progress, 2);
const currentLeft = Math.round(slideWidth * (1 - eased));
element.left = currentLeft;
screen.render();
await delay(interval);
}
// 恢复原始位置
element.left = originalLeft;
screen.render();
}
/**
* 滑出到右侧
*/
async function slideOutToRight(
element: Widgets.BoxElement,
screen: Widgets.Screen,
slideWidth: number = 30,
duration: number = 150,
): Promise<void> {
const steps = 8;
const interval = duration / steps;
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
const eased = progress * progress; // 缓入效果：慢速开始，快速结束
element.left = Math.round(slideWidth * eased);
screen.render();
await delay(interval);
}
element.hide();
screen.render();
}
8.11.3 展开/折叠详细视图
/**
* 展开视图：从 0 高度逐步增加到目标高度
*/
async function expandView(
element: Widgets.BoxElement,
screen: Widgets.Screen,
targetHeight: number,
duration: number = 300,
): Promise<void> {
const steps = Math.min(targetHeight, 15);
const interval = duration / steps;
element.show();
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
// 使用 overshoot 缓动产生"弹性展开"效果
const eased = progress < 0.8
? progress / 0.8 * 0.9
: 0.9 + 0.1 * (progress - 0.8) / 0.2;
element.height = Math.round(targetHeight * eased);
screen.render();
await delay(interval);
}
element.height = targetHeight;
screen.render();
}
/**
* 折叠视图：高度逐渐归零
*/
async function collapseView(
element: Widgets.BoxElement,
screen: Widgets.Screen,
duration: number = 200,
): Promise<void> {
const currentHeight = typeof element.height === 'number'
? element.height
: parseInt(element.height as string) || 5;
const steps = Math.min(currentHeight, 10);
const interval = duration / steps;
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
element.height = Math.round(currentHeight * (1 - progress));
screen.render();
await delay(interval);
}
element.hide();
screen.render();
}
8.11.4 内容状态间交叉淡变
/**
* 交叉淡变：新旧内容同时以不同透明度混合
* 利用 blessed 叠加元素实现
*/
async function crossFade(
container: Widgets.BoxElement,
screen: Widgets.Screen,
newContent: string,
duration: number = 200,
): Promise<void> {
const overlay = blessed.box({
parent: container.parent,
top: container.top,
left: container.left,
width: container.width,
height: container.height,
content: newContent,
style: { fg: 'white', bg: 'black' },
tags: true,
wrap: true,
});
const steps = 10;
const interval = duration / steps;
// 旧内容逐渐透明（依赖 blessed 的隐藏），新内容逐渐显示
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
if (progress > 0.3) {
container.hide();
}
screen.render();
await delay(interval);
}
// 最终切换：新内容替换旧内容，移除叠加层
container.setContent(newContent);
container.show();
overlay.detach();
screen.render();
}
8.11.5 过渡时长与缓动选择
| 过渡类型 | 推荐时长 | 缓动函数 | 适用场景 |
|---|---|---|---|
| 淡入 | 150-300ms | ease-out | 新消息出现 |
| 淡出 | 100-200ms | ease-in | 消息消失 |
| 滑入 | 200-350ms | ease-out | 工具卡片 |
| 滑出 | 100-200ms | ease-in | 卡片关闭 |
| 展开 | 200-400ms | overshoot | 详情面板 |
| 折叠 | 150-250ms | ease-in | 面板收起 |
| 交叉淡变 | 150-250ms | linear | 内容更新 |
8.11.6 弹跳过渡（超调缓动）
/**
* 带超调的弹性过渡：目标值附近来回震荡几次后稳定
*/
function bounceEaseOut(t: number): number {
if (t < 1 / 2.75) {
return 7.5625 * t * t;
} else if (t < 2 / 2.75) {
t -= 1.5 / 2.75;
return 7.5625 * t * t + 0.75;
} else if (t < 2.5 / 2.75) {
t -= 2.25 / 2.75;
return 7.5625 * t * t + 0.9375;
} else {
t -= 2.625 / 2.75;
return 7.5625 * t * t + 0.984375;
}
}
/**
* 超调缓动：先超过目标值，再回弹
*/
function overshootEaseOut(t: number, magnitude: number = 1.2): number {
return Math.min(1, t * t * ((magnitude + 1) * t - magnitude));
}
/**
* 弹跳展开效果
*/
async function expandWithBounce(
element: Widgets.BoxElement,
screen: Widgets.Screen,
targetHeight: number,
): Promise<void> {
const steps = 20;
const interval = 20;
element.show();
for (let i = 1; i <= steps; i++) {
const progress = i / steps;
const eased = bounceEaseOut(progress);
const currentHeight = Math.max(1, Math.round(targetHeight * eased));
element.height = currentHeight;
screen.render();
await delay(interval);
}
element.height = targetHeight;
screen.render();
}
8.12 脉冲/呼吸效果
为等待状态和专注于动画的 UI 元素添加有机的生命感。
8.12.1 呼吸动画（空闲等待）
/**
* 呼吸效果：字符在可见与不可见之间平滑变化
* 适用于空闲等待状态，提示用户系统仍在运行
*/
class BreathingAnimation {
private timer: ReturnType<typeof setInterval> | null = null;
private element: Widgets.BoxElement;
private phase = 0;
constructor(
parent: Widgets.BoxElement,
private screen: Widgets.Screen,
private amplitude: number = 1.0, // 振幅：0.0-1.0
private frequency: number = 0.5, // 频率：每秒周期数
private text: string = '● 等待中...',
) {
this.element = blessed.box({
parent,
top: 0, left: 0,
width: '100%-2', height: 1,
content: '',
style: { fg: 'cyan', bg: '#1a1a1a' },
tags: true,
});
}
start(): void {
this.timer = setInterval(() => {
this.phase += 0.05 * this.frequency * 2 * Math.PI;
// 呼吸波形：使用 sin 模拟吸气和呼气
const breath = (Math.sin(this.phase) + 1) / 2; // 0-1 范围
const scaledBreath = 0.3 + breath * this.amplitude * 0.7;
// 通过 Unicode 上标/下标字符模拟大小变化
const sizeIndicator = scaledBreath > 0.7 ? '◉' :
scaledBreath > 0.4 ? '◎' : '○';
// 亮度通过透明度字符模拟
const density = Math.round(scaledBreath * 8);
const shimmer = '░▒▓█'[Math.min(density % 4, 3)];
this.element.setContent(
` {cyan-fg}${sizeIndicator} ${shimmer} ${this.text}{/cyan-fg}`
);
this.screen.render();
}, 50);
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
this.element.setContent('');
this.screen.render();
}
}
8.12.2 Unicode 块字符渐变
/**
* 使用完整块字符梯度创建平滑颜色过渡效果
* 通过字符密度组合模拟亮度渐变
*/
const GRADIENT_CHARS = [' ', '▏', '▎', '▍', '▌', '▋', '▊', '▉', '█'];
/**
* 创建水平渐变条
*/
function createGradientBar(
parent: Widgets.BoxElement,
screen: Widgets.Screen,
width: number = 30,
colors: Array<{ r: number; g: number; b: number }> = [
{ r: 0, g: 100, b: 255 },
{ r: 100, g: 200, b: 255 },
{ r: 255, g: 100, b: 100 },
],
): { update: (progress: number) => void } {
const element = blessed.box({
parent,
top: 0, left: 0,
width,
height: 1,
style: { bg: 'black' },
});
return {
update(progress: number) {
// 将 progress (0-1) 映射到颜色渐变
const clampedProgress = Math.max(0, Math.min(1, progress));
// 插值颜色
const segmentCount = colors.length - 1;
const segment = Math.min(
Math.floor(clampedProgress * segmentCount),
segmentCount - 1,
);
const localProgress = (clampedProgress * segmentCount) - segment;
const c1 = colors[segment];
const c2 = colors[segment + 1];
const r = Math.round(c1.r + (c2.r - c1.r) * localProgress);
const g = Math.round(c1.g + (c2.g - c1.g) * localProgress);
const b = Math.round(c1.b + (c2.b - c1.b) * localProgress);
// 使用块字符构建渐变条
const barChars = Array.from({ length: width }, (_, i) => {
const charProgress = i / width;
const charIndex = Math.floor(charProgress * GRADIENT_CHARS.length);
return GRADIENT_CHARS[Math.min(charIndex, GRADIENT_CHARS.length - 1)];
});
element.setContent(
`{${r}-${g}-${b}-fg}${barChars.join('')}{/${r}-${g}-${b}-fg}`
);
screen.render();
},
};
}
8.12.3 心跳模式
/**
* 心跳脉冲模式：快速双脉冲后暂停
* 适合表示"活跃"或"监听中"状态
*/
class HeartbeatAnimation {
private timer: ReturnType<typeof setInterval> | null = null;
private element: Widgets.BoxElement;
private phase = 0;
constructor(
parent: Widgets.BoxElement,
private screen: Widgets.Screen,
private bpm: number = 72, // 每分钟心跳数
) {
this.element = blessed.box({
parent,
top: 0, left: 0,
width: 6, height: 1,
content: ' ♥ ',
style: { fg: 'red', bg: '#1a1a1a' },
});
}
start(): void {
const interval = Math.round((60000 / this.bpm) / 8); // 每拍 8 帧
this.timer = setInterval(() => {
this.phase = (this.phase + 1) % 8;
// 心跳模式：lub-dub 双脉冲
const isLub = this.phase === 0 || this.phase === 1;
const isDub = this.phase === 2 || this.phase === 3;
if (isLub || isDub) {
// 脉冲峰值
const brightness = isLub ? 'bright' : 'dim';
this.element.style.fg = brightness === 'bright' ? '#ff4444' : '#aa2222';
this.element.setContent(' ♥ ');
} else {
// 谷值
this.element.style.fg = '#551111';
this.element.setContent(' ♡ ');
}
this.screen.render();
}, interval);
// 实际效果：lub(1-2) dub(3-4) 休息(5-8)
// 72bpm 时每拍约 833ms，分 8 帧每帧约 104ms
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
this.element.setContent('');
this.screen.render();
}
}
8.12.4 脉冲边框
/**
* 脉冲边框：使元素边框颜色或亮度周期性变化
* 适合需要吸引用户注意的提示元素
*/
class PulsingBorder {
private timer: ReturnType<typeof setInterval> | null = null;
private phase = 0;
constructor(
private element: Widgets.BoxElement,
private screen: Widgets.Screen,
private baseColor: string = 'yellow',
private pulseSpeed: number = 1.0, // 速度倍率
) {}
start(): void {
this.timer = setInterval(() => {
this.phase += 0.05 * this.pulseSpeed;
// 使用正弦波控制亮度
const brightness = (Math.sin(this.phase) + 1) / 2; // 0-1
const intensity = Math.round(155 + brightness * 100); // 155-255
// 颜色逐步在基础色和亮色之间变化
const borderColor = brightness > 0.5
? `${this.baseColor}`
: `#${intensity.toString(16).repeat(3)}`;
this.element.style.border = { fg: borderColor as any };
this.screen.render();
}, 50);
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
this.element.style.border = { fg: this.baseColor as any };
this.screen.render();
}
}
8.12.5 颜色脉冲（色相循环）
/**
* HSL 色相循环：在 360 度色环上平滑过渡
*/
function hslToRgb(h: number, s: number, l: number): { r: number; g: number; b: number } {
h = h / 360;
s = s / 100;
l = l / 100;
const a = s * Math.min(l, 1 - l);
const f = (n: number) => {
const k = (n + h * 12) % 12;
return l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
};
return {
r: Math.round(f(0) * 255),
g: Math.round(f(8) * 255),
b: Math.round(f(4) * 255),
};
}
class ColorPulseAnimation {
private timer: ReturnType<typeof setInterval> | null = null;
private hue = 0;
constructor(
private element: Widgets.BoxElement,
private screen: Widgets.Screen,
private speed: number = 30, // 每秒色相变化度数
private saturation: number = 80,
private lightness: number = 60,
) {}
start(): void {
this.timer = setInterval(() => {
this.hue = (this.hue + this.speed * 0.05) % 360;
const { r, g, b } = hslToRgb(this.hue, this.saturation, this.lightness);
// 更新元素前景色
this.element.style.fg = { r, g, b } as any;
this.screen.render();
}, 50);
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
}
}
8.12.6 振幅与频率控制
所有脉冲/呼吸效果都支持两个关键参数：
interface PulseOptions {
/** 振幅 (0.0-1.0)：控制变化幅度，0 为静止 */
amplitude: number;
/** 频率倍率 (0.1-5.0)：控制变化速度，1.0 为默认 */
frequency: number;
}
/**
* 统一的脉冲控制器
*/
class PulseController {
private animations: Array<{
stop: () => void;
setAmplitude: (a: number) => void;
setFrequency: (f: number) => void;
}> = [];
register(animation: {
stop: () => void;
setAmplitude: (a: number) => void;
setFrequency: (f: number) => void;
}): void {
this.animations.push(animation);
}
setGlobalAmplitude(a: number): void {
this.animations.forEach(anim => anim.setAmplitude(a));
}
setGlobalFrequency(f: number): void {
this.animations.forEach(anim => anim.setFrequency(f));
}
pause(): void {
this.setGlobalAmplitude(0);
}
resume(): void {
this.setGlobalAmplitude(1);
}
stopAll(): void {
this.animations.forEach(anim => anim.stop());
this.animations = [];
}
}
8.13 无障碍动画
确保动画不会对特定用户群体造成不适，并提供足够的控制选项。
8.13.1 prefers-reduced-motion 检测
/**
* 检测用户是否在 OS 级别开启了"减少动效"偏好
*/
function prefersReducedMotion(): boolean {
// 方式 1：通过终端转义序列查询
// DECRPM 报告 — 并非所有终端支持
try {
process.stdout.write('\x1b[?1$p'); // 查询 DECRPM 状态
} catch {
// 忽略
}
// 方式 2：通过环境变量检测
const envHints = [
process.env.WEBKIT_FORCE_COMPOSITING_MODE,
process.env.NO_EMOTICON, // 部分 Linux 发行版使用
];
// 方式 3：通过 NO_COLOR 等标准推断简化渲染需求
if (process.env.NO_COLOR || process.env.TERM === 'dumb') {
return true;
}
// 方式 4：配置文件检测
// 用户可在 ~/.claude/config 中设置
// animation: reduced | no-preference
return false;
}
/**
* 简化动画配置
*/
type MotionPreference = 'no-preference' | 'reduced' | 'no-animation';
function getMotionPreference(): MotionPreference {
if (process.env.CLAUDE_ANIMATION === 'none') return 'no-animation';
if (process.env.CLAUDE_ANIMATION === 'reduced') return 'reduced';
// 检测 OS 级偏好（macOS 辅助功能 → "减少动效"）
if (prefersReducedMotion()) return 'reduced';
return 'no-preference';
}
8.13.2 NO_COLOR 与 TERM 环境变量
interface AnimationEnvironment {
/** 是否支持颜色 */
hasColor: boolean;
/** 是否支持 Unicode */
hasUnicode: boolean;
/** 终端类型 */
term: string;
/** 建议最大帧率 */
suggestedMaxFPS: number;
}
function detectAnimationEnvironment(): AnimationEnvironment {
const term = process.env.TERM || 'unknown';
const hasNoColor = process.env.NO_COLOR !== undefined;
// 根据终端类型判断能力
const isDumb = term === 'dumb';
const isSimple = ['xterm', 'vt100', 'linux'].includes(term);
return {
hasColor: !hasNoColor && !isDumb,
hasUnicode: !isDumb && !isSimple,
term,
suggestedMaxFPS: isDumb ? 0 : isSimple ? 8 : 30,
};
}
/**
* 根据终端能力选择适当的 spinner 序列
*/
function selectSpinnerByEnvironment(
env: AnimationEnvironment,
): { frames: string[]; interval: number } {
if (!env.hasUnicode) {
// 回退到 ASCII-only spinner
return { frames: ['-', '\\', '|', '/'], interval: 150 };
}
if (!env.hasColor) {
return { frames: ['◐', '◓', '◑', '◒'], interval: 120 };
}
// 完整能力
return {
frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
interval: 100,
};
}
8.13.3 动画速度控制（用户可配置）
/**
* 全局动画速度控制器
* 所有动画组件都应通过此控制器获取实际间隔/延迟
*/
class AnimationSpeedController {
private static instance: AnimationSpeedController;
/** 速度倍率：1.0 = 正常，2.0 = 两倍快，0.5 = 半速 */
private speedMultiplier = 1.0;
static getInstance(): AnimationSpeedController {
if (!AnimationSpeedController.instance) {
AnimationSpeedController.instance = new AnimationSpeedController();
}
return AnimationSpeedController.instance;
}
/** 设置速度倍率 */
setSpeed(multiplier: number): void {
this.speedMultiplier = Math.max(0, Math.min(10, multiplier));
}
/** 获取实际延迟（已应用速度倍率） */
getDelay(baseDelay: number): number {
if (this.speedMultiplier === 0) return Infinity; // 完全停止
return baseDelay / this.speedMultiplier;
}
/** 获取实际帧间隔 */
getInterval(baseInterval: number): number {
if (this.speedMultiplier === 0) return 60000; // 停止时用长间隔
return baseInterval / this.speedMultiplier;
}
get multiplier(): number {
return this.speedMultiplier;
}
}
// 使用示例
// const actualDelay = AnimationSpeedController.getInstance().getDelay(100);
8.13.4 各动画类型的静态替代方案
为 reduced-motion 偏好提供静态替代：
| 动画类型 | 正常 | 简化（reduced） | 无动画 |
|---|---|---|---|
| Spinner | 旋转字符动画 | 固定图标 + "加载中"文字 | 纯文字 "加载中..." |
| 打字机 | 逐字出现 | 逐词出现（50ms/词） | 整段一次显示 |
| 进度条 | 增量填充 | 仅百分比数字更新 | 完成后显示结果 |
| 呼吸 | 脉冲/颜色变化 | 静态图标 | 无 |
| 过渡 | 淡入/滑入 | 直接显示/隐藏 | 立即切换 |
class ReducedMotionAdapter {
constructor(private preference: MotionPreference) {}
/** 获取打字机效果适配器 */
createTypewriter(renderFn: (text: string) => void): {
update: (text: string) => void;
flush: () => void;
} {
if (this.preference === 'no-animation') {
// 无动画模式：一次性渲染所有文本
return {
update: (text: string) => renderFn(text),
flush: () => {},
};
}
if (this.preference === 'reduced') {
// 简化模式：按段落分批显示
let buffer = '';
return {
update: (chunk: string) => {
buffer += chunk;
// 每遇到句号或换行渲染一次
if (chunk.includes('.') || chunk.includes('\n')) {
renderFn(buffer);
}
},
flush: () => {
if (buffer) renderFn(buffer);
buffer = '';
},
};
}
// 正常模式：传入标准打字机实现
return {
update: () => {},
flush: () => {},
};
}
/** 获取 spinner 静态替代 */
createSpinnerIndicator(parent: Widgets.BoxElement, screen: Widgets.Screen): {
start: (text: string) => void;
stop: () => void;
} {
if (this.preference === 'no-animation') {
let indicator: Widgets.BoxElement | null = null;
return {
start: (text: string) => {
indicator = blessed.box({
parent,
top: 0, left: 0,
width: '100%-2', height: 1,
content: ` ${text}...`,
style: { fg: 'yellow', bg: '#1a1a1a' },
});
screen.render();
},
stop: () => {
if (indicator) {
parent.remove(indicator);
indicator = null;
screen.render();
}
},
};
}
// reduced 模式：静态图标
let indicator: Widgets.BoxElement | null = null;
return {
start: (text: string) => {
indicator = blessed.box({
parent,
top: 0, left: 0,
width: '100%-2', height: 1,
content: ` {yellow-fg}⟳ ${text}{/yellow-fg}`,
tags: true,
style: { bg: '#1a1a1a' },
});
screen.render();
},
stop: () => {
if (indicator) {
parent.remove(indicator);
indicator = null;
screen.render();
}
},
};
}
}
8.13.5 WCAG 指南映射
| WCAG 标准 | TUI 动画对应实现 | 检查项 |
|---|---|---|
| 2.2.2 暂停/停止/隐藏 | 全局暂停热键 (Ctrl+P)、聚焦失焦自动暂停 | 所有动画持续时间 < 5 秒或有暂停机制 |
| 2.3.1 三次闪烁 | 限制帧率 ≥ 60ms（< 16.6Hz） | 任何 1 秒内不超过 3 次亮度变化 |
| 2.3.2 三次闪烁阈值 | 禁止纯红交替闪烁 | 避免 red←→white 交替 |
| 1.4.1 颜色使用 | 动画不依赖颜色传达信息 | Spinner + 文字双重指示 |
| 1.4.4 文本缩放 | 不使用固定像素尺寸 | 所有元素使用相对尺寸 |
/**
* 安全检查：验证动画参数符合无障碍标准
*/
function validateAnimationSafety(params: {
minFrameInterval: number;
usesRedFlash: boolean;
duration: number;
hasPauseControl: boolean;
}): { passed: boolean; warnings: string[] } {
const warnings: string[] = [];
if (params.minFrameInterval < 60) {
warnings.push(
`帧间隔 ${params.minFrameInterval}ms 低于推荐的 60ms（≥16.6Hz 可能触发闪烁风险）`
);
}
if (params.usesRedFlash) {
warnings.push('使用纯红交替闪烁违反 WCAG 2.3.1 标准');
}
if (params.duration > 5000 && !params.hasPauseControl) {
warnings.push(`动画持续 ${params.duration}ms > 5s 但缺少暂停控制`);
}
return {
passed: warnings.length === 0,
warnings,
};
}
8.13.6 暂停全部动画热键
class GlobalAnimationPauseController {
private paused = false;
private callbacks: Array<(paused: boolean) => void> = [];
constructor(screen: Widgets.Screen) {
// 注册全局热键 Ctrl+P 暂停/恢复所有动画
screen.key(['C-p'], () => {
this.togglePause();
});
// ESC 键单独暂停，后续操作恢复
screen.key(['escape'], () => {
if (!this.paused) this.pause();
});
// 鼠标活动自动恢复
screen.on('mouse', () => {
if (this.paused) this.resume();
});
}
register(cb: (paused: boolean) => void): void {
this.callbacks.push(cb);
}
unregister(cb: (paused: boolean) => void): void {
this.callbacks = this.callbacks.filter(c => c !== cb);
}
togglePause(): void {
this.paused ? this.resume() : this.pause();
}
pause(): void {
if (this.paused) return;
this.paused = true;
this.callbacks.forEach(cb => cb(true));
}
resume(): void {
if (!this.paused) return;
this.paused = false;
this.callbacks.forEach(cb => cb(false));
}
get isPaused(): boolean {
return this.paused;
}
}
8.13.7 癫痫安全
/**
* 安全帧间隔守卫
* 确保任何动画帧间隔不低于安全阈值
*/
const SAFE_MIN_FRAME_INTERVAL_MS = 60; // ≈ 16.6 Hz，低于闪烁阈值
function safeInterval(requestedInterval: number): number {
return Math.max(requestedInterval, SAFE_MIN_FRAME_INTERVAL_MS);
}
/**
* 安全动画定时器包装
*/
class SafeAnimationTimer {
private timer: ReturnType<typeof setInterval> | null = null;
start(callback: () => void, requestedInterval: number): void {
this.stop();
const safeMs = safeInterval(requestedInterval);
this.timer = setInterval(callback, safeMs);
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
}
}
/**
* 动画安全检查清单（运行时自查）
*/
function runAnimationSafetyCheck(): string[] {
const issues: string[] = [];
// 检查是否设置了 NO_COLOR
if (process.env.NO_COLOR) {
issues.push('NO_COLOR 已设置，应禁用彩色动画');
}
// 检查终端类型
if (process.env.TERM === 'dumb') {
issues.push('TERM=dumb，应禁用所有动画');
}
// 检查是否可通过配置文件禁用
const configPath = process.env.HOME + '/.claude/config';
// 实际应用时可读取配置文件
return issues;
}
8.14 CSS 风格动画缓动函数
将 Web 动画的缓动概念引入 TUI，使动画节奏更自然。
8.14.1 标准缓动函数
/**
* 缓动函数类型
* 输入 t: 0-1（时间进度）
* 输出: 0-1（动画进度），可超调
*/
type EasingFunction = (t: number) => number;
// ── 线性 ──
const linear: EasingFunction = (t) => t;
// ── ease（默认）─ 缓慢开始，加速，缓慢结束 ──
const ease: EasingFunction = (t) => {
// 三次贝塞尔近似 cubic-bezier(0.25, 0.1, 0.25, 1.0)
return t < 0.5
? 2 * t * t
: -1 + (4 - 2 * t) * t;
};
// ── ease-in ── 缓慢开始，加速 ──
const easeIn: EasingFunction = (t) => t * t * t;
// ── ease-out ── 快速开始，减速 ──
const easeOut: EasingFunction = (t) => {
return 1 - Math.pow(1 - t, 3);
};
// ── ease-in-out ── 缓慢开始和结束 ──
const easeInOut: EasingFunction = (t) => {
return t < 0.5
? 4 * t * t * t
: 1 - Math.pow(-2 * t + 2, 3) / 2;
};
8.14.2 三次贝塞尔实现
/**
* 三次贝塞尔曲线插值
* 支持自定义控制点，类似 CSS cubic-bezier()
*/
function cubicBezier(
x1: number,
y1: number,
x2: number,
y2: number,
): EasingFunction {
const ZERO_LIMIT = 1e-6;
// 牛顿法求 x 对应的 t
function sampleCurveDerivativeX(t: number): number {
return 3 * (1 - t) * (1 - t) * x1 + 6 * (1 - t) * t * (x2 - x1) + 3 * t * t * (1 - x2);
}
function sampleCurveX(t: number): number {
return ((1 - t) * (1 - t) * (1 - t)) * 0 +
3 * ((1 - t) * (1 - t)) * t * x1 +
3 * (1 - t) * (t * t) * x2 +
(t * t * t) * 1;
}
function sampleCurveY(t: number): number {
return ((1 - t) * (1 - t) * (1 - t)) * 0 +
3 * ((1 - t) * (1 - t)) * t * y1 +
3 * (1 - t) * (t * t) * y2 +
(t * t * t) * 1;
}
function solveCurveX(x: number): number {
let t0 = 0;
let t1 = 1;
let t2 = x;
let x2_ = x;
for (let i = 0; i < 8; i++) {
x2_ = sampleCurveX(t2) - x;
if (Math.abs(x2_) < ZERO_LIMIT) return t2;
const d2 = sampleCurveDerivativeX(t2);
if (Math.abs(d2) < ZERO_LIMIT) break;
t2 = t2 - x2_ / d2;
}
t2 = x;
if (t2 < t0) return t0;
if (t2 > t1) return t1;
while (t0 < t1) {
x2_ = sampleCurveX(t2);
if (Math.abs(x2_ - x) < ZERO_LIMIT) return t2;
if (x > x2_) t0 = t2;
else t1 = t2;
t2 = (t1 - t0) / 2 + t0;
}
return t2;
}
return (t: number) => {
if (t <= 0) return 0;
if (t >= 1) return 1;
return sampleCurveY(solveCurveX(t));
};
}
// CSS 标准缓动的贝塞尔实现
const easingFunctions = {
linear: cubicBezier(0, 0, 1, 1),
ease: cubicBezier(0.25, 0.1, 0.25, 1.0),
'ease-in': cubicBezier(0.42, 0, 1.0, 1.0),
'ease-out': cubicBezier(0, 0, 0.58, 1.0),
'ease-in-out': cubicBezier(0.42, 0, 0.58, 1.0),
};
8.14.3 阶跃缓动函数
/**
* step-start：直接跳到终点
*/
const stepStart: EasingFunction = () => 1;
/**
* step-end：保持起点，结束时跳到终点
*/
const stepEnd: EasingFunction = (t) => t >= 1 ? 1 : 0;
/**
* steps(N)：将动画分为 N 个离散跳跃
* @param count 跳跃次数
* @param position 'start' | 'end' — 跳跃发生的时刻
*/
function steps(count: number, position: 'start' | 'end' = 'end'): EasingFunction {
return (t: number) => {
if (t <= 0) return 0;
if (t >= 1) return 1;
const step = position === 'start'
? Math.ceil(t * count) / count
: Math.floor(t * count) / count;
return step;
};
}
// 使用示例
// const step4End = steps(4, 'end'); // 0 → 0.25 → 0.5 → 0.75 → 1
// const step4Start = steps(4, 'start'); // 0.25 → 0.5 → 0.75 → 1 → 1
8.14.4 弹性与弹跳缓动
/**
* 弹性缓动：类似弹簧振荡
* @param amplitude 振幅倍率
* @param period 振荡周期
*/
function elasticEaseOut(
amplitude: number = 1,
period: number = 0.4,
): EasingFunction {
return (t: number) => {
if (t <= 0) return 0;
if (t >= 1) return 1;
const s = period / (2 * Math.PI) * Math.asin(1 / amplitude);
return amplitude * Math.pow(2, -10 * t) *
Math.sin((t - s) * (2 * Math.PI) / period) + 1;
};
}
function elasticEaseIn(
amplitude: number = 1,
period: number = 0.4,
): EasingFunction {
return (t: number) => {
if (t <= 0) return 0;
if (t >= 1) return 1;
const s = period / (2 * Math.PI) * Math.asin(1 / amplitude);
return -(amplitude * Math.pow(2, 10 * (t - 1)) *
Math.sin((t - 1 - s) * (2 * Math.PI) / period));
};
}
/**
* 弹跳缓出：球落地式弹跳
*/
const bounceEaseOutFn: EasingFunction = (t: number) => {
if (t < 1 / 2.75) return 7.5625 * t * t;
if (t < 2 / 2.75) return 7.5625 * (t -= 1.5 / 2.75) * t + 0.75;
if (t < 2.5 / 2.75) return 7.5625 * (t -= 2.25 / 2.75) * t + 0.9375;
return 7.5625 * (t -= 2.625 / 2.75) * t + 0.984375;
};
const bounceEaseInFn: EasingFunction = (t: number) => {
return 1 - bounceEaseOutFn(1 - t);
};
8.14.5 缓动函数应用于 Spinner 转速
/**
* 带缓动的 Spinner：转速随时间变化
*/
class EasedSpinner {
private timer: ReturnType<typeof setInterval> | null = null;
private element: Widgets.BoxElement;
private frameIndex = 0;
private startTime = 0;
private totalDuration: number;
private baseInterval: number;
constructor(
parent: Widgets.BoxElement,
private screen: Widgets.Screen,
private frames: string[] = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
private easing: EasingFunction = easeInOut,
duration: number = 2000, // 整个加速过程持续 2s
baseInterval: number = 150,
) {
this.totalDuration = duration;
this.baseInterval = baseInterval;
this.element = blessed.box({
parent,
top: 0, left: 0,
width: '100%-2', height: 1,
content: '',
style: { fg: 'yellow', bg: '#1a1a1a' },
tags: true,
});
}
start(text: string = 'AI 思考中...'): void {
this.startTime = Date.now();
this.frameIndex = 0;
this.timer = setInterval(() => {
const elapsed = Date.now() - this.startTime;
const progress = Math.min(elapsed / this.totalDuration, 1);
const eased = this.easing(progress);
// 当前间隔：从 baseInterval 逐渐降到 baseInterval * 0.3
const currentInterval = this.baseInterval * (1 - eased * 0.7);
this.frameIndex = (this.frameIndex + 1) % this.frames.length;
this.element.setContent(
` {yellow-fg}{bold}${this.frames[this.frameIndex]} ${text}{/bold}{/yellow-fg}`
);
this.screen.render();
// 动态调整下一帧间隔
if (this.timer) {
clearInterval(this.timer);
this.timer = setInterval(arguments.callee as any, currentInterval);
}
}, this.baseInterval);
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
if (this.element) {
this.element.detach();
this.screen.render();
}
}
}
8.14.6 缓动函数应用于打字机字符延迟
/**
* 带缓动的打字机效果
* 控制字符出现的节奏
*/
async function* easedTypewriter(
text: string,
easing: EasingFunction = easeOut,
baseDelay: number = 25,
minDelay: number = 5,
): AsyncGenerator<LLMEvent> {
const totalChars = text.length;
for (let i = 0; i < totalChars; i++) {
yield { type: 'text', content: text[i] };
const progress = i / Math.max(totalChars - 1, 1);
const eased = easing(progress);
// 映射缓动值到延迟范围
const delay = minDelay + (baseDelay - minDelay) * (1 - eased);
await delay(delay);
}
}
/**
* 帧插值：在动画帧之间生成中间帧，使过渡更平滑
*/
function interpolateFrames<T>(
startValue: T,
endValue: T,
easing: EasingFunction,
steps: number,
): Array<{ value: T; t: number }> {
const result: Array<{ value: T; t: number }> = [];
if (typeof startValue === 'number' && typeof endValue === 'number') {
for (let i = 0; i <= steps; i++) {
const t = i / steps;
const easedT = easing(t);
const value = (startValue as number) +
(endValue as number - (startValue as number)) * easedT;
result.push({ value: value as T, t: easedT });
}
}
return result;
}
// 使用示例：生成 Spinner 旋转的插值间隔
// const intervals = interpolateFrames(150, 30, elasticEaseOut(0.5), 20);
// intervals 可用来生成非均匀定时器序列
8.14.7 缓动函数速查表
| 函数 | CSS 等效 | 效果 | 适用动画 |
|---|---|---|---|
linear | linear | 匀速 | 进度条 |
easeIn | ease-in | 慢→快 | 淡出、滑出 |
easeOut | ease-out | 快→慢 | 淡入、滑入、展开 |
easeInOut | ease-in-out | 慢→快→慢 | 交叉淡变 |
elasticEaseOut(1, 0.4) | — | 弹性振荡后稳定 | 弹跳展开、通知出现 |
bounceEaseOut | cubic-bezier(0.68, -0.55, 0.27, 1.55) | 球落地弹跳 | 消息弹入 |
steps(4, 'end') | steps(4, end) | 离散跳跃 | 状态切换指示器 |
cubicBezier(0.1, 0.8, 0.3, 1.2) | 自定义 | 指定控制点 | 自定义动画曲线 |
实践： 修改 llm-chat.ts，将 Spinner 动画换一种风格（如 bounce 或 arc 序列），同时调整动画速度参数体验不同效果。
上一章： 第七章：工具调用 UI 实现
