VimTerminalKit

一个 Swift 包，为你的命令行应用程序带来 Vim 风格的导航和强大的终端 UI 功能。轻松创建交互式终端 UI，支持单列布局（如文件浏览器）和多列布局（如菜单）。

功能

🎮 Vim 风格 (hjkl) 和方向键导航
📊 灵活的单列和多列布局
🔄 加载动画和状态管理
⌨️ 原始终端模式处理
🎨 终端控制序列
🔧 异步操作支持

安装

Swift 包管理器

将 VimTerminalKit 添加到你的 Package.swift

dependencies: [
    .package(url: "https://github.com/marcusziade/VimTerminalKit.git", from: "1.0.0")
]

然后在你的源文件中导入它

import VimTerminalKit

布局类型

单列布局（文件浏览器）

最佳应用场景

文件浏览器
线性列表
命令日志
垂直菜单

必要设置

let navigator = VimTerminalKit.Navigator(
    itemCount: items.count,
    columnsCount: 1  // Must be 1 for vertical lists
)

多列布局（网格菜单）

最佳应用场景

仪表盘布局
选项网格
类别选择
并排视图

必要设置

let navigator = VimTerminalKit.Navigator(
    itemCount: items.count,
    columnsCount: 2  // 2 or more for grid layouts
)

核心概念

1. 正确的初始化

正确的初始化模式对于避免编译器错误和运行时问题至关重要。

final class MyApp {
    private let navigator: VimTerminalKit.Navigator
    private let stateManager: VimTerminalKit.StateManager
    private var items: [String] = []
    
    init() {
        // 1. Initialize basic properties first
        self.items = []
        // 2. Set up navigator with initial state
        self.navigator = .init(itemCount: 1, columnsCount: 1)
        // 3. Initialize stateManager with empty closure
        self.stateManager = .init { }
        // 4. Set up callbacks after initialization
        setupStateManager()
    }
    
    private func setupStateManager() {
        stateManager = .init { [weak self] in
            self?.updateUI()
        }
    }
}

2. 状态管理

StateManager 处理 UI 更新和加载状态。

// Initialize with UI update callback
let stateManager = VimTerminalKit.StateManager { 
    // Update UI here
}

// Show loading state
await stateManager.withLoading(message: "Loading...") {
    try await someAsyncWork()
}

3. 导航控制

处理导航输入

switch VimTerminalKit.InputReader.getInput() {
case .vim(let direction), .arrow(let direction):
    navigator.navigate(.arrow(direction))
case .enter:
    // Handle selection
case .quit:
    isRunning = false
default:
    break
}

完整示例

1. 查看在 `/Sources` 下名为 'FileExplorer' 的完整 CLI 应用程序示例

2. 文件浏览器实现

final class Explorer {
    private let fileManager = FileManager.default
    private var currentPath: String
    private var items: [FileItem] = []
    private var navigator: VimTerminalKit.Navigator
    private var stateManager: VimTerminalKit.StateManager
    private var isRunning = true
    private var pathHistory: [String] = []

    init() {
        // IMPORTANT: Order matters for initialization
        self.currentPath = fileManager.currentDirectoryPath
        self.navigator = .init(itemCount: 1, columnsCount: 1)
        self.stateManager = .init { }
        setupStateManager()
    }

    private func setupStateManager() {
        stateManager = .init { [weak self] in
            self?.clearScreen()
            self?.printInterface()
        }
    }

    private func loadCurrentDirectory() {
        Task { [weak self] in
            guard let self else { return }
            try await self.stateManager.withLoading(message: "Loading...") {
                let contents = try self.fileManager.contentsOfDirectory(atPath: self.currentPath)
                self.items = // ... process contents ...
                let totalItems = self.currentPath == "/" ? items.count : items.count + 1
                self.navigator = .init(itemCount: totalItems, columnsCount: 1)
            }
        }
    }

    func start() {
        VimTerminalKit.setup()
        defer { VimTerminalKit.cleanup() }
        
        loadCurrentDirectory()
        
        while isRunning {
            clearScreen()
            printInterface()
            handleInput()
        }
    }
}

3. 菜单实现

struct MenuApp {
    private let navigator: VimTerminalKit.Navigator
    private let stateManager: VimTerminalKit.StateManager
    private var isRunning = true
    private let menuItems = ["Option 1", "Option 2", "Option 3", "Option 4"]
    
    init() {
        self.navigator = .init(itemCount: menuItems.count, columnsCount: 2)
        self.stateManager = .init { }
        setupStateManager()
    }
    
    private func setupStateManager() {
        stateManager = .init { [weak self] in
            self?.redrawInterface()
        }
    }
    
    func start() {
        VimTerminalKit.setup()
        defer { VimTerminalKit.cleanup() }
        
        while isRunning {
            redrawInterface()
            handleInput()
        }
    }
    
    private func redrawInterface() {
        // ... draw menu interface ...
    }
}

常见陷阱

初始化问题

❌ 不要在属性初始化器中使用 self
❌ 不要在属性初始化中直接设置回调
❌ 不要在属性初始化之前访问它们
✅ 首先初始化属性，然后设置回调
✅ 使用正确的初始化顺序
✅ 在单独的设置方法中设置复杂逻辑

导航问题

❌ 当项目更改时，不要忘记更新导航器
❌ 不要混合列数（坚持使用 1 列或 2 列以上）
✅ 当内容更改时，始终更新导航器项目计数
✅ 文件浏览器使用 columnsCount: 1
✅ 网格布局使用 columnsCount: 2+

高级功能

终端控制

// Screen control
print(VimTerminalKit.Terminal.Control.clearScreen)

// Cursor control
print(VimTerminalKit.Terminal.Control.hideCursor)
print(VimTerminalKit.Terminal.Control.showCursor)

// Movement
print(VimTerminalKit.Terminal.Control.up)
print(VimTerminalKit.Terminal.Control.down)

状态管理

// Progress indication
stateManager.startLoading(message: "Step 1")
// ... work ...
stateManager.updateLoadingMessage("Step 2")
// ... work ...
stateManager.stopLoading()

// Async operations
await stateManager.withLoading(message: "Processing...") {
    try await someAsyncWork()
}

最佳实践

设置和清理
- 始终在启动前调用 VimTerminalKit.setup()
- 始终在设置后使用 defer { VimTerminalKit.cleanup() }
内存管理
- 在闭包中使用 [weak self]
- 当应用程序终止时清理资源
错误处理
- 适当处理所有异步操作
- 在错误期间提供用户反馈

贡献

欢迎贡献！请按照以下步骤

Fork 仓库
创建你的功能分支 (git checkout -b feature/AmazingFeature)
提交你的更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开一个拉取请求

在提交拉取请求之前，请阅读我们的贡献指南。

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

灵感来自 Vim 的导航系统
使用 Swift 的现代并发功能构建