console-rendering

控制台渲染系统用法

本指南介绍基于结构体标签的控制台渲染系统。

结构体标签支持

使用 console 结构体标签控制渲染行为：

• header:"Name" - 设置字段的显示名称（用于结构体和表格）
• title:"Section Title" - 设置嵌套结构体、切片或映射的标题
• format:"type" - 设置字段值的格式类型
  • format:number - 将整数格式化为易读的数字（例如，“1k”、“1.2M”）
  • format:cost - 将浮点数格式化为带 $ 前缀的货币（例如，“$1.234”）
• omitempty - 字段为零值时跳过该字段
• "-" - 始终跳过该字段

用法示例

type Overview struct {
    RunID    int64  `console:"header:Run ID"`
    Workflow string `console:"header:Workflow"`
    Status   string `console:"header:Status"`
    Duration string `console:"header:Duration,omitempty"`
}

data := Overview{
    RunID:    12345,
    Workflow: "test-workflow",
    Status:   "completed",
    Duration: "5m30s",
}

// Simple rendering
fmt.Print(console.RenderStruct(data))

// Output:
//   Run ID  : 12345
//   Workflow: test-workflow
//   Status  : completed
//   Duration: 5m30s

格式标签示例

数字格式

type Metrics struct {
    TokenUsage int `console:"header:Token Usage,format:number"`
    Errors     int `console:"header:Errors"`
}

data := Metrics{
    TokenUsage: 250000,
    Errors:     5,
}

// Renders as:
//   Token Usage: 250k
//   Errors     : 5

费用格式

type Billing struct {
    Cost float64 `console:"header:Estimated Cost,format:cost"`
}

data := Billing{
    Cost: 1.234,
}

// Renders as:
//   Estimated Cost: $1.234

渲染行为

结构体

结构体会渲染为对齐良好的键值对。

切片

结构体切片会自动渲染为表格：

type Job struct {
    Name       string `console:"header:Name"`
    Status     string `console:"header:Status"`
    Conclusion string `console:"header:Conclusion,omitempty"`
}

jobs := []Job{
    {Name: "build", Status: "completed", Conclusion: "success"},
    {Name: "test", Status: "in_progress", Conclusion: ""},
}

fmt.Print(console.RenderStruct(jobs))

渲染结果：

Name  | Status      | Conclusion
----- | ----------- | ----------
build | completed   | success
test  | in_progress | -

映射

映射会渲染为 Markdown 风格的标题，并附带键值对。

特殊类型处理

time.Time

time.Time 字段会自动格式化为 "2006-01-02 15:04:05"。使用 omitempty 时，零值时间会被视为空值。

未导出字段

渲染系统会在尝试访问字段值前检查 CanInterface()，从而安全地处理未导出的结构体字段。