univer-node-backend

Univer Node.js バックエンド

ブラウザーを使わずに Node.js 環境で Univer を実行するためのガイドです。ヘッドレスでのスプレッドシート処理、自動レポート生成、サーバーサイドでの数式計算、バッチデータ操作に使用します。

互換性：このスキルは Univer v0.21.x／Univer Pro v0.20.x 向けに作成されています。Univer のアーキテクチャに基づき、Node.js のサポートはブラウザーのサポートとアイソモーフィックです。

前提条件：univer-integrate スキル（基本的なプラグインアーキテクチャ、Facade API、プラグインの登録順序）に精通していることを前提としています。このスキルでは、Node.js 固有の違いのみを扱います。

クイックスタート

1. 依存関係をインストールする

npm install @univerjs/core @univerjs/engine-formula @univerjs/sheets @univerjs/sheets-formula @univerjs/rpc-node

Node.js で Pro 機能を使用する場合：

npm install @univerjs-pro/license @univerjs-pro/engine-formula @univerjs-pro/sheets-pivot @univerjs-pro/collaboration-client-node

2. Node.js で Univer インスタンスを作成する

import { LocaleType, Univer } from '@univerjs/core';
import { FUniver } from '@univerjs/core/facade';
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
import { UniverSheetsPlugin } from '@univerjs/sheets';
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula';
import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter';

// Facade side-effect imports for Node.js
import '@univerjs/sheets/facade';
import '@univerjs/engine-formula/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/sheets-filter/facade';
import '@univerjs/sheets-numfmt/facade';

const univer = new Univer({
  locale: LocaleType.ZH_CN,
});

univer.registerPlugin(UniverFormulaEnginePlugin);
univer.registerPlugin(UniverSheetsPlugin);
univer.registerPlugin(UniverSheetsFormulaPlugin);
univer.registerPlugin(UniverSheetsFilterPlugin);

const univerAPI = FUniver.newAPI(univer);
const workbook = univerAPI.createWorkbook({});
const sheet = workbook.getActiveSheet();

sheet.getRange('A1').setValue({ v: 123 });
sheet.getRange('B1').setValue({ f: '=SUM(A1) * 6' });

console.log(workbook.save());

3. 数式計算用の Node.js ワーカー（任意）

数式の処理負荷が高い場合は、フォークしたプロセスに処理を委任します。

// main.ts
import path from 'node:path';
import { LocaleType, Univer } from '@univerjs/core';
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
import { UniverRPCNodeMainPlugin } from '@univerjs/rpc-node';
import { UniverSheetsPlugin } from '@univerjs/sheets';

const univer = new Univer({ locale: LocaleType.ZH_CN });

univer.registerPlugin(UniverFormulaEnginePlugin, { notExecuteFormula: true });
univer.registerPlugin(UniverSheetsPlugin);

const workerPath = path.join(__dirname, 'worker.js');
univer.registerPlugin(UniverRPCNodeMainPlugin, { workerSrc: workerPath });

// worker.js
import { LocaleType, Univer } from '@univerjs/core';
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
import { UniverRPCNodeWorkerPlugin } from '@univerjs/rpc-node';
import { UniverSheetsPlugin } from '@univerjs/sheets';

const univer = new Univer({ locale: LocaleType.ZH_CN });

univer.registerPlugin(UniverSheetsPlugin, { onlyRegisterFormulaRelatedMutations: true });
univer.registerPlugin(UniverFormulaEnginePlugin);
univer.registerPlugin(UniverRPCNodeWorkerPlugin);

主な概念

ブラウザーと Node.js の違い

項目	ブラウザー	Node.js
UI プラグイン	必須（UniverUIPlugin、*-ui）	すべての *-ui プラグインを省略
レンダリングエンジン	UniverRenderEnginePlugin	チャート／図形を使用する場合を除き省略
RPC	UniverRPCMainThreadPlugin + Worker	UniverRPCNodeMainPlugin + fork()
ワーカープラグイン	UniverRPCWorkerThreadPlugin	UniverRPCNodeWorkerPlugin
CSS のインポート	必須	不要
テーマ	@univerjs/themes の defaultTheme	不要

Node.js でのプラグイン登録順序

1. UniverLicensePlugin (Pro only)
2. Engine plugins (UniverFormulaEnginePlugin / UniverProFormulaEnginePlugin)
3. RPC (UniverRPCNodeMainPlugin, if using worker)
4. Unit core (UniverSheetsPlugin, UniverDocsPlugin)
5. Feature plugins (UniverSheetsFormulaPlugin, UniverSheetsFilterPlugin, etc.)
6. Pro features (UniverSheetsPivotTablePlugin, etc.)

Node.js の Facade インポート

すべての Facade インポートが Node.js で動作するわけではありません。ブラウザー API に依存しないパッケージのみをインポートしてください。

// Safe in Node.js
import '@univerjs/core/facade';
import '@univerjs/sheets/facade';
import '@univerjs/engine-formula/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/sheets-filter/facade';
import '@univerjs/sheets-numfmt/facade';
import '@univerjs/sheets-data-validation/facade';
import '@univerjs/sheets-conditional-formatting/facade';
import '@univerjs/sheets-hyper-link/facade';
import '@univerjs/sheets-thread-comment/facade';
import '@univerjs/sheets-drawing/facade';
import '@univerjs/sheets-sort/facade';
import '@univerjs/sheets-table/facade';
import '@univerjs/sheets-note/facade';

// Pro (safe in Node.js)
import '@univerjs-pro/sheets-pivot/facade';
import '@univerjs-pro/sheets-chart/facade';
import '@univerjs-pro/sheets-shape/facade';
import '@univerjs-pro/sheets-sparkline/facade';
import '@univerjs-pro/collaboration-client/facade';

// Unsafe in Node.js (depend on browser APIs)
// import '@univerjs/ui/facade';
// import '@univerjs/sheets-ui/facade';
// import '@univerjs/sheets-drawing-ui/facade';
// import '@univerjs/sheets-formula-ui/facade';

よくあるタスク

バッチレポートの生成

const workbook = univerAPI.createWorkbook({});
const sheet = workbook.getActiveSheet();

// Populate data from database
const rows = await db.query('SELECT * sales');
rows.forEach((row, i) => {
  sheet.getRange(i + 1, 0).setValue(row.date);
  sheet.getRange(i + 1, 1).setValue(row.amount);
});

// Add formula summary
const lastRow = rows.length;
sheet.getRange(lastRow + 1, 1).setValue({ f: `=SUM(B2:B${lastRow})` });

// Export snapshot
const snapshot = workbook.save();

既存のブックを読み込んで変更する

const existingData = JSON.parse(fs.readFileSync('input.json', 'utf8'));
const workbook = univerAPI.createWorkbook(existingData);
const sheet = workbook.getActiveSheet();

sheet.getRange('A1').setValue('Updated');
fs.writeFileSync('output.json', JSON.stringify(workbook.save()));

サーバーサイドでの数式計算

// Without worker (simple workloads)
univer.registerPlugin(UniverFormulaEnginePlugin);

// With worker (heavy workloads)
univer.registerPlugin(UniverFormulaEnginePlugin, { notExecuteFormula: true });
univer.registerPlugin(UniverRPCNodeMainPlugin, { workerSrc: './worker.js' });

サーバーでカスタム関数を登録する

const formulaEngine = univerAPI.getFormula();
formulaEngine.registerFunction(
  'DISCOUNT',
  (price, percent) => price * (1 - percent / 100),
  'Calculate price after discount'
);

Pro の Node.js 統合

Node.js で Univer Pro の機能（コラボレーション、ピボット、チャート、図形）を使用する方法については、references/node-pro-integration.md を参照してください。

参考資料

• Node プラグインレジストリ：references/node-plugin-registry.md — Node.js 用プラグインの完全な一覧、登録順序、ワーカーの設定、ブラウザー専用機能の除外
• Node の一般的なタスク：references/node-common-tasks.md — バッチ処理、JSON のインポート／エクスポート、数式計算のパターン、カスタム関数、ヘッドレスモードでのイベント処理
• Pro の Node.js 統合：references/node-pro-integration.md — Pro 数式エンジン、コラボレーションクライアントの Node 対応、バックエンドでのピボット／チャート／図形、サーバー向けライセンスの設定