概要 — オブジェクトモデルと基本の流れ
level: basic / verified: 2026-10-04 / 5言語タブ対応 / 目次へ / English
やりたいこと
osbxl の全体像をつかむ。
- オブジェクトの階層(
App→WorkBook→WorkSheet→Range) - 基本の流れ(新規作成 / 既存ブックを開く → シート → Range → 値・数式 → save / saveAs / close)
- 4 クラスの主要メソッド
個々の機能の詳細は、このページの後続サンプルで扱います。
前提
各言語のモジュールをダウンロードページから入手してインストールします。
PHP の OS 別の詳しい導入手順(Linux / macOS / Windows、Composer が未インストールの場合を含む)はクイックスタートを参照してください。
WebAssembly 版は MEMORY64(Wasm 3.0)ビルドのため、実行環境側の対応が必要です (Chrome/Edge 133〜・Firefox 134〜・Node.js 24〜。Safari は現在未対応)。
入口は言語ごとに異なります。namespace 構成(操作対象クラス / dto / chart / enums)は4言語共通です。
npm install ./nodeosbxl-2.0.1.tgz
| 言語 | 入口 | 主な namespace |
|---|---|---|
| Node.js | require("nodeosbxl") | nodeosbxl / dto / chart / enums |
| Python | import pyosbxl | pyosbxl / pyosbxl.dto / pyosbxl.chart / pyosbxl.enums |
| Java | import com.osboffice.osbxl.* | dto / chart / enums 等のパッケージ |
| WebAssembly | createOsbxl(createModule) | osbxl / dto / chart / enums |
下表は Node.js 表記です。各 namespace の中身の数は4言語共通です。
| namespace | 中身 | 数 |
|---|---|---|
nodeosbxl | 操作の対象になるクラス(App / WorkBook / WorkSheet / Range / Font / Chart 系の入口 など) | 29 クラス |
dto | データの受け渡しに使うオブジェクト(BordersObject, FontObject, ColorObject など) | 40 クラス |
chart | グラフ専用オブジェクト(ChartObject, Axis, ChartTitle など) | 43 クラス |
enums | Excel 互換の列挙型(XlFont, XlChartType, XlIndexColor など) | 127 種 |
オブジェクトモデル
App ← すべての入口。ブックを開く/作る、セルアドレスの変換
│
├─ createWorkBook() ─┐
├─ openWorkBook() ─┴→ WorkBook ← xlsx ファイル 1 つ
│ │
│ ├─ openWorkSheet() → WorkSheet ← シート 1 つ
│ │ │
│ │ ├─ getRange("A1:B2") → Range
│ │ │ ※ getCells(0,0,1,1) でも同じ Range が取れる (0-based)
│ │ │ │
│ │ │ ├─ 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()
│
└─ convertFromRowColNumber() などのユーティリティ
この階層を常に上から辿るのが osbxl の基本です。 Range より下(Font, Color, Borders …)は「取得して、そのオブジェクトの setter を呼ぶ」形になります。
基本の流れ
[1] new App() App を生成する
[2] createWorkBook(path) 新規ブックを作る
openWorkBook(path) 既存のブックを開く
[3] openWorkSheet(name) ワークシートを開く
[4] getRange("A1:B2") Range を取得する(getCells(0,0,1,1) でも同じ。0-based)
[5] setValue() / setFormula() 値・数式を入れる
[6] getValue(true) 結果を読み戻す
[7] save() / saveAs(path) 保存する
[8] close() ブックを閉じる
コード
実行結果:
// basic-flow.js — 新規作成 → 編集 → 保存 → 開き直し → 別名保存 の一連の流れ
const { nodeosbxl } = require("nodeosbxl");
const app = new nodeosbxl.App(); // [1] App を生成
// ---------- 新規ブックを作って編集し、保存する ----------
let wb = app.createWorkBook("flow.xlsx"); // [2] 新規作成
console.log("[2] createWorkBook -> getBookPath =", wb.getBookPath());
let ws = wb.openWorkSheet("Sheet1"); // [3] ワークシートを開く
console.log("[3] openWorkSheet -> シート名 =", ws.getName());
// [4] Range を取得して [5] 値を設定
// 数値(行, 列)で取る ws.getCells(0, 0) も getRange("A1:A1") と同じ Range を返します (0-based)
ws.getRange("A1:A1").setValue("新規作成");
ws.getRange("B1:B1").setFormula("100*3"); // [5] 数式を設定(先頭の "=" は付けない)
console.log("[6] getValue(true) -> B1 =", ws.getRange("B1:B1").getValue(true)["B1"]);
wb.save(); // [7] 保存
console.log("[7] save() 完了");
wb.close(); // [8] 閉じる(WorkSheet の close は不要)
console.log("[8] close() 完了");
// ---------- 既存ブックを開いて、別名で保存する ----------
wb = app.openWorkBook("flow.xlsx"); // [2'] 既存のブックを開く
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("開き直して追記");
wb.saveAs("flow-copy.xlsx"); // [7'] 別名で保存
console.log("[7'] saveAs() 完了 -> getBookPath =", wb.getBookPath());
wb.close(); // [8']
console.log("[8] close() 完了");
[2] createWorkBook -> getBookPath = <実行ディレクトリ>/flow.xlsx
[3] openWorkSheet -> シート名 = Sheet1
[6] getValue(true) -> B1 = 300
[7] save() 完了
[8] close() 完了
[2'] openWorkBook -> A1 = 新規作成 / B1 = 300
[7'] saveAs() 完了 -> getBookPath = <実行ディレクトリ>/flow.xlsx
[8] close() 完了
flow.xlsx と flow-copy.xlsx の 2 つができます。
流れのポイント
Appは 1 プロセスに 1 つでよい。 ブックを複数扱う場合も同じappからcreateWorkBook()/openWorkBook()を呼びます。- 相対パスは絶対パスに解決される。
createWorkBook("flow.xlsx")の後、getBookPath()はカレントディレクトリを含む絶対パスを返します。 WorkSheetを閉じる処理は無い。close()はWorkBookのメソッドだけです。 シートはwb.close()でまとめて解放されます。save()とsaveAs()の違いに注意(下記の「注意点」参照)。
主要メソッド
App(10 メソッド)
new nodeosbxl.App() で生成します。ブックの開閉と、アドレス変換ユーティリティを持ちます。
| メソッド | 説明 |
|---|---|
getVersion() | バージョン番号を返します。 |
createWorkBook(path, defaultFont?, defaultFontSize?) | ワークブックを作成します。 |
openWorkBook(path) | ワークブックを開きます。 |
openPasswordWorkBook(path, password) | パスワード付きワークブックを開きます。 |
convertFromRowColNumber(row, col) | セルの数値表記を A1C1 表記に変換します。(1,1) → "A1" |
convertFromRowColNumber2(startRow, startCol, endRow, endCol) | セル範囲の数値表記を A1C1 表記に変換します。(1,1,2,3) → "A1:C2" |
convertToColumnNumber("B") | 列の A1 表記を数値表記に変換します。→ 2 |
convertFromColumnNumber(3) | 列の数値表記を A1 表記に変換します。→ "C" |
getNumericValue(dateTimeObject, is1904?) | 日付時刻オブジェクトから Excel 内部のシリアル値を取得します。 |
calculateHexColor(bookPath, colorObj, isForeGroundColor) | ワークブック固有の色情報を加味した HEX 値を取得します。 |
convertFromRowColNumber / convertFromRowColNumber2 には絶対参照("$A$1")を返すオーバーロードもあります。
WorkBook(27 メソッド)— 主要 12
xlsx ファイル 1 つに対応します。
| メソッド | 説明 |
|---|---|
getBookPath() | ワークブックのファイルパスを返します。 |
openWorkSheet(sheetName | index) | ワークシートをシート名またはインデックス(0 始まり)で開きます。※旧 openWorkSheetByIndex は非推奨。 |
addWorkSheet(sheetName, position?) | ワークシートを追加します。 |
deleteWorkSheet(sheetName) | ワークシートを削除します。 |
moveSheet(sheetName, position) | ワークシートを移動します。 |
getSheetCount() | ワークシート数を取得します。 |
getSheetNumber(sheetName) | ワークシートのシート番号を取得します。 |
save() / save(password) | ワークブックを同一ファイルに保存します。 |
saveAs(path) / saveAs(path, password) | ワークブックを別ファイルに保存します。 |
close() | ワークブックを閉じます。 |
isDate1904() | Excel の日付 1904 年形式であるかを取得します。 |
getNames
addCustomStyle
getCustomStyle
deleteCustomStyle
addCustomTableStyle
addPivotCustomTableStyle
getCustomTableStyle
deleteCustomTableStyle
addExternalWorkBook
updateExternalWorkBook
getExternalWorkBookPath
setCompanyName
setManagerName
setCreateAuthor
setLastAuthor
WorkSheet(44 メソッド)— 主要 14
シート 1 つに対応します。ここから下のオブジェクト(Range / Sort / PivotTable / Chart …)へ辿る入口です。
| メソッド | 説明 |
|---|---|
getRange("A1:B2") | セル範囲クラスインスタンスを取得します。 |
getCells(row, col) / getCells(sr, sc, er, ec) | セル範囲クラスインスタンスを数値指定で取得します。 |
getRow(rowNum) | 行クラスインスタンスを取得します。 |
getCol(colNum) | 列クラスインスタンスを取得します。 |
getName() / setName(name) | シート名称の取得 / 設定を行います。 |
isActive() / activate(...) | シートタブが起動時の表示項目かどうかの取得 / 設定を行います。 |
insertRow(startRow, numOfRows) | 行の挿入を行います。 |
deleteRow(startRow, numOfRows) | 行の削除を行います。 |
insertCol(startCol, numOfCols) | 列の挿入を行います。 |
deleteCol(startCol, numOfCols) | 列の削除を行います。 |
setRangeData(startAddress, data) | 2次元配列によるセル値の超高速一括流し込みを行います(数値自動認識)。 |
setRangeFormulas(startAddress, formulas) | 2次元配列による数式の超高速一括流し込みを行います。 |
getFormatConditions
getAutoFilter
getSort
getComments
getHyperLinks
getListObjects
getPivotTables
getShapes
getWindow
getHPageBreaks
getVPageBreaks
getChartObject
addChartObject
deleteChartObject
getPageSetupObject
setPageSetupObject
getActiveCell
setActiveCell
clearRow
copyRow
clearCol
copyCol
insertCell
deleteCell
clearCell
copyCell
setRowOutline
clearRowOutline
setColOutline
clearColOutline
Range(31 メソッド)— 主要 16
セル範囲に対応します。値・数式の読み書きと、書式オブジェクトへの入口です。
| メソッド | 説明 |
|---|---|
getValue(rawValue?) | セルの値の取得を行います。true で生値(数式の結果)。 |
getFormula() | 数式の取得を行います。 |
setValue(value, forceString?, numberFormat?) | セル値の設定を行います(汎用メソッド)。 |
setNumberValue(value, ...) | セル値の設定を行います(数値設定メソッド)。 |
setDateValue(dateTimeObject, ...) | セル値の設定を行います(日付/時刻設定メソッド)。 |
setDateStringValue(str, ...) | セル値の設定を行います(日付/時刻を文字列から入力)。 |
setBooleanValue(bool, ...) | セル値の設定を行います(Boolean 値設定メソッド)。 |
setFormula(formula, isArray?, setAllCell?) | 数式の設定を行います。 |
getFont() | フォントオブジェクトインスタンスを取得します。 |
getBorders() | 枠線一括オブジェクトインスタンスを取得します。 |
getFill() | フィルオブジェクトインスタンスを取得します。 |
getAlignment() | セルの配置位置指定オブジェクトインスタンスを取得します。 |
setNumberFormat(format) | 表示書式の設定を行います。 |
merge(mergeEachRow?) | セル範囲をマージします。 |
clearContent() | セルのクリアを行います。 |
getAddress() | Range の選択範囲を取得します。 |
getProtection
getCharacters
getPhonetics
getNumberFormat
clearNumberFormat
clearAllFormat
setBuiltinStyle
setCustomStyle
setDataTable
clearDataTable
getTotalWidth
getTotalColumnWidth
getTotalRowHeight
unMerge
replaceValue
解説
Rangeは「取得して使い捨て」でよい。ws.getRange("A1:A1")は呼ぶたびに新しいインスタンスを返すので、 変数に保持し続ける必要はありません。getValue()の戻り値はマップ。{ "A1": "100", "B1": "300" }の形で、値はすべて文字列です。
数値として扱うにはNumber(...)で変換します。- Range の取り方は 2 通り(デフォルトは 0 始まり)。
ws.getRange("A1:B2")— 文字列アドレスで指定。単一セルでも"A1:A1"と範囲の形で渡します。ws.getCells(row, col)/ws.getCells(startRow, startCol, endRow, endCol)— 数値(行, 列)で指定。 バージョン 2.0 より既定で 0 始まり (zeroBase = true) となり、(0, 0)= A1、(2, 0, 2, 2)= A3:C3 です。プログラムのループ配列インデックスとそのまま直結でき便利です。- バージョン 1 互換(1 始まり)で動作させたい場合:
new App(false)(Python はApp(zeroBase=False))と指定することで、従来の 1 始まりとして動作します。 - 数値 ⇔ 文字列の変換は
app.convertFromRowColNumber(row, col)/app.convertFromRowColNumber2(sr, sc, er, ec)/app.convertToColumnNumber("B")を使います(これらも App の zeroBase 設定に応じた数値を扱います)。
- 数式は実行時に計算される。
setFormula()の直後にgetValue(true)で計算結果を読めます (save()を待つ必要はありません)。
注意点
- ワークブックは、一意性を確保するため内部でロックされ、この処理によって同一ワークブックの同時読込・書込は起こりません。
close()はWorkBookのメソッドだけ。App/WorkSheet/Rangeに close 系のメソッドはありません。saveAs()は「その時点の内容を別ファイルに書き出す」だけで、以降の保存先は切り替わりません。 Excel VBA のSaveAsとは挙動が違います。wb.save() → base.xlsx に書かれる wb.saveAs("copy.xlsx") → copy.xlsx に「この時点の内容」が書かれる wb.getBookPath() → base.xlsx のまま(切り替わらない) ws.getRange(...).setValue(...) wb.save() → base.xlsx に書かれる(copy.xlsx ではない)- 数式に先頭の
=を付けない。setFormula("SUM(A1:A3)")です。 - 起動時にライセンス表示が stdout に 1 行出力されます(プロセスにつき 1 回)。
標準出力をパースする処理を書く場合は注意してください。
関連
- 目次
- 次のサンプル: 値と数式を入れて表を作る