inquirer-form

English | 简体中文

一个基于 Vue 3 的可视化表单设计器和运行时库，专为 Inquirer.js 打造，实现 Web 表单与命令行交互的完美统一。

✨ 特性

• 🎨 可视化设计器 - 拖拽式表单设计，所见即所得
• 🔄 多端统一 - 一套 Schema 同时驱动 Web 表单和 CLI 交互
• 🚀 开箱即用 - 内置 9 种 Inquirer 专属控件
• 🎯 类型安全 - 完整的 TypeScript 类型定义
• 🌍 国际化 - 内置中英文支持
• 🔌 灵活扩展 - 支持自定义控件和主题
• 📦 轻量级 - 基于 agilebuilder-form 构建

📦 安装

npm install inquirer-form

必需依赖

本包需要 agilebuilder-form 作为核心依赖：

npm install agilebuilder-form

注意：vue-i18n 已内置在本包中，无需单独安装。

Peer Dependencies

确保安装以下对等依赖：

npm install vue@^3.5.0 element-plus@^2.11.7 vuedraggable@^4.1.0

导入样式

别忘了在应用中导入所需的 CSS 文件：

// 导入 inquirer-form 样式
import 'inquirer-form/style.css'

// 导入 agilebuilder-form 样式
import 'agilebuilder-form/dist/style.css'

// 导入 Element Plus 样式
import 'element-plus/dist/index.css'

🎯 使用场景

CLI 工具开发

• 项目脚手架的配置向导
• 命令行工具的参数收集
• 批量操作的确认流程

Web 应用表单

• 管理后台的配置表单
• 用户注册和设置页面
• 数据录入和编辑界面

多端统一场景

• DevOps 工具（CLI 操作 + Web 管理）
• 配置管理系统（命令行配置 + Web 可视化）
• 自动化脚本（CLI 执行 + Web 监控）

🚀 快速开始

1. 安装插件（可选）

如果使用默认导出，i18n 将自动安装：

import InquirerForm from 'inquirer-form'
import { createApp } from 'vue'

const app = createApp(App)
app.use(InquirerForm) // 自动安装 i18n 并注册组件

或手动注册控件：

import { registerInquirerControls } from 'inquirer-form'

// 注册所有 Inquirer 控件
registerInquirerControls()

2. 导入样式

// main.ts 或 App.vue
import 'inquirer-form/style.css'
import 'agilebuilder-form/dist/style.css'
import 'element-plus/dist/index.css'

3. 使用设计器

<script setup lang="ts">
import { InquirerFormDesigner, createInquirerSampleControls } from 'inquirer-form'
import { SchemaEngine } from 'agilebuilder-form'

const engine = new SchemaEngine()

// 可选：加载示例表单
engine.getSchema().controls = createInquirerSampleControls((key) => key)
</script>

<template>
  <InquirerFormDesigner :engine="engine" />
</template>

4. Web 端运行时

<script setup lang="ts">
import { ref } from 'vue'
import { InquirerFormRuntime } from 'inquirer-form'
import type { FormData, FormSchema } from 'agilebuilder-form'

const formData = ref<FormData>({})
const schema: FormSchema = {
  controls: [
    // 从设计器获取或手动定义
  ]
}
</script>

<template>
  <InquirerFormRuntime v-model="formData" :schema="schema" />
</template>

5. 转换为 Inquirer

import inquirer from 'inquirer'
import { schemaToInquirer } from 'inquirer-form'
import type { FormSchema } from 'agilebuilder-form'

const schema: FormSchema = {
  // 从设计器或 API 获取
}

// 转换为 Inquirer 问题集
const questions = schemaToInquirer(schema)

// 在命令行中使用
const answers = await inquirer.prompt(questions)
console.log(answers)

6. 体验 Playground

git clone <repository-url>
cd inquirer-form
npm install
npm run dev

访问浏览器查看集成了设计器、Web 预览和 Inquirer 导出的完整演示。

📚 API 文档

组件

InquirerFormDesigner

可视化表单设计器组件。

Props:

• engine?: SchemaEngine - Schema 引擎实例（可选，默认创建新实例）
• seedSample?: boolean - 是否加载示例表单（默认 false）
• autoRegisterControls?: boolean - 是否自动注册控件（默认 true）

示例:

<InquirerFormDesigner 
  :engine="engine" 
  :seedSample="true"
  :autoRegisterControls="true"
/>

InquirerFormRuntime

Web 端表单运行时组件。

Props:

• schema: FormSchema - 表单 Schema（必需）
• modelValue: FormData - 表单数据（v-model）

Events:

• update:modelValue - 表单数据更新事件

示例:

<InquirerFormRuntime v-model="formData" :schema="schema" />

InquirerFormPlayground

完整的 Playground 组件，包含设计器、运行时和导出功能。

示例:

<InquirerFormPlayground />

函数

registerInquirerControls()

注册所有内置的 Inquirer 控件到全局注册表。

import { registerInquirerControls } from 'inquirer-form'

registerInquirerControls()

schemaToInquirer(schema, options?)

将表单 Schema 转换为 Inquirer 问题集。

参数:

• schema: FormSchema - 表单 Schema
• options?: TransformOptions - 转换选项
  • includeDisabled?: boolean - 是否包含禁用的字段（默认 false）

返回:

• InquirerQuestion[] - Inquirer 问题数组

示例:

import { schemaToInquirer } from 'inquirer-form'

const questions = schemaToInquirer(schema, {
  includeDisabled: false
})

createInquirerSampleControls(t)

创建示例表单控件。

参数:

• t: (key: string) => string - 国际化翻译函数

返回:

• SchemaNode[] - Schema 节点数组

示例:

import { createInquirerSampleControls } from 'inquirer-form'

const controls = createInquirerSampleControls((key) => key)
engine.getSchema().controls = controls

类型

InquirerPromptType

支持的 Inquirer 提示类型。

type InquirerPromptType =
  | 'input'      // 文本输入
  | 'number'     // 数字输入
  | 'confirm'    // 确认（是/否）
  | 'list'       // 单选列表
  | 'rawlist'    // 原始列表
  | 'expand'     // 展开选择
  | 'checkbox'   // 多选框
  | 'password'   // 密码输入
  | 'editor'     // 编辑器

InquirerQuestion

Inquirer 问题对象接口。

interface InquirerQuestion {
  type: InquirerPromptType
  name: string
  message: string
  default?: any
  prefix?: string
  suffix?: string
  pageSize?: number
  loop?: boolean
  mask?: string | boolean
  choices?: InquirerChoice[]
  whenExpression?: string
  validateExpression?: string
  filterExpression?: string
  transformerExpression?: string
  metadata?: Record<string, any>
}

InquirerChoice

选择项接口（用于 list、checkbox 等）。

interface InquirerChoice {
  name: string    // 显示文本
  value: string   // 实际值
  short?: string  // 简短描述
}

🎨 内置控件

| 控件类型 | 说明 | Inquirer 类型 | |---------|------|--------------| | Input | 文本输入框 | input | | Password | 密码输入框 | password | | Number | 数字输入框 | number | | Confirm | 确认框 | confirm | | List | 单选列表 | list | | RawList | 原始列表 | rawlist | | Expand | 展开选择 | expand | | Checkbox | 多选框 | checkbox | | Editor | 多行编辑器 | editor |

🔧 高级用法

自定义控件

import { registry } from 'agilebuilder-form'
import type { ControlMeta } from 'agilebuilder-form'

const customControl: ControlMeta = {
  type: 'custom-input',
  label: '自定义输入',
  component: CustomInputComponent,
  initialSchema: () => ({
    id: generateId(),
    type: 'custom-input',
    field: '',
    props: {}
  })
}

// 注册自定义控件
registry.register(customControl)

表达式支持

Schema 支持多种表达式字段，用于动态控制：

{
  type: 'input',
  field: 'email',
  props: {
    message: '请输入邮箱',
    // 条件显示
    whenExpression: "return answers.needEmail === true",
    // 验证
    validateExpression: "return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(input) || '请输入有效的邮箱'",
    // 过滤
    filterExpression: "return input.trim().toLowerCase()",
    // 转换显示
    transformerExpression: "return input.replace(/@.*/, '@***')"
  }
}

与 Inquirer.js 集成

完整的 CLI 集成示例：

import inquirer from 'inquirer'
import { schemaToInquirer } from 'inquirer-form'
import type { FormSchema } from 'agilebuilder-form'

// 从文件或 API 加载 Schema
const schema: FormSchema = require('./form-schema.json')

// 转换为 Inquirer 问题
const questions = schemaToInquirer(schema)

// 处理表达式（将字符串转换为函数）
const processedQuestions = questions.map(q => ({
  ...q,
  when: q.whenExpression 
    ? new Function('answers', q.whenExpression) 
    : undefined,
  validate: q.validateExpression
    ? new Function('input', 'answers', q.validateExpression)
    : undefined,
  filter: q.filterExpression
    ? new Function('input', 'answers', q.filterExpression)
    : undefined,
  transformer: q.transformerExpression
    ? new Function('input', 'answers', 'flags', q.transformerExpression)
    : undefined
}))

// 执行询问
const answers = await inquirer.prompt(processedQuestions)
console.log('用户输入:', answers)

📝 开发

脚本命令

| 命令 | 说明 | |------|------| | npm run dev | 启动开发服务器（Playground） | | npm run build | 构建生产版本 | | npm run type-check | TypeScript 类型检查 | | npm run test:unit | 运行单元测试 | | npm run docs:dev | 启动文档开发服务器 | | npm run docs:build | 构建文档 |

构建产物

运行 npm run build 后，将生成以下文件：

dist/
├── inquirer-form.es.js      # ES Module
├── inquirer-form.umd.js     # UMD Module
├── inquirer-form.css        # 样式文件
└── index.d.ts               # TypeScript 类型声明

发布到 npm

1. 确保已登录 npm 账号
2. 更新版本号：npm version patch|minor|major
3. 构建：npm run build
4. 发布：npm publish --access public

🔗 相关项目

• agilebuilder-form - 底层表单引擎
• Inquirer.js - 命令行交互库
• Element Plus - UI 组件库
• Vue 3 - 渐进式 JavaScript 框架

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

如有问题或建议，请通过 GitHub Issues 联系我们。