@ark-x/prompt

美观且易用的命令行交互提示库

@ark-x/prompt 是一个构建在 @ark-x/clack 之上的高级命令行交互库，提供开箱即用的样式化提示函数。它专注于提供一致、美观的用户体验，无需复杂配置即可创建专业的 CLI 应用。

特性

• 🎨 美观设计 - 统一的视觉风格和颜色主题
• 📦 开箱即用 - 无需配置即可使用
• 🔧 完整功能 - 涵盖所有常用的 CLI 交互场景
• 🎯 类型安全 - 完整的 TypeScript 类型支持
• 🚀 轻量高效 - 最小化依赖，性能优异
• ♿ 优雅降级 - 自动适配终端环境

安装

pnpm add @ark-x/prompt

快速开始

import { intro, outro, text, confirm, select } from "@ark-x/prompt";

async function main() {
  intro("欢迎使用我的 CLI 工具");

  const name = await text({
    message: "请输入您的名字",
    placeholder: "John Doe",
  });

  const shouldContinue = await confirm({
    message: "是否继续？",
  });

  if (shouldContinue) {
    const color = await select({
      message: "选择您喜欢的颜色",
      options: [
        { value: "red", label: "红色" },
        { value: "green", label: "绿色" },
        { value: "blue", label: "蓝色" },
      ],
    });

    outro(`您选择了 ${color}，感谢使用！`);
  }
}

main();

API 文档

提示函数

text

文本输入提示，用于收集用户的单行文本输入。

import { text } from "@ark-x/prompt";

const name = await text({
  message: "请输入您的名字",
  placeholder: "John Doe",
  initialValue: "",
  defaultValue: "Guest",
  validate: (value) => {
    if (!value) return "名字不能为空";
  },
});

选项：

• message (string, 必需) - 提示消息
• placeholder (string) - 占位符文本
• initialValue (string) - 初始值
• defaultValue (string) - 默认值
• validate (function) - 验证函数，返回错误消息或 void

password

密码输入提示，输入内容会被掩码字符替换。

import { password } from "@ark-x/prompt";

const pwd = await password({
  message: "请输入密码",
  validate: (value) => {
    if (value.length < 6) return "密码至少需要 6 个字符";
  },
});

选项：

• message (string, 必需) - 提示消息
• validate (function) - 验证函数

confirm

确认提示，用于获取用户的是/否选择。

import { confirm } from "@ark-x/prompt";

const shouldContinue = await confirm({
  message: "是否继续？",
  active: "是",
  inactive: "否",
  initialValue: true,
});

选项：

• message (string, 必需) - 提示消息
• active (string) - 激活选项文本，默认 "Yes"
• inactive (string) - 未激活选项文本，默认 "No"
• initialValue (boolean) - 初始值，默认 true

select

单选提示，从列表中选择一个选项。

import { select } from "@ark-x/prompt";

const framework = await select({
  message: "选择一个框架",
  options: [
    { value: "react", label: "React", hint: "推荐" },
    { value: "vue", label: "Vue" },
    { value: "angular", label: "Angular" },
  ],
  initialValue: "react",
  maxItems: 5,
});

选项：

• message (string, 必需) - 提示消息
• options (array, 必需) - 选项数组，每项包含 value、label（可选）、hint（可选）
• initialValue (any) - 初始选中的值
• maxItems (number) - 最多显示的项数

selectKey

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

import { selectKey } from "@ark-x/prompt";

const action = await selectKey({
  message: "请选择操作",
  options: [
    { value: "y", label: "确认" },
    { value: "n", label: "取消" },
    { value: "a", label: "全部" },
  ],
});

选项：

• message (string, 必需) - 提示消息
• options (array, 必需) - 选项数组

multiselect

多选提示，从列表中选择多个选项。

import { multiselect } from "@ark-x/prompt";

const features = await multiselect({
  message: "选择需要的功能",
  options: [
    { value: "typescript", label: "TypeScript", hint: "推荐" },
    { value: "eslint", label: "ESLint" },
    { value: "prettier", label: "Prettier" },
  ],
  initialValues: ["typescript"],
  required: true,
  maxItems: 10,
});

选项：

• message (string, 必需) - 提示消息
• options (array, 必需) - 选项数组
• initialValues (array) - 初始选中的值数组
• required (boolean) - 是否至少选择一项，默认 true
• maxItems (number) - 最多显示的项数
• cursorAt (any) - 初始光标位置

groupMultiselect

分组多选提示，支持选项分组的多选。

import { groupMultiselect } from "@ark-x/prompt";

const packages = await groupMultiselect({
  message: "选择要安装的包",
  options: {
    前端框架: [
      { value: "react", label: "React" },
      { value: "vue", label: "Vue" },
    ],
    构建工具: [
      { value: "vite", label: "Vite" },
      { value: "webpack", label: "Webpack" },
    ],
  },
  required: false,
});

选项：

• message (string, 必需) - 提示消息
• options (object, 必需) - 分组选项对象
• initialValues (array) - 初始选中的值数组
• required (boolean) - 是否至少选择一项，默认 true
• cursorAt (any) - 初始光标位置

输出函数

intro

显示 CLI 应用的开始标题。

import { intro } from "@ark-x/prompt";

intro("欢迎使用我的 CLI 工具");

outro

显示 CLI 应用的结束消息。

import { outro } from "@ark-x/prompt";

outro("感谢使用！");

log

输出日志消息，支持多种类型。

import { log } from "@ark-x/prompt";

log.info("这是一条信息");
log.success("操作成功！");
log.warning("这是一个警告");
log.error("发生错误！");
log.step("执行步骤 1");
log.message("普通消息");

方法：

• log.info(message) - 信息消息
• log.success(message) - 成功消息
• log.warning(message) - 警告消息
• log.error(message) - 错误消息
• log.step(message) - 步骤消息
• log.message(message, options) - 自定义消息

note

显示带标题的多行消息框。

import { note } from "@ark-x/prompt";

note("这是消息内容\n可以多行显示", "标题");

box

显示一个装饰性的消息框。

import { box } from "@ark-x/prompt";

box("欢迎使用 @ark-x/prompt！");

cancel

显示取消消息并退出进程。

import { cancel } from "@ark-x/prompt";

cancel("操作已取消");

taskLog

显示任务状态日志。

import { taskLog } from "@ark-x/prompt";

taskLog({
  message: "构建项目",
  status: "active", // 'active' | 'error' | 'success' | 'cancel'
});

进度指示器

spinner

创建一个加载动画。

import { spinner } from "@ark-x/prompt";

const s = spinner();
s.start("正在加载...");

// 执行异步操作
await someAsyncTask();

s.stop("加载完成");

方法：

• spinner.start(message?) - 开始显示加载动画
• spinner.stop(message?, code?) - 停止加载动画（code: 0=成功, 1=取消, 2=错误）
• spinner.message(message) - 更新加载消息

tasks

执行一组任务，每个任务都有自己的 spinner。

import { tasks } from "@ark-x/prompt";

await tasks([
  {
    title: "安装依赖",
    task: async (message) => {
      await installDependencies();
      message("依赖安装完成");
    },
  },
  {
    title: "构建项目",
    task: async () => {
      await build();
      return "构建成功";
    },
    enabled: true,
  },
]);

任务选项：

• title (string, 必需) - 任务标题
• task (function, 必需) - 任务函数，可以返回消息或使用 message 回调
• enabled (boolean) - 是否启用该任务，默认 true

提示组

group

将多个提示组合成一个组，按顺序执行并返回所有结果。

import { group, text, confirm, select } from "@ark-x/prompt";

const results = await group(
  {
    name: () => text({ message: "请输入名字" }),

    age: () =>
      text({
        message: "请输入年龄",
        validate: (value) => {
          if (isNaN(Number(value))) return "年龄必须是数字";
        },
      }),

    // 可以访问之前的结果
    shouldContinue: ({ results }) =>
      confirm({
        message: `${results.name}，是否继续？`,
      }),

    color: ({ results }) => {
      if (!results.shouldContinue) return;
      return select({
        message: "选择颜色",
        options: [
          { value: "red", label: "红色" },
          { value: "blue", label: "蓝色" },
        ],
      });
    },
  },
  {
    onCancel: ({ results }) => {
      cancel("操作已取消");
    },
  }
);

console.log(results); // { name: 'John', age: '25', shouldContinue: true, color: 'red' }

选项：

• onCancel (function) - 当某个提示被取消时的回调函数

工具函数

isCancel

检查用户是否取消了提示（按 Ctrl+C）。

import { text, isCancel } from "@ark-x/prompt";

const name = await text({ message: "请输入名字" });

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

键盘快捷键

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

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

完整示例

基础 CLI 工具

import {
  intro,
  outro,
  text,
  select,
  multiselect,
  confirm,
  spinner,
  isCancel,
  cancel,
} from "@ark-x/prompt";

async function main() {
  console.clear();

  intro("创建新项目");

  const project = await group(
    {
      name: () =>
        text({
          message: "项目名称",
          placeholder: "my-app",
          validate: (value) => {
            if (!value) return "项目名称不能为空";
          },
        }),

      type: () =>
        select({
          message: "项目类型",
          options: [
            { value: "web", label: "Web 应用" },
            { value: "cli", label: "CLI 工具" },
            { value: "lib", label: "库" },
          ],
        }),

      features: () =>
        multiselect({
          message: "选择功能",
          options: [
            { value: "typescript", label: "TypeScript", hint: "推荐" },
            { value: "eslint", label: "ESLint" },
            { value: "prettier", label: "Prettier" },
            { value: "test", label: "测试框架" },
          ],
          required: false,
        }),

      install: () =>
        confirm({
          message: "是否立即安装依赖？",
        }),
    },
    {
      onCancel: () => {
        cancel("项目创建已取消");
        process.exit(0);
      },
    }
  );

  const s = spinner();
  s.start("正在创建项目...");

  // 模拟项目创建
  await new Promise((resolve) => setTimeout(resolve, 2000));

  s.stop("项目创建完成！");

  outro(`成功创建项目 ${project.name}！`);
}

main().catch(console.error);

使用 tasks 执行多个任务

import { intro, outro, tasks } from "@ark-x/prompt";

async function build() {
  intro("开始构建");

  await tasks([
    {
      title: "清理构建目录",
      task: async () => {
        await cleanDist();
      },
    },
    {
      title: "编译 TypeScript",
      task: async (message) => {
        await compileTS();
        message("TypeScript 编译完成");
      },
    },
    {
      title: "打包资源",
      task: async () => {
        await bundleAssets();
        return "资源打包完成";
      },
    },
  ]);

  outro("构建完成！");
}

build();

与 @ark-x/clack 的关系

• @ark-x/clack：提供底层提示原语和基础类，适合构建自定义提示组件
• @ark-x/prompt：构建在 @ark-x/clack 之上，提供样式化的高级提示函数，开箱即用

如果您需要自定义提示组件的渲染逻辑和行为，可以使用 @ark-x/clack。

依赖项

• @ark-x/clack - 核心提示引擎
• picocolors - 终端颜色
• sisteransi - ANSI 转义序列
• wrap-ansi - 文本换行
• is-unicode-supported - Unicode 支持检测

许可证

MIT

作者

Derrick [email protected]