Overview — Object Model and Basic Flow

level: basic ／ verified: 2026-10-01 ／ tabs: Node.js・Python・Java・WebAssembly ／ 日本語

What you want to do

Get the big picture of nodeosbxl.

• The object hierarchy (App → WorkBook → WorkSheet → Range)
• The basic flow (create new / open existing book → sheet → Range → values & formulas → save / saveAs / close)
• The main methods of the four classes

Details of individual features are covered by the samples that follow this page.

Prerequisites

Download the module for your language from the download page and install it.

The WebAssembly build uses MEMORY64 (Wasm 3.0), so the runtime must support it (Chrome/Edge 133+, Firefox 134+, Node.js 24+. Safari is not supported yet).

The entry point differs per language; the namespace layout (operation classes / dto / chart / enums) is common to all four.

npm install ./nodeosbxl-1.5.0.tgz

# (example) Python 3.12+ (a single abi3 wheel covers 3.12 and later)
pip install ./pyosbxl-1.5.0-cp312-abi3-linux_x86_64.whl

# Add the JAR to your classpath (javacpp-1.5.14.jar is also required)
javac -cp osbxl-1.5.0.jar:javacpp-1.5.14.jar Main.java
java  -cp osbxl-1.5.0.jar:javacpp-1.5.14.jar:. Main

# Unpack the package (contains osbxl_wasm.js / osbxl_em.js / license/)
tar xzf wasmosbxl-1.5.0.tgz

// Loading example (requires Node.js 24+: this wasm is a MEMORY64 = Wasm 3.0 build)
const fs = require("fs");
const createModule = require("./package/osbxl_wasm.js");   // emscripten factory
const { createOsbxl } = require("./package/osbxl_em.js");  // loader + enum definitions

createOsbxl(createModule).then(({ Module, osbxl, dto, chart, enums }) => {
  // Stage the license file into the wasm virtual FS (required before new App())
  const lic = process.env.OSB_LICENSE_PATH_WASM;          // e.g. /root/lic_node.osb
  if (lic && fs.existsSync(lic)) {
    Module.FS.mkdirTree(lic.substring(0, lic.lastIndexOf("/")));
    Module.FS.writeFile(lic, fs.readFileSync(lic));
  }
  const app = new osbxl.App();   // from here on it matches the Node.js build (namespace name is osbxl)
  // ...
});
// In the browser, load osbxl_wasm.js via <script> and call createOsbxl the same way.
// Supported: Chrome/Edge 133+, Firefox 134+ (Safari not supported yet)

The table below uses Node.js names; the counts per namespace are common to all four languages.

Object model

App                     ← the single entry point. Open/create books, convert cell addresses
 │
 ├─ createWorkBook()  ─┐
 ├─ openWorkBook()    ─┴→ WorkBook          ← one xlsx file
 │                        │
 │                        ├─ openWorkSheet()      → WorkSheet   ← one sheet
 │                        │                         │
 │                        │                         ├─ getRange("A1:B2")    → Range
 │                        │                         │    ※ getCells(1,1,2,2) returns the same Range
 │                        │                         │                       │
 │                        │                         │                       ├─ getValue() / setValue() / setFormula()
 │                        │                         │                       ├─ getFont()   → Font   → getColor() → Color
 │                        │                         │                       ├─ getBorders()→ Borders→ getBorder()  → Border
 │                        │                         │                       ├─ getFill()   → Fill
 │                        │                         │                       └─ getAlignment() → Alignment
 │                        │                         │
 │                        │                         ├─ getRow() / getCol()  → Row / Col
 │                        │                         ├─ getSort() / getAutoFilter()
 │                        │                         ├─ getPivotTables() / getListObjects()
 │                        │                         ├─ addChartObject()     → chart.ChartObject
 │                        │                         └─ getComments() / getHyperLinks() / getShapes() ...
 │                        │
 │                        ├─ addWorkSheet() / deleteWorkSheet() / moveSheet()
 │                        ├─ addCustomStyle() / addCustomTableStyle()
 │                        └─ save() / saveAs() / close()
 │
 └─ utilities such as convertFromRowColNumber()

Always walking this hierarchy top-down is the osbxl basics. Below Range (Font, Color, Borders, …) the pattern is "get the object, then call its setters".

Basic flow

 [1] new App()                 create the App
 [2] createWorkBook(path)      create a new book
     openWorkBook(path)        open an existing book
 [3] openWorkSheet(name)       open a worksheet
 [4] getRange("A1:B2")         get a Range (getCells(1,1,2,2) is the same)
 [5] setValue() / setFormula() write values / formulas
 [6] getValue(true)            read the results back
 [7] save() / saveAs(path)     save
 [8] close()                   close the book

Code

Output:

// basic-flow.js — the full flow: create → edit → save → reopen → save as
const { nodeosbxl } = require("nodeosbxl");

const app = new nodeosbxl.App();                  // [1] create the App

// ---------- create a new book, edit it and save ----------
let wb = app.createWorkBook("flow.xlsx");         // [2] create new
console.log("[2] createWorkBook -> getBookPath =", wb.getBookPath());

let ws = wb.openWorkSheet("Sheet1");              // [3] open a worksheet
console.log("[3] openWorkSheet  -> sheet name =", ws.getName());

// [4] get a Range and [5] set values
//     ws.getCells(1, 1) (numeric row/col) returns the same Range as getRange("A1:A1")
ws.getRange("A1:A1").setValue("created new");
ws.getRange("B1:B1").setFormula("100*3");         // [5] set a formula (no leading "=")
console.log("[6] getValue(true) -> B1 =", ws.getRange("B1:B1").getValue(true)["B1"]);

wb.save();                                        // [7] save
console.log("[7] save() done");
wb.close();                                       // [8] close (no close needed for WorkSheet)
console.log("[8] close() done");

// ---------- open the existing book and save it under a new name ----------
wb = app.openWorkBook("flow.xlsx");               // [2'] open an existing book
ws = wb.openWorkSheet("Sheet1");                  // [3']
const read = ws.getRange("A1:B1").getValue(true);
console.log("[2'] openWorkBook -> A1 =", read["A1"], "/ B1 =", read["B1"]);

ws.getRange("A2:A2").setValue("appended after reopen");
wb.saveAs("flow-copy.xlsx");                      // [7'] save under a new name
console.log("[7'] saveAs() done -> getBookPath =", wb.getBookPath());
wb.close();                                       // [8']
console.log("[8] close() done");

# basic-flow.py — same verification as the Node.js sample (pyosbxl)
import pyosbxl

app = pyosbxl.App()                               # [1] create the App

wb = app.createWorkBook("flow-py.xlsx")           # [2] create new
ws = wb.openWorkSheet("Sheet1")                   # [3] open a worksheet

ws.getRange("A1:A1").setValue("created new")
ws.getRange("B1:B1").setFormula("100*3")          # [5] formula (no leading "=")
print("[6] getValue(True) -> B1 =", ws.getRange("B1:B1").getValue(True)["B1"])

wb.save()                                         # [7] save
wb.close()                                        # [8] close
print("[8] close() done")

wb = app.openWorkBook("flow-py.xlsx")             # [2'] open an existing book
ws = wb.openWorkSheet("Sheet1")
print("[2'] openWorkBook -> A1 =", ws.getRange("A1:A1").getValue(True)["A1"])
wb.close()
print("[8] close() done")

// basic-flow.java — same verification as the Node.js sample (javaosbxl)
import com.osboffice.osbxl.*;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        AppWrapper app = new AppWrapper();                          // [1] create the App

        WorkBookWrapper wb = app.createWorkBook("flow-java.xlsx");  // [2] create new
        WorkSheetWrapper ws = wb.openWorkSheet("Sheet1");           // [3] open a worksheet

        ws.getRange("A1:A1").setValue("created new");
        ws.getRange("B1:B1").setFormula("100*3");                   // [5] formula (no leading "=")
        Map<String, String> v = ws.getRange("B1:B1").getValue(true);
        System.out.println("[6] getValue(true) -> B1 = " + v.get("B1"));

        wb.save();                                                  // [7] save
        wb.close();                                                 // [8] close
        System.out.println("[8] close() done");

        wb = app.openWorkBook("flow-java.xlsx");                    // [2'] open an existing book
        ws = wb.openWorkSheet("Sheet1");
        Map<String, String> r = ws.getRange("A1:A1").getValue(true);
        System.out.println("[2'] openWorkBook -> A1 = " + r.get("A1"));
        wb.close();
        System.out.println("[8] close() done");
    }
}

// basic-flow.wasm.js — same verification as the Node.js sample (wasmosbxl / embind)
// Note (WebAssembly build): load the module first with createOsbxl(createModule).
// osbxl / dto / chart / enums used below are the four namespaces it returns
// (the equivalent of require("nodeosbxl") in the Node.js build).
const app = new osbxl.App();                        // [1] create the App

const wb = app.createWorkBook("flow-wasm.xlsx");    // [2] create new
const ws = wb.openWorkSheet("Sheet1");              // [3] open a worksheet

ws.getRange("A1:A1").setValue("created new");
ws.getRange("B1:B1").setFormula("100*3");           // [5] formula (no leading "=")
console.log("[6] getValue(true) -> B1 =", ws.getRange("B1:B1").getValue(true)["B1"]);

wb.save();                                          // [7] save
wb.close();                                         // [8] close
console.log("[8] close() done");

const wb2 = app.openWorkBook("flow-wasm.xlsx");     // [2'] open an existing book
const ws2 = wb2.openWorkSheet("Sheet1");
console.log("[2'] openWorkBook -> A1 =", ws2.getRange("A1:A1").getValue(true)["A1"]);
wb2.close();
console.log("[8] close() done");

[2] createWorkBook -> getBookPath = <working directory>/flow.xlsx
[3] openWorkSheet  -> sheet name = Sheet1
[6] getValue(true) -> B1 = 300
[7] save() done
[8] close() done
[2'] openWorkBook -> A1 = created new / B1 = 300
[7'] saveAs() done -> getBookPath = <working directory>/flow.xlsx
[8] close() done

Two files are produced: flow.xlsx and flow-copy.xlsx.

Flow highlights

• One App per process is enough. Even when handling multiple books, call createWorkBook() / openWorkBook() on the same app.
• Relative paths are resolved to absolute paths. After createWorkBook("flow.xlsx"), getBookPath() returns an absolute path including the current directory.
• There is no operation to close a WorkSheet. close() exists only as a WorkBook method. Sheets are all released together by wb.close().
• Note the difference between save() and saveAs() (see "Caveats" below).

Main methods

App (10 methods)

Created with new nodeosbxl.App(). Handles opening/closing books and address conversion utilities.

convertFromRowColNumber / convertFromRowColNumber2 also have overloads that return absolute references ("$A$1").

WorkBook (27 methods) — main 12

Corresponds to one xlsx file.

Others (15): styles — getNames addCustomStyle getCustomStyle deleteCustomStyle addCustomTableStyle addPivotCustomTableStyle getCustomTableStyle deleteCustomTableStyle / external books — addExternalWorkBook updateExternalWorkBook getExternalWorkBookPath / file properties — setCompanyName setManagerName setCreateAuthor setLastAuthor

WorkSheet (44 methods) — main 14

Corresponds to one sheet. This is the gateway to the objects below it (Range / Sort / PivotTable / Chart …).

Others (30): feature objects — getFormatConditions getAutoFilter getSort getComments getHyperLinks getListObjects getPivotTables getShapes getWindow getHPageBreaks getVPageBreaks / charts — getChartObject addChartObject deleteChartObject / print setup — getPageSetupObject setPageSetupObject / selection — getActiveCell setActiveCell / row, column and cell operations — clearRow copyRow clearCol copyCol insertCell deleteCell clearCell copyCell / outlining — setRowOutline clearRowOutline setColOutline clearColOutline

Range (31 methods) — main 16

Corresponds to a cell range. Reads/writes values and formulas, and is the gateway to formatting objects.

Others (15): getProtection getCharacters getPhonetics getNumberFormat clearNumberFormat clearAllFormat setDataTable clearDataTable setBuiltinStyle setCustomStyle getTotalWidth getTotalColumnWidth getTotalRowHeight unMerge replaceValue

Notes

• Range is "get it and throw it away". ws.getRange("A1:A1") returns a new instance on every call, so there is no need to keep holding it in a variable.
• getValue() returns a map. Shaped like { "A1": "100", "B1": "300" }, and all values are strings. Convert with Number(...) to treat them as numbers.
• Two ways to get a Range.
  • ws.getRange("A1:B2") — by string address. Even a single cell is passed in range form as "A1:A1".
  • ws.getCells(row, col) / ws.getCells(startRow, startCol, endRow, endCol) — by numbers (row, col). Rows and columns are 1-based: (1,1) = A1, (3,1,3,3) = A3:C3. Handy when looping over row/column numbers because you don't have to assemble address strings.
  • For number ⇔ string conversion use app.convertFromRowColNumber(row, col) / app.convertFromRowColNumber2(sr, sc, er, ec) / app.convertToColumnNumber("B").
• Formulas are computed at run time. Right after setFormula() you can read the result with getValue(true) (no need to wait for save()).

Caveats

• close() exists only as a WorkBook method. App / WorkSheet / Range have no close-style methods.
• saveAs() only "writes the current content to a different file"; it does not switch the destination of later saves. This differs from Excel VBA's SaveAs.

  wb.save()                  → written to base.xlsx
  wb.saveAs("copy.xlsx")     → "the content at this point" is written to copy.xlsx
  wb.getBookPath()           → still base.xlsx (not switched)
  ws.getRange(...).setValue(...)
  wb.save()                  → written to base.xlsx (not copy.xlsx)

• Do not prefix formulas with =. Use setFormula("SUM(A1:A3)").
• A license banner line is printed to stdout at startup (once per process). Keep it in mind when writing code that parses standard output.

See also

• Index
• Next sample: Building a table with values and formulas
• API reference

  Node.js Python Java WebAssembly

  App / WorkBook / WorkSheet / Range

  App / WorkBook / WorkSheet / Range

  App / WorkBook / WorkSheet / Range

  App / WorkBook / WorkSheet / Range