ReoGrid JSON フォーマット

ReoGrid JSON は、ReoGrid ワークブックのネイティブなシリアライズ形式です。xlsx は交換用フォーマットで ReoGrid 固有機能を一部失いますが、ReoGrid JSON はロスレス。カスタムセルタイプ、条件付き書式、入力規則、アウトライン、名前定義、保護まで、ランタイムが必要とするすべてを往復できます。

ReoGrid は xlsx の読み込みもできるため、この API はそのまま xlsx → JSON 変換器にもなります。.xlsx をグリッドに読み込んで toJson() を呼ぶだけ。すべてブラウザ内で完結し、ファイルはサーバーに送信されません。

要点 — ワークブック全体は grid.toJson() で保存、grid.loadJson(doc) で復元。単一ワークシートなら writeReoGridJson(ws) / readReoGridJson(ws, doc)。

どんなときに使うか

ReoGrid JSON はすべてを保持します。セル値をオブジェクトの配列として欲しいだけなら、よりコンパクトでアプリ向きのデータ抽出レシピが適しています。

クイックスタート（単一ワークシート）

ワークシート単位のヘルパーは @reogrid/lite / @reogrid/pro の両方から再エクスポートされています（深いインポート不要）。

import {
  createReogrid,
  writeReoGridJson,
  readReoGridJson,
  parseReoGridJson,
  type ReoGridJsonDocument,
} from '@reogrid/lite';

const { worksheet } = createReogrid('#grid');

// シリアライズ → 文字列
const doc: ReoGridJsonDocument = writeReoGridJson(worksheet);
localStorage.setItem('my-sheet', JSON.stringify(doc));

// 復元
const saved = localStorage.getItem('my-sheet');
if (saved) {
  const parsed = parseReoGridJson(saved); // 文字列 → 検証済みドキュメント
  readReoGridJson(worksheet, parsed);     // ワークシートへ適用
}

parseReoGridJson はドキュメントを検証し（format のマジック文字列とメジャー version をチェック）、不一致なら例外を投げます。外部ファイルや壊れたファイルを誤って適用することがありません。

ワークブック全体（全シート）

複数シートのワークブックでは、インスタンスのメソッドが全シート＋アクティブシート番号を一度に保存・復元します。

const grid = createReogrid('#grid');

// ワークブック全体を保存
const doc = grid.toJson();
await fetch('/api/save', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(doc),
});

// あとで読み戻す
const doc2 = await (await fetch('/api/load')).json();
grid.loadJson(doc2); // 全シートを置き換え、doc.workbook.activeSheet を有効化

loadJson は unknown を受け取り、適用前に検証します。response.json() の結果をそのまま渡せます。

xlsx → JSON 変換

xlsx インポートと toJson() を組み合わせれば、完全にクライアント側でスプレッドシートを JSON に変換できます。

const grid = createReogrid('#grid');

document.querySelector<HTMLInputElement>('#file')!
  .addEventListener('change', async (e) => {
    const file = (e.target as HTMLInputElement).files?.[0];
    if (!file) return;

    await grid.loadFromFile(file);   // .xlsx を解析・描画
    const json = grid.toJson();      // フル忠実度の ReoGrid JSON

    console.log(JSON.stringify(json, null, 2));
  });

Lite と Pro。 xlsx の読み込みは両ティアで可能ですが、Lite は 100 行 × 26 列を超えるファイルを切り詰めます。実務の任意のスプレッドシートを切り詰めずに変換するには Pro を使ってください。すぐ使えるツールはオンライン XLSX → JSON 変換器、スニペットは xlsx-to-json レシピを参照。

API リファレンス

書き込みオプション

writeReoGridJson(worksheet, {
  sheetName: 'Q3',                          // 単一ワークシート時のシート名
  activeSheet: 0,                           // 読み込み時にアクティブにする番号
  definedNames: [{ name: 'TaxRate', address: "Sheet1!$B$1" }],
  meta: { appName: 'Budget App', author: 'jane', createdAt: '2026-06-27T00:00:00Z' },
});

stringifyReoGridJson(worksheet, { pretty: true }); // 2スペースインデントの文字列

読み込みオプション

readReoGridJson(worksheet, doc, {
  rebuildFormulas: false, // 一括読み込み時は再計算を遅延し、後で ws.rebuildFormulas() を呼ぶ
});

複数シート

writeReoGridJson は配列を受け取り、readReoGridJsonAll は渡したファクトリでシートを再構築します（シートタブの管理はこのレイヤーの上＝アプリ側）。

import { writeReoGridJson, readReoGridJsonAll } from '@reogrid/lite';

// 複数ワークシートを1つのドキュメントに書き出す
const doc = writeReoGridJson([
  { name: 'Jan', worksheet: janSheet },
  { name: 'Feb', worksheet: febSheet },
], { activeSheet: 1 });

// 読み戻す — createWorksheet がエントリごとに新しいシートを生成
const { sheets, activeSheet } = readReoGridJsonAll(doc, {
  createWorksheet: () => new Worksheet(),
});

グリッドに紐づくワークブックの一般的なケースでは、grid.toJson() / grid.loadJson() を使うのが簡単です（タブバーとアクティブシートを面倒見てくれます）。

ドキュメント構造

実ファイルでコンパクトに保てるよう設計されています。セル・スタイル・結合・罫線はスパース配列（密な行列にしない）、キーは短く（r, c, v, f, s）、スタイルと数値書式は番号参照の共有辞書、行・列サイズはランレングス圧縮です。

{
  "format": "reogrid-json",     // マジック文字列 — 不一致は拒否
  "version": 1,                  // メジャーバージョン — 新しすぎる版は拒否
  "meta": { "appName": "Budget App", "modifiedAt": "2026-06-27T09:00:00Z" },
  "workbook": {
    "activeSheet": 0,
    "sheets": [
      {
        "name": "Sheet1",
        "rowCount": 100,
        "columnCount": 26,
        "cells": [
          { "r": 0, "c": 0, "v": "Region", "s": 1 },   // v = 値, s = スタイル番号
          { "r": 1, "c": 0, "v": "Tokyo" },
          { "r": 1, "c": 1, "v": "1200" },
          { "r": 2, "c": 1, "f": "=B2*1.1" }            // f = 数式ソース
        ],
        "merges": [{ "r": 0, "c": 0, "rs": 1, "cs": 3 }]
      }
    ]
  },
  "styles": [ {}, { "bold": true, "bg": "#f1f5f9" } ],   // 番号 0 = 既定スタイル
  "numberFormats": ["General", "#,##0.00"],
  "definedNames": [{ "name": "TaxRate", "address": "Sheet1!$B$1" }]
}

ファイルは手書き編集を想定していません。ライターは常に最もコンパクトな有効ドキュメントを生成し、リーダーはその最適化に関係なく任意の有効ドキュメントを受理します。

保持される内容

エディタをユーザーが残したまま再現したいときは ReoGrid JSON、Excel や他ツールで開く必要があるときは xlsx を使います。

関連

• XLSX インポート・エクスポート — .xlsx の読み書き
• ブラウザで XLSX を JSON に変換 — How-to 記事
• ExcelデータをアプリのJSONとして取り出す — 素の行オブジェクト
• AIでスプレッドシートを一括処理 — xlsx → JSON → LLM
• レシピ: xlsx → JSON · xlsx → データ行