@ark-code/clack

@ark-code/clack

轻量级的交互式命令行提示核心库

@ark-code/clack 是一个提供命令行交互提示原语的 TypeScript 库，为构建更高级的 CLI 工具提供基础能力。它提供了一组可扩展的提示类和工具函数，支持文本输入、确认、单选、多选等多种交互方式。

特性

• 🎯 核心提示组件 - 提供完整的提示类型支持
• 🎨 高度可定制 - 基于基类轻松扩展自定义提示
• ⌨️ 智能键盘交互 - 支持标准键和 vim 风格快捷键（hjkl）
• 🔄 状态管理 - 内置状态机处理提示生命周期
• 📦 零配置 - 开箱即用的基础提示组件
• 🪶 轻量级 - 最小化依赖，核心功能聚焦

安装

pnpm add @ark-code/clack

核心组件

Prompt（基类）

所有提示组件的基类，提供：

• 事件驱动架构（发布-订阅模式）
• 状态管理（initial → active → submit/cancel/error）
• 键盘输入处理
• 终端渲染控制
• 验证机制

TextPrompt（文本输入）

单行文本输入提示，支持光标显示和默认值。

import { TextPrompt } from "@ark-code/clack";

const prompt = new TextPrompt({
  render() {
    return `请输入您的名字: ${this.valueWithCursor}`;
  },
  placeholder: "输入名字",
  defaultValue: "John",
  validate(value) {
    if (!value) return "名字不能为空";
  },
});

const name = await prompt.prompt();

ConfirmPrompt（确认提示）

是/否二选一的确认提示，支持方向键和 y/n 快捷键。

import { ConfirmPrompt } from "@ark-code/clack";

const prompt = new ConfirmPrompt({
  render() {
    return `确认继续吗？`;
  },
  active: "是",
  inactive: "否",
  initialValue: true,
});

const confirmed = await prompt.prompt();

SelectPrompt（单选）

从列表中选择单个选项，支持方向键导航和循环滚动。

import { SelectPrompt } from "@ark-code/clack";

const prompt = new SelectPrompt({
  render() {
    return `选择一个颜色:\n${this.options
      .map((opt, i) =>
        i === this.cursor ? `> ${opt.label}` : `  ${opt.label}`
      )
      .join("\n")}`;
  },
  options: [
    { value: "red", label: "红色" },
    { value: "green", label: "绿色" },
    { value: "blue", label: "蓝色" },
  ],
  initialValue: "red",
});

const color = await prompt.prompt();

MultiSelectPrompt（多选）

从列表中选择多个选项，使用空格键切换选中状态。

import { MultiSelectPrompt } from "@ark-code/clack";

const prompt = new MultiSelectPrompt({
  render() {
    return `选择喜欢的水果（空格选择）:\n${this.options
      .map(
        (opt, i) =>
          `${i === this.cursor ? ">" : " "} [${
            this.value.includes(opt.value) ? "x" : " "
          }] ${opt.label}`
      )
      .join("\n")}`;
  },
  options: [
    { value: "apple", label: "苹果" },
    { value: "banana", label: "香蕉" },
    { value: "orange", label: "橙子" },
  ],
  initialValues: ["apple"],
  required: true,
});

const fruits = await prompt.prompt();

GroupMultiSelectPrompt（分组多选）

支持选项分组的多选提示，可展开/折叠分组。

import { GroupMultiSelectPrompt } from "@ark-code/clack";

const prompt = new GroupMultiSelectPrompt({
  render() {
    // 自定义渲染逻辑
  },
  options: {
    前端: [
      { value: "react", label: "React" },
      { value: "vue", label: "Vue" },
    ],
    后端: [
      { value: "node", label: "Node.js" },
      { value: "python", label: "Python" },
    ],
  },
  required: false,
});

const selections = await prompt.prompt();

PasswordPrompt（密码输入）

密码输入提示，输入内容以掩码字符显示。

import { PasswordPrompt } from "@ark-code/clack";

const prompt = new PasswordPrompt({
  render() {
    return `请输入密码: ${this.valueWithCursor}`;
  },
  mask: "*",
  validate(value) {
    if (value.length < 6) return "密码至少需要 6 个字符";
  },
});

const password = await prompt.prompt();

SelectKeyPrompt（键选择）

通过按键快速选择选项的提示。

import { SelectKeyPrompt } from "@ark-code/clack";

const prompt = new SelectKeyPrompt({
  render() {
    return `请选择操作:\n${this.options
      .map((opt) => `[${opt.value}] ${opt.label}`)
      .join("\n")}`;
  },
  options: [
    { value: "y", label: "确认" },
    { value: "n", label: "取消" },
    { value: "a", label: "全部" },
  ],
});

const action = await prompt.prompt();

工具函数

isCancel

检查用户是否取消了提示操作（通过 Ctrl+C）。

import { TextPrompt, isCancel } from "@ark-code/clack";

const prompt = new TextPrompt({
  /* ... */
});
const result = await prompt.prompt();

if (isCancel(result)) {
  console.log("用户取消了操作");
  process.exit(0);
}

block

创建阻塞式输入监听器，阻止用户输入显示到终端。

import { block } from "@ark-code/clack";

const unblock = block({
  hideCursor: true,
  overwrite: true,
});

// 在这里执行需要阻塞输入的操作

unblock(); // 恢复终端状态

键盘快捷键

所有提示组件都支持以下键盘操作：

• ↑/k - 向上移动
• ↓/j - 向下移动
• ←/h - 向左移动
• →/l - 向右移动
• Space - 空格键（多选中切换选中状态）
• Enter - 确认提交
• Ctrl+C - 取消操作

自定义提示

通过继承 Prompt 基类创建自定义提示组件：

import Prompt, { type PromptOptions } from "@ark-code/clack";

interface MyPromptOptions extends PromptOptions<MyPrompt> {
  // 自定义选项
}

class MyPrompt extends Prompt {
  constructor(opts: MyPromptOptions) {
    super(opts);

    // 监听事件
    this.on("cursor", (key) => {
      // 处理光标移动
    });

    this.on("value", () => {
      // 处理值变化
    });
  }

  // 实现自定义逻辑
}

API 参考

Prompt 类

构造函数选项

interface PromptOptions<Self> {
  render(this: Self): string | void;
  placeholder?: string;
  initialValue?: any;
  validate?: (value: any) => string | void;
  input?: NodeJS.ReadableStream;
  output?: NodeJS.WritableStream;
  debug?: boolean;
}

生命周期事件

• cursor - 光标移动时触发
• value - 值变化时触发
• confirm - 确认操作时触发
• finalize - 提示结束时触发

状态类型

type State = "initial" | "active" | "error" | "submit" | "cancel";

依赖项

• picocolors - 终端颜色
• sisteransi - ANSI 转义序列
• wrap-ansi - 文本换行
• is-unicode-supported - Unicode 支持检测

与 @ark-code/prompt 的关系

• @ark-code/clack：提供底层提示原语和基础类
• @ark-code/prompt：构建在 @ark-code/clack 之上，提供样式化的高级提示函数

如果您需要开箱即用的美观提示界面，推荐使用 @ark-code/prompt。如果您需要构建自定义提示组件，@ark-code/clack 是理想选择。

许可证

MIT

作者

Derrick [e-mail]