شروع سریع Go Excelize

معرفی Excelize

Excelize یک کتابخانه ابتدایی برای دستکاری اسناد اداری اکسل Office نوشته شده به زبان Go می باشد، بر اساس استانداردهای بین المللی ECMA-376 و ISO/IEC 29500. این کتابخانه می تواند برای خواندن و نوشتن اسناد صفحه کاری‌های ایجاد شده توسط Microsoft Excel™ 2007 و بالاتر استفاده شود و فرمت‌های اسناد مختلف مانند XLAM / XLSM / XLSX / XLTM / XLTX را پشتیبانی می کند. این کتابخانه با اسنادی که حاوی استایل‌ها، تصاویر (جداول)، جدول‌های پیوت، برش‌ها و سایر مؤلفه‌های پیچیده هستند، سازگاری بسیاری دارد و یک API خواندن-نوشتن جریانی برای پردازش کتب‌ها با داده‌های بزرگ فراهم می کند. این کتابخانه می تواند در انواع پلتفرم‌های گزارش‌گیری، محاسبات ابری، محاسبات لبه و سایر سیستم‌ها به کار رود. برای استفاده از این کتابخانه نیاز به نسخه 1.16 یا بالاتر از زبان Go می باشد.

نصب

جدول زیر حداقل نیازمندی‌های کتابخانه ابتدایی Excelize برای نسخه‌های مختلف زبان Go را نشان می دهد:

استفاده از آخرین نسخه Excelize نیازمند نسخه 1.16 یا بالاتر از زبان Go می باشد. لطفا توجه داشته باشید که تغییرات ناسازگار(https://github.com/golang/go/issues/61881) در Go 1.21.0 باعث می شود که کتابخانه ابتدایی Excelize به درستی روی این نسخه کار نکند. اگر از Go 1.21.x استفاده می کنید، لطفا به نسخه 1.21.1 یا بالاتر ارتقا دهید.

• فرمان نصب

go get github.com/xuri/excelize

• اگر از ماژول‌های Go برای مدیریت بسته‌ها استفاده می کنید، از دستور زیر برای نصب آخرین نسخه استفاده کنید.

go get github.com/xuri/excelize/v2

به روزرسانی

• فرمان به‌روزرسانی

go get -u github.com/xuri/excelize/v2

ایجاد اسناد اکسل

در زیر یک مثال ساده از ایجاد یک سند اکسل آمده است:

package main

import (
    "fmt"
    "github.com/xuri/excelize/v2"
)

func main() {
    f := excelize.NewFile()
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    // ایجاد یک برگه جدید
    index, err := f.NewSheet("Sheet2")
    if err != nil {
        fmt.Println(err)
        return
    }
    // تنظیم مقادیر سلول
    f.SetCellValue("Sheet2", "A2", "سلام دنیا.")
    f.SetCellValue("Sheet1", "B2", 100)
    // تنظیم برگه کار پیش‌فرض کتاب
    f.SetActiveSheet(index)
    // ذخیره فایل در مسیر مشخص شده
    if err := f.SaveAs("Book1.xlsx"); err != nil {
        fmt.Println(err)
    }
}

خواندن اسناد اکسل

در زیر مثالی از خواندن اسناد اکسل آمده است:

package main

import (
    "fmt"

    "github.com/xuri/excelize/v2"
)

func main() {
    f, err := excelize.OpenFile("Book1.xlsx")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    // دریافت مقدار سلول مشخص شده در برگه کاری
    cell, err := f.GetCellValue("Sheet1", "B2")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(cell)
    // دریافت تمامی سلول‌ها در Sheet1
    rows, err := f.GetRows("Sheet1")
    if err != nil {
        fmt.Println(err)
        return
    }
    for _, row := range rows {
        for _, colCell := range row {
            fmt.Print(colCell, "\t")
        }
        fmt.Println()
    }
}

ایجاد نمودارها در اسناد اکسل

ایجاد نمودارها با استفاده از Excelize بسیار ساده است و تنها چند خط کد نیاز است. می‌توانید نمودارها را بر اساس داده‌های موجود در کارشیت ایجاد کنید یا داده‌ها را به کارشیت اضافه کرده و سپس نمودارها را ایجاد کنید.

package main

import (
    "fmt"
    
    "github.com/xuri/excelize/v2"
)

func main() {
    f := excelize.NewFile()
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    for idx, row := range [][]interface{}{
        {nil, "سیب", "پرتقال", "گلابی"}, {"کوچک", 2, 3, 3},
        {"عادی", 5, 2, 4}, {"بزرگ", 6, 7, 8},
    } {
        cell, err := excelize.CoordinatesToCellName(1, idx+1)
        if err != nil {
            fmt.Println(err)
            return
        }
        f.SetSheetRow("Sheet1", cell, &row)
    }
    if err := f.AddChart("Sheet1", "E1", &excelize.Chart{
        Type: excelize.Col3DClustered,
        Series: []excelize.ChartSeries{
            {
                Name:       "Sheet1!$A$2",
                Categories: "Sheet1!$B$1:$D$1",
                Values:     "Sheet1!$B$2:$D$2",
            },
            {
                Name:       "Sheet1!$A$3",
                Categories: "Sheet1!$B$1:$D$1",
                Values:     "Sheet1!$B$3:$D$3",
            },
            {
                Name:       "Sheet1!$A$4",
                Categories: "Sheet1!$B$1:$D$1",
                Values:     "Sheet1!$B$4:$D$4",
            }},
        Title: []excelize.RichTextRun{
            {
                Text: "نمودار ستونی سه‌بعدی میوه‌ها",
            },
        },
    }); err != nil {
        fmt.Println(err)
        return
    }
    // ذخیرهٔ فایل در مسیر مشخص شده
    if err := f.SaveAs("Book1.xlsx"); err != nil {
        fmt.Println(err)
    }
}

وارد کردن تصاویر در اسناد اکسل

package main

import (
    "fmt"
    _ "image/gif"
    _ "image/jpeg"
    _ "image/png"

    "github.com/xuri/excelize/v2"
)

func main() {
    f, err := excelize.OpenFile("Book1.xlsx")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    // وارد کردن یک تصویر
    if err := f.AddPicture("Sheet1", "A2", "image.png", nil); err != nil {
        fmt.Println(err)
        return
    }
    // وارد کردن تصویر در کارشیت و تنظیم مقیاس تصویر
    if err := f.AddPicture("Sheet1", "D2", "image.jpg",
        &excelize.GraphicOptions{ScaleX: 0.5, ScaleY: 0.5}); err != nil {
        fmt.Println(err)
        return
    }
    // وارد کردن تصویر در کارشیت و تنظیم ویژگی‌های چاپ تصویر
    enable, disable := true, false
    if err := f.AddPicture("Sheet1", "H2", "image.gif",
        &excelize.GraphicOptions{
            PrintObject:     &enable,
            LockAspectRatio: false,
            OffsetX:         15,
            OffsetY:         10,
            Locked:          &disable,
        }); err != nil {
        fmt.Println(err)
        return
    }
    // ذخیرهٔ فایل
    if err = f.Save(); err != nil {
        fmt.Println(err)
    }
}