# axon

**Repository Path**: muleiwu/axon

## Basic Information

- **Project Name**: axon
- **Description**: Axon 是一个用于构建交互式命令行应用的轻量级 Go 库，提供了简洁易用的终端交互功能。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-15
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Axon

Axon 是一个用于构建交互式命令行应用的轻量级 Go 库，提供了简洁易用的终端交互功能。

## 功能特点

- 简单易用的 API，专注于提供优质的终端交互体验
- 支持多种交互方式：普通问答、确认选择、密码输入、电话号码输入、单选、多选、搜索选择、键盘导航选择、多行文本、强类型输入、危险确认、表单向导、进度条和加载动画
- 内置数据验证和格式化功能
- 支持默认值设置
- 每种交互模式都有独立接口和默认实现，方便按需替换
- 电话号码自动脱敏处理，保护用户隐私
- 彩色输出支持，增强视觉体验

> 已经在 毫秒镜像 CLI配置工具 应用（如下）

![毫秒镜像配置工具截图](./_image/Snipaste_2025-09-15_16-42-20.png)

## 安装

```bash
go get github.com/muleiwu/axon
```

## 快速开始

```go
package main

import (
	"fmt"
	"github.com/muleiwu/axon"
	"github.com/muleiwu/axon/pkg/question"
)

func main() {
	// 普通问题
	name := axon.Question("请输入您的姓名: ", "")
	fmt.Printf("您好，%s!\n", name)
	
	// 确认问题
	proceed := axon.Confirm("是否继续? (y/n) ", true)
	if proceed {
		fmt.Println("继续执行...")
	} else {
		fmt.Println("已取消")
		return
	}
	
	// 密码输入（隐藏显示）
	password := axon.Password("请输入密码: ", "")
	fmt.Println("密码已保存")
	
	// 电话号码（带验证和脱敏）
	phone := axon.PhoneNumber("请输入手机号: ", "")
	fmt.Println("手机号已保存")
	
	// 选择列表
	items := []question.SelectionItem{
		{Label: "选项一", Description: "这是第一个选项", Value: "option1"},
		{Label: "选项二", Description: "这是第二个选项", Value: "option2"},
		{Label: "选项三", Description: "这是第三个选项", Value: "option3"},
	}
	selected := axon.Selection("请选择一个选项:", items)
	
	if selected == "exit" {
		fmt.Println("您选择了退出")
	} else {
		fmt.Printf("您选择了: %s\n", selected)
	}

	// 多选
	selectedValues := axon.MultiSelect("请选择多个选项:", items)
	fmt.Printf("您选择了: %v\n", selectedValues)

	// 强类型输入
	age := axon.Number("请输入年龄: ", 18)
	email := axon.Email("请输入邮箱: ", "")
	fmt.Println(age, email)

	// 表单向导
	result := axon.Form("创建用户", []axon.FormField{
		{Name: "name", Question: "姓名: ", Kind: axon.FieldText, Required: true},
		{Name: "email", Question: "邮箱: ", Kind: axon.FieldEmail, Required: true},
		{Name: "admin", Question: "是否管理员? ", Kind: axon.FieldConfirm},
	})
	fmt.Printf("%#v\n", result)
}
```

## API 参考

### 普通问题

```go
func Question(question string, defaultValue string) string
```

询问用户普通问题并获取文本输入。

- `question`: 要显示给用户的问题文本
- `defaultValue`: 默认值，当用户直接按回车时使用
- 返回: 用户输入的字符串

### 确认问题

```go
func Confirm(question string, defaultValue bool) bool
```

询问用户确认问题，获取 yes/no 回答。

- `question`: 要显示给用户的问题文本
- `defaultValue`: 默认值，当用户直接按回车时使用
- 返回: 用户的选择结果(true/false)

### 密码输入

```go
func Password(question string, defaultValue string) string
```

询问用户密码，输入过程中密码会被隐藏显示。

- `question`: 要显示给用户的问题文本
- `defaultValue`: 默认值，当用户直接按回车时使用
- 返回: 用户输入的密码字符串

### 电话号码输入

```go
func PhoneNumber(question string, defaultValue string) string
```

询问用户电话号码，包含格式验证功能。输入后自动脱敏处理，保护用户隐私。

- `question`: 要显示给用户的问题文本
- `defaultValue`: 默认值，当用户直接按回车时使用
- 返回: 经过验证的电话号码字符串

### 选择列表

```go
func Selection(question string, items []SelectionItem) string
```

让用户从列表中选择一项。

- `question`: 要显示给用户的问题文本
- `items`: 选择项列表
- 返回: 用户选择的项目的Value，如果选择退出则返回"exit"

### 多选列表

```go
func MultiSelect(question string, items []SelectionItem) []string
```

让用户一次选择多个选项。支持 `1,3-5` 和 `all` 输入格式；用户选择退出时返回空切片。

### 搜索选择

```go
func SearchSelect(question string, items []SelectionItem) string
```

先根据关键字过滤选项，再让用户从匹配项中选择一项。

### 键盘导航选择

```go
func KeyboardSelect(question string, items []SelectionItem) string
```

使用上下键或 `j/k` 移动，`Enter` 确认，`q` 退出。

### 自定义校验输入

```go
func ValidatedQuestion(question string, defaultValue string, validators ...Validator) string
```

使用一个或多个自定义校验器校验文本输入。校验器返回 `error` 时会重新询问。

### 强类型输入

```go
func Number(question string, defaultValue int) int
func Email(question string, defaultValue string) string
func URL(question string, defaultValue string) string
func Path(question string, defaultValue string, mustExist bool) string
func DateTime(question string, defaultValue time.Time, layout string) time.Time
```

提供整数、邮箱、URL、路径和时间输入。`DateTime` 的 `layout` 为空时使用默认格式 `2006-01-02 15:04:05`。

### 多行文本

```go
func MultiLine(question string, defaultValue string) string
```

读取多行文本，输入单独一行 `.` 结束。

### 危险确认

```go
func DangerousConfirm(question string, expected string) bool
```

要求用户准确输入 `expected` 后才返回 `true`，适合删除、覆盖、发布等危险操作。

### 表单向导

```go
func Form(title string, fields []FormField) FormResult
func Wizard(title string, fields []FormField) FormResult
```

按字段顺序收集多个输入，返回 `map[string]any`。`Wizard` 是 `Form` 的语义化别名。

### 进度交互

```go
func Spinner(message string) SpinnerController
func Progress(total int, message string) ProgressReporter
```

`Spinner` 用于不确定时长任务，`Progress` 用于确定总量任务。

## 自定义选择项

创建选择列表时，可以使用 `SelectionItem` 结构定义选项：

```go
type SelectionItem struct {
	Label       string // 显示的标签
	Description string // 描述信息
	Value       string // 实际值
	Disabled    bool   // 是否禁用
}
```

## 替换默认实现

每种交互模式都在 `pkg/interfaces` 中定义了独立接口，默认实现位于 `pkg/question`。你可以通过 setter 替换任意模式：

```go
type MyQuestioner struct{}

func (MyQuestioner) Ask(question string, defaultValue string) string {
	return defaultValue
}

func main() {
	axon.SetQuestioner(MyQuestioner{})
	name := axon.Question("请输入姓名: ", "axon")
	fmt.Println(name)
}
```

## 许可证

本项目采用 [LICENSE](LICENSE) 许可证开源。