# Excel导出工具文档

## 概述

Excel导出工具提供了将数据导出到Excel文件的功能，支持结构体切片、自定义格式化、多工作表等特性。通过工厂模式，外部项目可以方便地使用Excel导出功能。

## 功能特性

- **黑盒模式**：提供直接调用的方法，无需获取Excel对象
- **延迟初始化**：Excel导出器在首次使用时才创建
- **支持结构体切片**：自动将结构体切片转换为Excel行数据
- **支持嵌套字段**：支持访问嵌套结构体字段（如 "User.Name"）
- **自定义格式化**：支持自定义字段值的格式化函数
- **自动列宽**：自动调整列宽以适应内容
- **表头样式**：自动应用表头样式（加粗、背景色等）
- **智能工作表管理**：自动处理工作表的创建和删除，避免产生空sheet
- **ExportData接口**：支持实现ExportData接口进行高级定制
- **空数据处理**：即使数据为空（nil或空切片），也会正常生成表头
- **统一接口**：只暴露 `ExportToWriter` 一个核心方法

## 使用方法

### 1. 创建工厂

```go
import "git.toowon.com/jimmy/go-common/factory"

// 从配置文件创建
fac, err := factory.NewFactoryFromFile("./config.json")

// 或Excel导出不需要配置，可以传nil
fac := factory.NewFactory(nil)
```

### 2. 导出结构体切片到文件

```go
// 定义结构体
type User struct {
    ID        int       `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
    Status    int       `json:"status"`
}

// 准备数据
users := []User{
    {ID: 1, Name: "Alice", Email: "alice@example.com", CreatedAt: time.Now(), Status: 1},
    {ID: 2, Name: "Bob", Email: "bob@example.com", CreatedAt: time.Now(), Status: 1},
}

// 定义导出列
columns := []factory.ExportColumn{
    {Header: "ID", Field: "ID", Width: 10},
    {Header: "姓名", Field: "Name", Width: 20},
    {Header: "邮箱", Field: "Email", Width: 30},
    {Header: "创建时间", Field: "CreatedAt", Width: 20},
    {Header: "状态", Field: "Status", Width: 10},
}

// 导出到文件
err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
if err != nil {
    log.Fatal(err)
}
```

### 3. 导出到HTTP响应

```go
import "net/http"

func exportUsersHandler(w http.ResponseWriter, r *http.Request) {
    fac, _ := factory.NewFactoryFromFile("./config.json")
    
    users := []User{
        {ID: 1, Name: "Alice", Email: "alice@example.com", CreatedAt: time.Now(), Status: 1},
        {ID: 2, Name: "Bob", Email: "bob@example.com", CreatedAt: time.Now(), Status: 1},
    }
    
    columns := []factory.ExportColumn{
        {Header: "ID", Field: "ID"},
        {Header: "姓名", Field: "Name"},
        {Header: "邮箱", Field: "Email"},
    }
    
    // 设置HTTP响应头
    w.Header().Set("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
    w.Header().Set("Content-Disposition", "attachment; filename=users.xlsx")
    
    // 导出到响应
    err := fac.ExportToExcel(w, "用户列表", columns, users)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
}
```

### 4. 使用格式化函数

```go
import "git.toowon.com/jimmy/go-common/excel"

columns := []factory.ExportColumn{
    {Header: "ID", Field: "ID", Width: 10},
    {Header: "姓名", Field: "Name", Width: 20},
    {
        Header: "创建时间",
        Field:  "CreatedAt",
        Width:  20,
        Format: excel.AdaptTimeFormatter(tools.FormatDateTime), // 使用适配器直接调用tools函数
    },
    {
        Header: "状态",
        Field:  "Status",
        Width:  10,
        Format: func(value interface{}) string {
            // 自定义格式化函数
            if status, ok := value.(int); ok {
                if status == 1 {
                    return "启用"
                }
                return "禁用"
            }
            return ""
        },
    },
}

err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
```

### 5. 使用ExportData接口（高级功能）

```go
// 实现ExportData接口
type UserExportData struct {
    users []User
}

// GetExportColumns 获取导出列定义
func (d *UserExportData) GetExportColumns() []excel.ExportColumn {
    return []excel.ExportColumn{
        {Header: "ID", Field: "ID", Width: 10},
        {Header: "姓名", Field: "Name", Width: 20},
        {Header: "邮箱", Field: "Email", Width: 30},
    }
}

// GetExportRows 获取导出数据行
func (d *UserExportData) GetExportRows() [][]interface{} {
    rows := make([][]interface{}, 0, len(d.users))
    for _, user := range d.users {
        row := []interface{}{
            user.ID,
            user.Name,
            user.Email,
        }
        rows = append(rows, row)
    }
    return rows
}

// 使用
exportData := &UserExportData{users: users}
columns := exportData.GetExportColumns()
err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, exportData)
```

### 6. 获取Excel对象（高级功能）

```go
// 获取Excel导出器对象（仅在需要高级功能时使用）
excel, err := fac.GetExcel()
if err != nil {
    log.Fatal(err)
}

// 获取excelize.File对象，用于高级操作
file := excel.GetFile()

// 创建多个工作表
file.NewSheet("Sheet2")
file.SetCellValue("Sheet2", "A1", "数据")

// 自定义样式
style, _ := file.NewStyle(&excelize.Style{
    Font: &excelize.Font{
        Bold: true,
        Size: 14,
    },
})
file.SetCellStyle("Sheet2", "A1", "A1", style)
```

## API 参考

### 工厂方法

#### ExportToExcel(w io.Writer, sheetName string, columns []ExportColumn, data interface{}) error

导出数据到Writer。

**参数：**
- `w`: Writer对象（如http.ResponseWriter）
- `sheetName`: 工作表名称（可选，默认为"Sheet1"）
- `columns`: 列定义
- `data`: 数据列表（可以是结构体切片或实现了ExportData接口的对象）

**返回：** 错误信息

**数据为空处理：**
- 支持 `nil`、空切片、指针类型等空数据情况
- 即使数据为空，表头也会正常生成

**工作表处理逻辑：**
- 如果 `sheetName` 为空，默认使用 "Sheet1"
- 如果指定的工作表不存在，会自动创建
- 使用自定义名称时会自动删除默认的"Sheet1"，避免产生空sheet

**示例：**
```go
fac.ExportToExcel(w, "用户列表", columns, users)
fac.ExportToExcel(w, "空数据", columns, []User{}) // 空数据也会生成表头
```

#### ExportToExcelFile(filePath string, sheetName string, columns []ExportColumn, data interface{}) error

导出数据到文件。

**参数：**
- `filePath`: 文件路径
- `sheetName`: 工作表名称（可选，默认为"Sheet1"）
- `columns`: 列定义
- `data`: 数据列表（可以是结构体切片或实现了ExportData接口的对象）

**返回：** 错误信息

**实现说明：**
- 此方法内部创建文件并调用 `ExportToWriter`
- 文件相关的封装由工厂方法处理

**工作表处理逻辑：**
- 如果 `sheetName` 为空，默认使用 "Sheet1"
- 如果指定的工作表不存在，会自动创建
- 使用自定义名称时会自动删除默认的"Sheet1"，避免产生空sheet

**示例：**
```go
fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
fac.ExportToExcelFile("empty.xlsx", "空数据", columns, []User{}) // 空数据也会生成表头
```

### 高级方法

#### GetExcel() (*excel.Excel, error)

获取Excel导出器对象。

**返回：** Excel导出器对象和错误信息

**说明：** 仅在需要使用高级功能时使用，推荐使用黑盒方法

### 结构体类型

#### ExportColumn

导出列定义。

```go
type ExportColumn struct {
    Header string                    // 表头名称
    Field  string                    // 数据字段名（支持嵌套字段，如 "User.Name"）
    Width  float64                   // 列宽（可选，0表示自动）
    Format func(interface{}) string  // 格式化函数（可选）
}
```

**字段说明：**
- `Header`: 表头显示的名称
- `Field`: 数据字段名，支持嵌套字段（如 "User.Name"）
- `Width`: 列宽，0表示自动调整
- `Format`: 格式化函数，用于自定义字段值的显示格式

### 格式化函数适配器

#### excel.AdaptTimeFormatter(fn func(time.Time, ...string) string) func(interface{}) string

适配器函数：将tools包的格式化函数转换为Excel Format字段需要的函数类型。

**参数：**
- `fn`: tools包的格式化函数（如 `tools.FormatDate`、`tools.FormatDateTime` 等）

**返回：** Excel Format字段需要的格式化函数

**说明：** 
- 允许直接使用tools包的任何格式化函数

**示例：**
```go
import (
    "git.toowon.com/jimmy/go-common/excel"
    "git.toowon.com/jimmy/go-common/tools"
)

// 使用tools.FormatDate
Format: excel.AdaptTimeFormatter(tools.FormatDate)

// 使用tools.FormatDateTime
Format: excel.AdaptTimeFormatter(tools.FormatDateTime)

// 使用tools.FormatTime
Format: excel.AdaptTimeFormatter(tools.FormatTime)

// 使用自定义格式化函数
Format: excel.AdaptTimeFormatter(func(t time.Time) string {
    return tools.Format(t, "2006-01-02 15:04:05", "Asia/Shanghai")
})
```

### ExportData接口

实现此接口的结构体可以直接导出。

```go
type ExportData interface {
    // GetExportColumns 获取导出列定义
    GetExportColumns() []ExportColumn
    // GetExportRows 获取导出数据行
    GetExportRows() [][]interface{}
}
```

## 完整示例

```go
package main

import (
    "net/http"
    "time"
    
    "git.toowon.com/jimmy/go-common/excel"
    "git.toowon.com/jimmy/go-common/factory"
)

type User struct {
    ID        int       `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
    Status    int       `json:"status"`
}

func exportUsersHandler(w http.ResponseWriter, r *http.Request) {
    fac, _ := factory.NewFactoryFromFile("./config.json")
    
    // 从数据库或其他数据源获取数据
    users := []User{
        {ID: 1, Name: "Alice", Email: "alice@example.com", CreatedAt: time.Now(), Status: 1},
        {ID: 2, Name: "Bob", Email: "bob@example.com", CreatedAt: time.Now(), Status: 1},
    }
    
    // 定义导出列
    columns := []factory.ExportColumn{
        {Header: "ID", Field: "ID", Width: 10},
        {Header: "姓名", Field: "Name", Width: 20},
        {Header: "邮箱", Field: "Email", Width: 30},
        {
            Header: "创建时间",
            Field:  "CreatedAt",
            Width:  20,
            Format: excel.AdaptTimeFormatter(tools.FormatDateTime),
        },
        {
            Header: "状态",
            Field:  "Status",
            Width:  10,
            Format: func(value interface{}) string {
                if status, ok := value.(int); ok {
                    if status == 1 {
                        return "启用"
                    }
                    return "禁用"
                }
                return ""
            },
        },
    }
    
    // 设置HTTP响应头
    w.Header().Set("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
    w.Header().Set("Content-Disposition", "attachment; filename=users.xlsx")
    
    // 导出到响应
    err := fac.ExportToExcel(w, "用户列表", columns, users)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
}

func main() {
    http.HandleFunc("/export/users", exportUsersHandler)
    http.ListenAndServe(":8080", nil)
}
```

## 设计优势

1. **降低复杂度**：调用方无需关心Excel文件对象的创建和管理
2. **延迟初始化**：Excel导出器在首次使用时才创建
3. **统一接口**：所有操作通过工厂方法调用
4. **灵活扩展**：支持结构体切片、自定义格式化、ExportData接口等多种方式
5. **自动优化**：自动调整列宽、应用表头样式等

## 注意事项

1. **配置**：Excel导出不需要配置，可以传nil创建工厂
2. **错误处理**：所有方法都可能返回错误，需要正确处理
3. **延迟初始化**：Excel导出器在首次使用时才创建，首次调用可能稍慢
4. **字段名匹配**：Field字段名必须与结构体字段名匹配（区分大小写）
5. **嵌套字段**：支持嵌套字段访问（如 "User.Name"），但需要确保字段路径正确
6. **格式化函数**：格式化函数返回的字符串会直接写入Excel单元格
7. **列宽设置**：Width为0时会自动调整列宽，但可能影响性能（大数据量时建议设置固定宽度）
8. **工作表处理**：工具会自动处理工作表的创建和删除，确保不会产生空sheet
9. **空数据处理**：即使数据为 `nil` 或空切片，表头也会正常生成
10. **方法设计**：
    - `excel` 包只暴露 `ExportToWriter` 一个核心方法
    - 文件相关的封装由工厂方法 `ExportToExcelFile` 处理

## 最佳实践

1. **使用工厂方法**：推荐使用 `ExportToExcel()` 和 `ExportToExcelFile()`
2. **设置列宽**：对于大数据量，建议设置固定列宽以提高性能
3. **使用格式化函数**：对于日期时间、状态等字段，使用格式化函数提高可读性
4. **错误处理**：始终检查导出方法的返回值
5. **HTTP响应**：导出到HTTP响应时，记得设置正确的Content-Type和Content-Disposition头
6. **工作表命名**：推荐使用有意义的工作表名称，工具会自动处理工作表的创建和删除
7. **空数据场景**：即使查询结果为空，也可以导出包含表头的Excel文件

## 示例

完整示例请参考 `examples/excel_example.go`