Aspose.Cells FOSS
Python
Panduan Pembangun
Bekerja dengan Carta

Bekerja dengan Carta

Gambaran Keseluruhan

Aspose.Cells FOSS menggunakan API kaedah-per-jenis-carta. Daripada panggilan add(ChartType.X, ...) generik, setiap jenis carta mempunyai kaedah khususnya sendiri pada koleksi charts lembar kerja:

KaedahJenis carta
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)Kolum berkelompok (carta bar)
ws.charts.add_line(top_row, left_col, bottom_row, right_col)Garis
ws.charts.add_pie(top_row, left_col, bottom_row, right_col)Pai
ws.charts.add_area(top_row, left_col, bottom_row, right_col)Kawasan

Keempat-empat parameter posisi menggambarkan kawasan segi empat tepat dalam helaian di mana carta akan disematkan. Indeks baris dan lajur adalah berdasarkan sifar. Setiap kaedah mengembalikan objek Chart yang anda konfigurasi selanjutnya sebelum menyimpan.

Had: Hanya jenis carta LINE, BAR, PIE, AREA, dan STOCK yang boleh disimpan ke XLSX. Memanggil wb.save() dengan buku kerja yang mengandungi sebarang jenis carta lain (contoh, SCATTER, WATERFALL, RADAR, TREEMAP, HISTOGRAM) akan memunculkan NotImplementedError.

Menambah Carta Lajur

Contoh di bawah menulis set data pendapatan mengikut produk kecil dan kemudian menambah carta lajur yang diletakkan di bawah data.

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##--- Data ---
ws.cells["A1"].value = "Product"
ws.cells["B1"].value = "Revenue"

products = ["Widget A", "Widget B", "Widget C", "Widget D", "Widget E"]
revenues = [12_500, 18_200, 9_800, 21_400, 15_600]

for i, (product, revenue) in enumerate(zip(products, revenues), start=2):
    ws.cells[f"A{i}"].value = product
    ws.cells[f"B{i}"].value = revenue

##--- Chart (rows 7–22, columns A–H, all zero-based) ---
##top_row=6, left_col=0, bottom_row=22, right_col=7
chart = ws.charts.add_bar(6, 0, 22, 7)

chart.title = "Revenue by Product"
chart.n_series.add("B2:B6", category_data="A2:A6", name="Revenue (USD)")
chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("column_chart.xlsx")
print("Saved column_chart.xlsx")

Data tersebut menempati baris 1–6 (baris berasaskan sifar 0–5), jadi top_row=6 meletakkan carta terus di bawah tanpa menindih data.

Menambah Carta Garis

Carta garis berfungsi dengan baik untuk menunjukkan trend dari masa ke masa. Tandatangan panggilan adalah serupa dengan add_bar — hanya nama kaedah yang berubah.

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##--- Monthly trend data ---
ws.cells["A1"].value = "Month"
ws.cells["B1"].value = "Page Views"
ws.cells["C1"].value = "Conversions"

months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
page_views   = [4_200, 5_100, 4_800, 6_300, 7_100, 6_800]
conversions  = [  210,   255,   230,   340,   390,   360]

for i, (month, pv, cv) in enumerate(zip(months, page_views, conversions), start=2):
    ws.cells[f"A{i}"].value = month
    ws.cells[f"B{i}"].value = pv
    ws.cells[f"C{i}"].value = cv

##--- Line chart below the data ---
chart = ws.charts.add_line(8, 0, 24, 8)

chart.title = "Monthly Website Metrics"
chart.n_series.add("B2:B7", category_data="A2:A7", name="Page Views")
chart.n_series.add("C2:C7", category_data="A2:A7", name="Conversions")
chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("line_chart.xlsx")
print("Saved line_chart.xlsx")

Tajuk Carta dan Legenda

Tetapkan tajuk carta dengan menetapkan rentetan biasa secara langsung kepada chart.title. Sifat ini menerima str — jangan cuba mengakses sub-sifat seperti .title.text, yang tidak wujud dalam perpustakaan ini.

##Correct
chart.title = "Quarterly Sales"

##Wrong — raises AttributeError
##chart.title.text = "Quarterly Sales"

Keterlihatan legenda dan kedudukan dikawal oleh dua sifat:

chart.show_legend = True          # display the legend
chart.legend_position = "bottom"  # "bottom", "top", "left", "right"

Untuk menyembunyikan legenda sepenuhnya, tetapkan chart.show_legend = False. Nilai legend_position diabaikan apabila legenda disembunyikan.

Konfigurasi Siri Data

Gunakan chart.n_series.add() untuk melampirkan julat data ke carta. Hantar semua argumen sebagai keyword arguments untuk mengelakkan kekeliruan susunan posisi:

chart.n_series.add("B2:B6", category_data="A2:A6", name="Revenue")

Anda boleh menambah pelbagai siri ke dalam satu carta dengan memanggil n_series.add lebih daripada sekali. Setiap panggilan menambah satu siri baru:

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##Headers
ws.cells["A1"].value = "Quarter"
ws.cells["B1"].value = "North"
ws.cells["C1"].value = "South"
ws.cells["D1"].value = "East"

data = [
    ("Q1", 8_400, 6_100, 7_200),
    ("Q2", 9_200, 7_400, 8_100),
    ("Q3", 10_500, 8_900, 9_600),
    ("Q4", 11_800, 9_300, 10_200),
]

for i, row in enumerate(data, start=2):
    ws.cells[f"A{i}"].value = row[0]
    ws.cells[f"B{i}"].value = row[1]
    ws.cells[f"C{i}"].value = row[2]
    ws.cells[f"D{i}"].value = row[3]

chart = ws.charts.add_bar(6, 0, 22, 8)
chart.title = "Regional Sales by Quarter"

chart.n_series.add("B2:B5", category_data="A2:A5", name="North")
chart.n_series.add("C2:C5", category_data="A2:A5", name="South")
chart.n_series.add("D2:D5", category_data="A2:A5", name="East")

chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("multi_series_chart.xlsx")
print("Saved multi_series_chart.xlsx")

Data Kategori

Label kategori boleh ditetapkan pada peringkat carta atau pada peringkat siri individu.

Chart-level category data digunakan untuk semua siri secara lalai:

chart.category_data = "A2:A5"

Data kategori peringkat siri (melalui argumen kata kunci category_data kepada n_series.add) menggantikan tetapan peringkat carta untuk siri tertentu itu:

chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")

Apabila setiap siri berkongsi julat kategori yang sama, menetapkan chart.category_data sekali adalah lebih ringkas. Apabila siri mempunyai julat kategori yang berbeza — contohnya, dua set data dengan tempoh masa yang berbeza — gunakan argumen kata kunci per-siri sebagai gantinya.

Penempatan Carta

Empat parameter posisi kepada setiap kaedah add_* mendefinisikan segi empat tepat sempadan dalam helaian, diukur dalam indeks baris dan lajur berasaskan sifar:

add_bar(top_row, left_col, bottom_row, right_col)
ParameterMaksud
top_rowIndeks berasaskan sifar bagi baris pertama yang diduduki oleh carta
left_colIndeks berasaskan sifar bagi lajur paling kiri
bottom_rowIndeks berasaskan sifar bagi baris terakhir yang diduduki oleh carta
right_colIndeks berasaskan sifar bagi lajur paling kanan

Corak biasa ialah meletakkan carta terus di bawah data. Jika data anda berakhir pada baris Excel 6 (indeks baris berasaskan sifar 5), mulakan carta pada top_row=6:

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##Data in rows 1–5 (zero-based 0–4)
labels = ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"]
values = [30, 45, 28, 60, 52]

ws.cells["A1"].value = "Category"
ws.cells["B1"].value = "Score"

for i, (label, val) in enumerate(zip(labels, values), start=2):
    ws.cells[f"A{i}"].value = label
    ws.cells[f"B{i}"].value = val

##Data ends at zero-based row 5 (Excel row 6).
##Place chart from row 6 to row 22, columns A–H (0–7).
chart = ws.charts.add_bar(6, 0, 22, 7)
chart.title = "Category Scores"
chart.n_series.add("B2:B6", category_data="A2:A6", name="Score")
chart.show_legend = False

workbook.save("positioned_chart.xlsx")
print("Saved positioned_chart.xlsx")

Buat carta cukup tinggi supaya boleh dibaca: ketinggian sekurang‑kurangnya 15 baris (bottom_row - top_row >= 15) dan lebar sekurang‑kurangnya 6 lajur adalah titik permulaan yang munasabah.

Kesilapan Biasa

SalahBetulKenapa
ws.charts.add(ChartType.COLUMN, ...)ws.charts.add_bar(...)Jangan panggil ws.charts.add(ChartType.X, ...) secara langsung untuk jenis yang tidak disokong — ia akan membangkitkan NotImplementedError untuk 11 daripada 16 jenis carta. Gunakan add_bar(), add_line(), add_pie(), add_area(), atau add_stock() sebagai gantinya.
chart.title.text = "My Chart"chart.title = "My Chart"chart.title ialah sifat rentetan biasa, bukan objek dengan sub‑sifat .text.
chart.n_series.add("B2:B5", "A2:A5", "Revenue")chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")Parameter kedua dan ketiga mesti dihantar sebagai argumen kata kunci untuk mengelakkan kekaburan.
chart = ws.charts.add_bar(0, 0, 15, 7) (overlaps data)Letakkan top_row di bawah baris data terakhirCarta yang bertindih data menyembunyikan nilai dan menyebabkan susun atur yang mengelirukan.
chart.legend_position = "bottom" tanpa chart.show_legend = TrueTetapkan chart.show_legend = True terlebih dahululegend_position tidak berkesan apabila show_legend ialah False.

Lihat Juga

 Bahasa Melayu