مقدمه

کلاس Cell واحد پایه‌ای در Aspose.Cells FOSS برای جاوا است. این کلاس مقادیر تایپ‌شده را ذخیره می‌کند، نوع زمان اجرا آن‌ها را از طریق enum CellValueType نشان می‌دهد، رشته‌های فرمول را برای ارزیابی توسط Excel حفظ می‌کند و نمایهٔ رشته‌ای یکنواختی را از طریق getStringValue() فراهم می‌آورد. این پست API اصلی سلول را به‌صورت جزئی با مثال‌های تأییدشده بررسی می‌کند.

تمام مثال‌های کد زیر از وابستگی Maven استفاده می‌کنند:

<dependency>
  <groupId>com.aspose</groupId>
  <artifactId>cells-foss</artifactId>
  <version>1.0.0</version>
</dependency>

API سلول هسته‌ای

ذخیره‌سازی مقادیر تایپ‌شده با putValue()

Cell.putValue() شش نوع جاوا را می‌پذیرد: String، int، double، boolean، LocalDateTime و Object. هر فراخوانی مقدار داخلی سلول را تنظیم می‌کند و CellValueType بازگردانده شده توسط cell.getType() را تعیین می‌نماید.

import com.aspose.cells_foss.Cell;
import com.aspose.cells_foss.CellValueType;
import com.aspose.cells_foss.Workbook;
import com.aspose.cells_foss.Worksheet;
import java.time.LocalDateTime;

try (Workbook workbook = new Workbook()) {
    Worksheet sheet = workbook.getWorksheets().get(0);

    Cell a1 = sheet.getCells().get("A1");
    a1.putValue("Revenue");
    assert a1.getType() == CellValueType.STRING;

    Cell b1 = sheet.getCells().get("B1");
    b1.putValue(42500.75);
    assert b1.getType() == CellValueType.NUMBER;

    Cell c1 = sheet.getCells().get("C1");
    c1.putValue(true);
    assert c1.getType() == CellValueType.BOOLEAN;

    Cell d1 = sheet.getCells().get("D1");
    d1.putValue(LocalDateTime.of(2026, 4, 27, 9, 0, 0));
    assert d1.getType() == CellValueType.DATE_TIME;

    workbook.save("typed.xlsx");
}

سلول‌های خالی CellValueType.BLANK را از getType() برمی‌گردانند. مقادیر صحیح ذخیره‌شده با
putValue(int) در مسیر دورانی از طریق سریال‌سازی XLSX بدون افزودن نقطه اعشار —
getStringValue() "123" را برمی‌گرداند نه "123.0".

بازرسی مقادیر در زمان اجرا

cell.getValue() مقدار ذخیره‌شدهٔ خام را به‌صورت Object برمی‌گرداند. cell.getStringValue()
یک نمایش رشته‌ای مستقل از locale فراهم می‌کند که برای پردازش یا نمایش
در ادامه مناسب است. شاخه‌بندی بر پایهٔ CellValueType الگوی پیشنهادی برای استخراج
مقدار به‌صورت type‑safe است:

import com.aspose.cells_foss.Cell;
import com.aspose.cells_foss.CellValueType;
import com.aspose.cells_foss.Workbook;
import com.aspose.cells_foss.Worksheet;

try (Workbook workbook = new Workbook()) {
    Worksheet sheet = workbook.getWorksheets().get(0);
    sheet.getCells().get("A1").putValue("Hello");
    sheet.getCells().get("B1").putValue(123);
    sheet.getCells().get("C1").putValue(true);
    sheet.getCells().get("D1").putValue(12.5d);
    sheet.getCells().get("G1").setFormula("=B1*2");

    Cell b1 = sheet.getCells().get("B1");
    if (b1.getType() == CellValueType.NUMBER) {
        System.out.println("Number: " + b1.getStringValue());
    }
    workbook.save("inspect.xlsx");
}

ذخیره‌سازی فرمول

رشته‌های فرمول با cell.setFormula() ذخیره می‌شوند. رشته فرمول ذخیره‌شده با
= شروع می‌شود و از سینتکس استاندارد فرمول‌های Excel پیروی می‌کند. متد getType()
CellValueType.FORMULA را برای سلول‌های فرمول برمی‌گرداند. Aspose.Cells FOSS for Java فرمول‌ها را در
XLSX ذخیره و round‑trip می‌کند؛ فرمول هنگام باز کردن توسط Excel دوباره محاسبه می‌شود.

import com.aspose.cells_foss.Cell;
import com.aspose.cells_foss.CellValueType;
import com.aspose.cells_foss.Workbook;
import com.aspose.cells_foss.Worksheet;

try (Workbook workbook = new Workbook()) {
    Worksheet sheet = workbook.getWorksheets().get(0);
    Cell b1 = sheet.getCells().get("B1");
    b1.putValue(100.0);
    Cell c1 = sheet.getCells().get("C1");
    c1.setFormula("=B1*1.2");
    assert c1.getType() == CellValueType.FORMULA;
    workbook.save("formulas.xlsx");
}

دقت تبدیل رفت و برگشت XLSX

تمام مقادیر تایپ‌شده در طول سریال‌سازی XLSX و بارگذاری مجدد حفظ می‌شوند. بارگذاری یک فایل .xlsx موجود از new Workbook(path) یا new Workbook(path, options) با LoadOptions برای فعال‌سازی حالت تعمیر استفاده می‌کند. پس از بارگذاری مجدد، getType() و getStringValue() همان مقادیر را که در زمان نوشتن بودند برمی‌گردانند.

import com.aspose.cells_foss.LoadIssue;
import com.aspose.cells_foss.LoadOptions;
import com.aspose.cells_foss.Workbook;
import com.aspose.cells_foss.Worksheet;

LoadOptions options = new LoadOptions();
options.setStrictMode(false);
options.setTryRepairPackage(true);
options.setTryRepairXml(true);

try (Workbook workbook = new Workbook("input.xlsx", options)) {
    if (workbook.getLoadDiagnostics().hasRepairs()) {
        for (LoadIssue issue : workbook.getLoadDiagnostics().getIssues()) {
            System.out.println(issue.getMessage());
        }
    }
    Worksheet sheet = workbook.getWorksheets().get(0);
    System.out.println(sheet.getCells().get("A1").getStringValue());
    workbook.save("output.xlsx");
}

قالب‌های پشتیبانی‌شده

قالبپسوندخواندننوشتن
Excel Open XML.xlsx

منبع باز و مجوزدهی

Aspose.Cells FOSS for Java تحت مجوز MIT منتشر شده است. شما آزادید که استفاده کنید، تغییر دهید و آن را در پروژه‌های شخصی، منبع باز و تجاری بدون محدودیت. کد منبع در دسترس است در github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-Java.


شروع کار