HeurAMS

Appearance

Interface API 文档 ​

概述 ​

Interface 是 HeurAMS 的用户界面模块，基于 Textual 框架实现终端用户界面，负责记忆流程的屏幕管理和用户交互处理。

子模块 ​

1. Screens - 屏幕管理 ​

MemScreen 类 ​

主要记忆屏幕，实现核心的记忆练习界面。

python
class MemScreen(Screen):

继承自: textual.screen.Screen

主要功能:

  • 显示记忆内容和谜题
  • 处理用户输入和答案验证
  • 管理记忆流程状态
  • 提供快捷键支持

核心方法:

  • on_mount() - 屏幕挂载时的初始化
  • on_key(event) - 键盘事件处理
  • show_puzzle() - 显示当前谜题
  • validate_answer() - 验证用户答案
  • show_feedback() - 显示反馈信息

PrecachingScreen 类 ​

预缓存屏幕，负责资源预加载和初始化。

python
class PrecachingScreen(Screen):

主要功能:

  • 预加载记忆内容
  • 初始化算法数据
  • 准备学习资源
  • 显示加载进度

核心方法:

  • on_mount() - 启动预缓存流程
  • load_content() - 加载记忆内容
  • setup_algorithms() - 初始化算法
  • on_complete() - 预缓存完成处理

2. Compositions - 界面组件 ​

键盘快捷键绑定 ​

统一的键盘快捷键处理机制。

支持的快捷键:

  • Ctrl+C - 退出程序
  • Space - 显示答案/下一题
  • 数字键 1-5 - 记忆质量评分
  • H - 显示帮助信息
  • R - 重新生成谜题

状态显示组件 ​

实时显示记忆流程状态的界面组件。

显示信息:

  • 当前记忆单元进度
  • 算法参数状态
  • 学习统计数据
  • 系统资源使用情况

屏幕流程 ​

标准记忆流程 ​

PrecachingScreen → MemScreen → Feedback → Next Puzzle

状态转换 ​

  1. 预缓存阶段 (PrecachingScreen)

    • 加载记忆内容
    • 初始化算法
    • 准备谜题资源

  2. 记忆练习阶段 (MemScreen)

    • 显示谜题
    • 接收用户输入
    • 验证答案
    • 收集质量反馈

  3. 反馈阶段

    • 显示正确答案
    • 提供学习建议
    • 更新算法参数

用户交互 ​

输入处理 ​

键盘输入 ​

  • 质量评分: 数字键 1-5
  • 导航控制: 方向键、Tab
  • 功能操作: 空格、回车、Esc

鼠标输入 (如果支持) ​

  • 点击选择答案
  • 滚动查看内容
  • 按钮操作

输出显示 ​

内容布局 ​

  • 主内容区: 显示记忆内容和谜题
  • 状态栏: 显示进度和系统信息
  • 提示区: 显示操作提示和帮助
  • 反馈区: 显示答案验证结果

视觉样式 ​

  • 支持主题切换
  • 响应式布局
  • 可访问性支持

配置和自定义 ​

界面配置 ​

通过配置文件自定义界面行为：

toml
[interface]
# 快捷键配置
shortcuts = { "quit" = "ctrl+c", "next" = "space" }

# 显示配置
display = { "theme" = "dark", "font_size" = 14 }

# 行为配置
behavior = { "auto_advance" = true, "show_hints" = true }

主题自定义 ​

支持自定义颜色主题和布局：

python
# 自定义主题示例
custom_theme = {
    "primary": "#2E86AB",
    "secondary": "#A23B72",
    "background": "#1E1E1E",
    "text": "#FFFFFF"
}

扩展接口 ​

自定义屏幕 ​

开发者可以创建自定义屏幕：

python
from textual.screen import Screen

class CustomScreen(Screen):
    def compose(self):
        # 定义界面组件
        yield Header()
        yield ContentArea()
        yield Footer()

    def on_key(self, event):
        # 处理键盘事件
        if event.key == "q":
            self.app.exit()

组件集成 ​

集成自定义界面组件：

python
from textual.widgets import Static

class ProgressIndicator(Static):
    def update_progress(self, current, total):
        self.update(f"进度: {current}/{total}")

错误处理 ​

界面错误 ​

  • 加载失败: 显示友好的错误信息
  • 资源缺失: 提供恢复选项
  • 配置错误: 使用默认值并记录警告

用户输入验证 ​

  • 格式验证: 确保输入符合预期格式
  • 范围检查: 验证数值在有效范围内
  • 类型安全: 防止类型错误导致的崩溃

性能优化 ​

渲染优化 ​

  • 懒加载: 按需加载界面组件
  • 缓存机制: 重用已渲染的组件
  • 增量更新: 只更新变化的部分

内存管理 ​

  • 资源释放: 及时释放不再使用的资源
  • 对象池: 重用频繁创建的对象
  • 垃圾回收: 优化内存使用模式

使用示例 ​

基本屏幕使用 ​

python
from heurams.interface.screens.memory import MemScreen

# 创建记忆屏幕
screen = MemScreen()

# 设置记忆内容
screen.set_content(memory_content)

# 启动屏幕
app.push_screen(screen)

自定义快捷键 ​

python
class CustomMemScreen(MemScreen):
    def on_key(self, event):
        if event.key == "f":
            # 自定义功能
            self.show_full_content()
        else:
            super().on_key(event)

界面主题配置 ​

python
# 应用自定义主题
app.theme = custom_theme

# 动态切换主题
app.switch_theme("dark")

兼容性说明 ​

  • Textual 版本: 需要 Textual 0.52.0 或更高版本
  • Python 版本: 需要 Python 3.8 或更高版本
  • 终端要求: 支持 ANSI 转义序列的终端
  • 平台支持: Linux, macOS, Windows (部分功能)

© 2025 Wang Zhiyu 保留所有权