کار با مدیریت صفحه‌گسترده

کار با مدیریت صفحات گسترده

این راهنما نشان می‌دهد چگونه کتاب‌کارهای Excel را با استفاده از Aspose.Cells FOSS برای Java ایجاد، بارگذاری، ویرایش و ذخیره کنید. شما یاد خواهید گرفت چگونه با کلاس‌های Workbook، WorksheetCollection، Worksheet، Cells و Cell برای مدیریت کامل صفحه‌گسترده کار کنید.

ایجاد یک کتاب‌کار جدید

از سازنده بدون آرگومان برای ایجاد یک کتاب‌کار خالی استفاده کنید. یک برگه‌کار خالی به نام Sheet1 به‌صورت خودکار اضافه می‌شود.

import com.aspose.cells.foss.Workbook;
import com.aspose.cells.foss.WorksheetCollection;
import com.aspose.cells.foss.Worksheet;

Workbook workbook = new Workbook();
WorksheetCollection sheets = workbook.getWorksheets();
Worksheet sheet = sheets.get(0);
System.out.println("Sheet name: " + sheet.getName()); // Sheet1

بارگذاری یک کتاب‌کار از فایل

مسیر فایل را به سازنده Workbook(fileName) بدهید تا یک فایل .xlsx یا .ods موجود را باز کنید. از Workbook(fileName, options) برای فراهم کردن LoadOptions استفاده کنید وقتی که نیاز به کنترل تشخیص قالب یا مدیریت رمز عبور دارید.

import com.aspose.cells.foss.Workbook;
import com.aspose.cells.foss.LoadOptions;

// Simple load
Workbook workbook = new Workbook("data/report.xlsx");

// Load with explicit options
LoadOptions opts = new LoadOptions();
Workbook workbookWithOpts = new Workbook("data/report.xlsx", opts);

بارگذاری یک کتاب‌کار از یک جریان

Workbook(stream) و Workbook(stream, options) هر java.io.InputStream را می‌پذیرند. این در زمانی مفید است که فایل از منبع شبکه، یک BLOB پایگاه داده، یا یک آرایه بایت در حافظه می‌آید.

import com.aspose.cells.foss.Workbook;
import java.io.FileInputStream;
import java.io.InputStream;

try (InputStream is = new FileInputStream("data/template.xlsx")) {
    Workbook workbook = new Workbook(is);
    System.out.println("Worksheets: " + workbook.getWorksheets().getCount());
}

دسترسی و مدیریت شیت‌ها

Workbook.getWorksheets() یک WorksheetCollection برمی‌گرداند. شیت‌ها را بر اساس شاخص یا نام دریافت کنید، بر تمام شیت‌ها تکرار کنید، و در صورت نیاز شیت‌ها را اضافه یا حذف کنید.

import com.aspose.cells.foss.Workbook;
import com.aspose.cells.foss.WorksheetCollection;
import com.aspose.cells.foss.Worksheet;

Workbook workbook = new Workbook();
WorksheetCollection sheets = workbook.getWorksheets();

// Access by index
Worksheet first = sheets.get(0);
System.out.println(first.getName()); // Sheet1

// Add a named sheet
int idx = sheets.add("Summary");
Worksheet summary = sheets.get(idx);
summary.setName("Summary");

// Iterate all sheets
for (Worksheet ws : sheets) {
    System.out.println("Sheet: " + ws.getName());
}

// Remove a sheet by name
sheets.removeAt("Sheet1");
System.out.println("Remaining sheets: " + sheets.getCount());

خواندن و نوشتن مقادیر سلول‌ها

با استفاده از Worksheet.getCells() به یک سلول بروید، که یک مجموعه Cells را برمی‌گرداند. یک Cell را بر اساس نام (مثلاً "A1") یا بر مبنای شاخص صفر-پایه ردیف/ستون دریافت کنید. از putValue() برای نوشتن مقادیر اولیه و از getValue() / getStringValue() برای خواندن آنها استفاده کنید.

import com.aspose.cells.foss.Workbook;
import com.aspose.cells.foss.Worksheet;
import com.aspose.cells.foss.Cells;
import com.aspose.cells.foss.Cell;

Workbook workbook = new Workbook();
WorksheetCollection sheets = workbook.getWorksheets();
Worksheet sheet = sheets.get(0);
Cells cells = sheet.getCells();

// Write values
cells.get("A1").putValue("Product");
cells.get("B1").putValue("Units Sold");

// Write by row/column index (0-based)
Cell a2 = cells.get(1, 0);
a2.putValue("Widget A");

Cell b2 = cells.get(1, 1);
b2.putValue(1200);

// Read back
System.out.println(a2.getStringValue()); // Widget A
System.out.println(b2.getValue());       // 1200

تنظیم فرمول‌های سلول

یک رشته فرمول را به یک سلول از طریق setFormula() اختصاص دهید. Aspose.Cells فرمول‌ها را وقتی کتاب کار ذخیره می‌شود یا محاسبه به‌صورت صریح فعال می‌شود، ارزیابی می‌کند.

import com.aspose.cells.foss.Workbook;
import com.aspose.cells.foss.Cells;
import com.aspose.cells.foss.Cell;

Workbook workbook = new Workbook();
WorksheetCollection sheets = workbook.getWorksheets();
Cells cells = sheets.get(0).getCells();

cells.get("A1").putValue(100);
cells.get("A2").putValue(200);

Cell a3 = cells.get("A3");
a3.setFormula("=SUM(A1:A2)");
System.out.println("Formula: " + a3.getFormula()); // =SUM(A1:A2)

ذخیره‌سازی یک کتاب کار

از Workbook.save(fileName) برای نوشتن کتاب‌کار روی دیسک استفاده کنید. قالب خروجی توسط پسوند فایل تعیین می‌شود؛ برای کتاب‌کارهای اکسل از .xlsx استفاده کنید.

import com.aspose.cells.foss.Workbook;

Workbook workbook = new Workbook();
workbook.getWorksheets().get(0).getCells().get("A1").putValue("Hello");

// Save to file -- format inferred from .xlsx extension
workbook.save("output/result.xlsx");

آزادسازی منابع

Workbook AutoCloseable را پیاده‌سازی می‌کند. برای اطمینان از آزادسازی سریع منابع داخلی کتاب‌کار پس از استفاده، از بلوک try-with-resources استفاده کنید.

import com.aspose.cells.foss.Workbook;

try (Workbook workbook = new Workbook("data/large.xlsx")) {
    workbook.save("output/large_modified.xlsx");
}
// workbook.close() called automatically

نکات و بهترین شیوه‌ها

• همیشه برای فایل‌های بزرگ از try-with-resources (try (Workbook wb = new Workbook(...))) استفاده کنید تا از باز ماندن دستگیره‌های فایل جلوگیری شود.
• در حلقه‌های پرسرعت، cells.get(row, column) را بر cells.get(cellName) ترجیح دهید؛ نسخهٔ عددی از تجزیهٔ مکرر نام سلول جلوگیری می‌کند.
• قبل از دسترسی به شیت‌ها بر اساس شاخص، workbook.getWorksheets().getCount() را فراخوانی کنید تا از IndexOutOfBoundsException جلوگیری شود.
• پس از add()، شیت‌های خود را به‌وضوح با setName() نام‌گذاری کنید تا کدهای بعدی بتوانند آن‌ها را بر اساس نام جستجو کنند نه بر اساس شاخص ناپایدار.
• پس از setFormula() فوراً به نتایج فرمول اعتماد نکنید؛ ابتدا ذخیره کنید یا اگر در همان نشست به مقادیر محاسبه‌شده نیاز دارید، مجدداً بارگذاری کنید.

مسائل رایج

FAQ

چگونه یک برگه کاری را تغییر نام دهم؟

شیء Worksheet را با استفاده از اندیس از WorksheetCollection بازیابی کنید و setName(name) را با نام نمایشی جدید فراخوانی کنید:

workbook.getWorksheets().get(0).setName("Sales Data");

چگونه تعداد برگه‌های موجود در یک کتاب کار را بررسی کنم؟

برای دریافت کل تعداد برگه‌های کاری، getCount() را بر روی WorksheetCollection که توسط Workbook.getWorksheets() بازگردانده شده است، فراخوانی کنید:

int count = workbook.getWorksheets().getCount();

آیا می‌توانم چندین برگه را در یک فراخوانی اضافه کنم؟

نه. worksheets.add(sheetName) را یک بار برای هر شیت صدا بزنید. هر فراخوانی شاخص شیت تازه ایجاد شده را برمی‌گرداند.

چگونه نوع مقدار یک سلول را بررسی کنم؟

Cell را بر اساس نام بازیابی کنید و getType() را فراخوانی کنید، که یک مقدار enum از نوع CellValueType برمی‌گرداند:

Cell cell = cells.get("A1");
System.out.println(cell.getType()); // CellValueType enum value

خلاصه API Reference

همچنین ببینید:

• Aspose.Cells for Java — Enterprise Documentation