数値フォーマット

ReoGrid Web は Excel 互換の数値フォーマットコードをサポートしています。 フォーマットコードは、セルの格納値を変えずに表示形式を制御します。

フォーマットの適用

セルまたは範囲に setFormat() を使うか、format プロパティに直接代入します。

// 単一セル
worksheet.cell('B2').setValue('4999').setFormat('$#,##0.00')

// 範囲
worksheet.range('B2:B10').setFormat(NumberFormat.currency('$', 2))

// プロパティ代入
worksheet.cell('C3').format = '0.00%'

// フォーマットのクリア
worksheet.cell('B2').format = undefined

NumberFormat ヘルパー

NumberFormat ユーティリティは一般的なケースのフォーマットコードを生成します。 createReogrid と一緒にインポートします:

import { createReogrid, NumberFormat } from '@reogrid/lite'

NumberFormat.number(decimals?, grouping?)

NumberFormat.number()          // '#,##0'       → 1,234,567
NumberFormat.number(2)         // '#,##0.00'    → 1,234,567.89
NumberFormat.number(2, false)  // '0.00'        → 1234567.89

NumberFormat.percent(decimals?)

NumberFormat.percent()   // '0%'     → 43%
NumberFormat.percent(2)  // '0.00%'  → 42.75%

セルの値は小数（例: '0.4275' → 42.75%）で格納します。

NumberFormat.currency(symbol, decimals?, position?)

NumberFormat.currency('$', 2)            // '$#,##0.00'  → $4,999.00
NumberFormat.currency('€', 2)            // '€#,##0.00'  → €4,999.00
NumberFormat.currency('¥', 0)            // '¥#,##0'     → ¥4,999
NumberFormat.currency('円', 0, 'suffix') // '#,##0円'    → 4,999円

NumberFormat.date(pattern?)

NumberFormat.date()               // 'yyyy-mm-dd'   → 2025-03-17
NumberFormat.date('MM/dd/yyyy')   // 'MM/dd/yyyy'   → 03/17/2025
NumberFormat.date('d MMM yyyy')   // 'd MMM yyyy'   → 17 Mar 2025

セルの値は Excel シリアル日付（シリアル値 1 = 1900-01-01）である必要があります。 xlsx ファイルを読み込む場合、日付セルにはシリアル値とフォーマットコードが既に含まれているため、追加の作業は不要です。

NumberFormat.time(pattern?)

NumberFormat.time()               // 'HH:mm:ss'     → 18:00:00
NumberFormat.time('h:mm AM/PM')   // 'h:mm AM/PM'   → 6:00 PM

セルの値は1日の小数部分（例: '0.75' = 18:00）である必要があります。

低レベル API

// フォーマット設定
ws.setCellNumberFormat(row, column, '#,##0.00');

// フォーマット取得
const fmt = ws.getCellNumberFormat(row, column);

// フォーマットクリア
ws.clearCellNumberFormat(row, column);

生のフォーマットコードの使用

Excel 互換のフォーマットコード文字列を直接渡すこともできます:

worksheet.cell('A1').setFormat('#,##0.0')       // 小数1桁、桁区切りあり
worksheet.cell('A2').setFormat('0.000%')         // パーセント、小数3桁
worksheet.cell('A3').setFormat('"€"#,##0.00')   // 引用符付き記号
worksheet.cell('A4').setFormat('[Red]0.00')      // カラー修飾子

フォーマットコードリファレンス

千単位スケーリング

書式コードの末尾に置いたカンマは、表示する値をカンマ 1 つにつき 1,000 で割ります。集計列を「千円」「百万円」単位で書くための標準的な方法です。

ws.cell('B2').setFormat('#,##0,')          // 8,500,000  → 8,500
ws.cell('B3').setFormat('#,##0.0,,"百万円"') // 2,400,000  → 2.4百万円

数字のプレースホルダーの間にあるカンマ（#,##0）は桁区切りで、スケーリングは行いません。

v1.6.0 で修正。 小数部の後ろにカンマを置く形 —— 0.0, や #,##0.0,, という、Excel が標準的に書き出すほうの並び —— はスケーリングされず、しかもカンマが書式から取り除かれないため解析ごと失敗し、0.0,,"M" は 2,400,000 を 2400000.0,,M と表示していました。現在はどちらの形も動作するため、集計列でよく使う [>=1000000]#,##0.0,,"百万円";[>=1000]#,##0.0,"千円";0"円" が Excel と同じ結果になります。

なお、スケーリング後の数値はパターンが求める桁に丸められるため、#,##0, を 8,500 に当てると 9 と読めます。正確な数字が必要な場所ではなく、集計列で使ってください。