同じ数値を同じセルに入れても、用途が変われば見せ方も変わります。財務の表では金額に桁区切りと小数第 2 位までを付け、負の値は括弧でくくります。工程表では日付のシリアル値を「2026年11月2日 月曜日」として表示します。単価表では 1234.5 を 1,234.50 USD と書き、ゼロは短いダッシュで済ませます。違いはデータそのものではなく、同じ値に掛ける NumberFormat の違いです。ブックをコードで一括生成する場合、書式もコードで入れておかなければ、開くたびに手で設定し直すことになります。
Spire.XLS ではこの操作がセルの NumberFormat プロパティに対応します。書式コードをセルまたは範囲に渡して保存すると、Excel はそのコードに従って数値を描画し、保存値はそのまま残ります。書式コードそのものはプレースホルダー、セミコロン、角括弧、引用符という 4 種類の記号で組み立てられ、以下の 7 種類はそれらの記号の組み合わせ方の違いに対応します。
本記事では Free Spire.XLS for Python を使用します。インストールコマンドは次のとおりです。
pip install Spire.XLS.Free
オブジェクトモデル
数値書式はセルに紐づき、フォントや罫線と同じく CellStyle に属します。Worksheet.Range で範囲を取得し、そのまま代入できます。
| オブジェクト | 役割 | 本記事で使うメンバー |
|---|---|---|
Workbook |
ブックのコンテナ |
CreateEmptySheets、Worksheets、SaveToFile
|
Worksheet |
ワークシート |
Range、Name、AutoFitColumn、ToImage
|
CellRange |
セルまたは範囲 |
NumberValue、Text、NumberFormat、DisplayedText、Style
|
CellStyle |
セルのスタイル |
NumberFormat、Font、Interior、HorizontalAlignment
|
範囲に代入すれば一括適用になります。sheet.Range["C2:C100"].NumberFormat = "0.00" の 1 行で 99 個のセルが対象になり、各セルの保存値は変わりません。DisplayedText は現在の書式で描画したテキストを返すので、書式が意図どおり効いているかの確認に使えます。
1 基本の数値：プレースホルダーが小数位と桁区切りを決める
書式コードの 0 は必ず表示する桁、# は省略できる桁です。小数点以下の 0 の個数がそのまま表示する小数位になり、表示は保持している精度と独立しています。1234.5678 は 0.00 で 1234.57 と表示され、値は 1234.5678 のままです。整数部のカンマは桁区切り、% は 100 倍してパーセント記号を付けます。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
cases = [
("General", 1234.5678),
("0", 1234.5678),
("0.00", 1234.5678),
("#,##0", 1234567.891),
("#,##0.00", 1234567.891),
("0.00%", 0.4567),
("0.00E+00", 1234.5678),
("00000", 42),
]
for row, (fmt, value) in enumerate(cases, start=1):
cell = sheet.Range[row, 1]
cell.NumberValue = value
cell.NumberFormat = fmt
sheet.AutoFitColumn(1)
workbook.SaveToFile("basic.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
General は書式未設定の既定状態で、値をそのまま表示します。0 は小数を 1 桁も残さず、1234.5678 は四捨五入されて 1235 になります。00000 は 5 個の 0 で整数部を 5 桁まで埋め、42 は 00042 と表示されます。管理番号のような桁を揃えたい値はこの書き方で揃います。指数表記の E+00 も同じプレースホルダーの組み合わせで、指数部の桁数は 0 の個数で決まります。
2 セクション：1 本のコードで正・負・ゼロ・文字列を扱う
書式コードはセミコロンで最大 4 つの区切りに分かれ、順に正の値、負の値、ゼロ、文字列に対応します。1 つならすべての数値が同じ規則、2 つなら負の値が 2 番目、3 つならゼロが別扱い、4 つなら文字列のセルも書式の対象になります。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
formats = [
"0.00",
"0.00;[Red]-0.00",
'0.00;[Red]-0.00;"—"',
'0.00;[Red]-0.00;"—";"テキスト"',
]
values = (1234.5678, -1234.5678, 0)
for row, fmt in enumerate(formats, start=1):
for col, value in enumerate(values, start=2):
cell = sheet.Range[row, col]
cell.NumberValue = value
cell.NumberFormat = fmt
workbook.SaveToFile("sections.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
同じ 3 つの値でも、区切りを増やすにつれて負の値とゼロの見え方が分かれていきます。2 区切りでは負号を 2 番目の区切りが持つ - が補い、赤で表示します。3 区切りではゼロが短いダッシュに変わります。4 番目の区切りを足すと文字列のセルも書式の対象になり、文字列は 4 番目の区切りで出力されます。3 区切りまでのときは、文字列のセルは入力どおりに表示されます。数値の正負で表示を振り分けられるのはこの区切りの仕組みだけで、帳票で「ゼロは横線」といった取り決めは 3 番目の区切りに置きます。
3 通貨：記号、括弧、千単位への丸め
通貨の書き方は 3 つの要素で決まります。記号をどこに置くか、負の値を何でくくるか、大きな数をどの位で丸めるかです。記号はリテラルとしてコードに直接書くか、[$記号-ロケール] の形でロケールを宣言します。負の区切りを括弧でくくれば会計用の書式になり、整数部のカンマが 1 つ増えるごとに値は 1000 分の 1 になります。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
cases = [
('"¥"#,##0.00;("¥"#,##0.00)', 1234.5678),
("#,##0.00_);[Red](#,##0.00)", -1234.5678),
("[$¥-411]#,##0.00", 1234.5678),
('#,##0,"千"', 1234567.891),
('#,##0.00,,"百万"', 1234567.891),
]
for row, (fmt, value) in enumerate(cases, start=1):
cell = sheet.Range[row, 1]
cell.NumberValue = value
cell.NumberFormat = fmt
sheet.AutoFitColumn(1)
workbook.SaveToFile("currency.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
"¥" は引用符付きのリテラルで、引用符があることで記号が書式のプレースホルダーとして扱われません。2 番目の区切りの括弧は負の値を (1,234.57) にし、_) が ) と同じ幅の空白を数字の右側に確保するので、正負の行で小数点の位置が揃います。[$¥-411] はロケールコードで記号の描画を決め、411 が日本語ロケールです。整数部の末尾にカンマを 1 つ足すごとに 1000 で割られ、#,##0,"千" は 1234567.891 を 1,235千 に、#,##0.00,,"百万" はカンマ 2 つで 1.23百万 にします。丸めは表示だけに働き、セルには元の数値が残るため、集計式が読むのも元の値です。
4 日付と時刻：シリアル値に書式コードを掛ける
Excel の日付は内部ではシリアル値で、1900-01-01 を 1 として以降 1 日ごとに 1 増えます。2026-11-02 は 46328、時刻部分は 1 日を 1 とする小数で表し、15:30 は 0.6458333 です。書式コードはシリアル値を yyyy、mm、dd といった要素に描き分ける役割を持ち、時刻の累計か時計表示かの違いは角括弧で決まります。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
cases = [
("yyyy-mm-dd", 46328),
('yyyy"年"m"月"d"日"', 46328),
('[$-411]yyyy"年"m"月"d"日" aaaa', 46328),
("h:mm AM/PM", 0.6458333),
("[h]:mm:ss", 1.5),
("[m]:ss", 0.0625),
("yyyy-mm-dd hh:mm", 46328.6458333),
]
for row, (fmt, value) in enumerate(cases, start=1):
cell = sheet.Range[row, 1]
cell.NumberValue = value
cell.NumberFormat = fmt
sheet.AutoFitColumn(1)
workbook.SaveToFile("datetime.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
yyyy"年"m"月"d"日" の日本語は引用符でリテラルにします。m は日付の部分では月、h の直後では分を表します。曜日は aaaa で、先頭に [$-411] のロケール指定を付けると「月曜日」と描画されます。角括弧は累計と循環の分かれ目です。[h]:mm:ss は 1.5 を 36:00:00 と表示し、時間が 24 を超えても加算を続けます。角括弧を外して h:mm:ss にすると同じ値が 12:00:00 になり、1.5 日を 24 時間で割った余りの時計表示になります。[m]:ss は 0.0625 日（90 分）を 90:00 と描画し、稼働時間や通話時間のように時間をまたぐ分数の表示に使えます。
5 条件付きセクション：比較結果で書式を選ぶ
区切りの先頭に角括弧の比較式を置くと、その区切りは条件を満たす値にだけ効きます。式は [>=1000]、[<0] のように角括弧の中に書き、条件付きの区切りは記述順に照合され、最初に一致した区切りが表示テキスト全体を担います。色名も同じく角括弧に入れ、[Red]、[Blue] のほか [Color1] から [Color56] までのインデックスも使えます。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
cases = [
("[>=1000]#,##0;[Red]0.00", 1234.5),
("[>=1000]#,##0;[Red]0.00", 12.345),
("[<0][Red]-0.00;[Blue]0.00", -5.5),
("[<0][Red]-0.00;[Blue]0.00", 5.5),
("[Color10]0.00;[Color3]-0.00", -3.25),
]
for row, (fmt, value) in enumerate(cases, start=1):
cell = sheet.Range[row, 1]
cell.NumberValue = value
cell.NumberFormat = fmt
sheet.AutoFitColumn(1)
workbook.SaveToFile("conditional.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
1 番目のコードでは、1234.5 が [>=1000] に一致して 1 番目の区切りを通り桁区切りの整数で表示され、12.345 は条件を満たさず 2 番目の区切りを通って小数第 2 位まで表示されます。条件付きの区切りは表示テキスト全体を引き受けるので、負号もその区切りのコードに書きます。[<0][Red]-0.00 の 2 番目を 0.00 にすると、負の値の符号は補われません。[Color3] はパレットのインデックス 3 の赤で [Red] と同じ色になり、[Color10] に変えると緑になります。コードで条件付き書式を組む場合、この区切りの書き方ならセルごとに色を設定するより手数が少なく、規則がファイルと一緒に残るため再生成しても失われません。
6 ロケール指定：和暦とローカライズされた名称
[$-ロケール] を書式コードの先頭に置くと、数値と名称のローカライズ方法が決まります。$-411 が日本語、$-804 が簡体字中国語です。和暦の元号は g で表し、ggge"年"m"月"d"日" のように書くと「令和8年11月2日」と描画されます。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
cases = [
('[$-411]yyyy"年"m"月"d"日"', 46328),
('[$-411]ggge"年"m"月"d"日"', 46328),
('[$-411]m"月"d"日" aaaa', 46328),
('[$-411]aaaa', 46328),
]
for row, (fmt, value) in enumerate(cases, start=1):
cell = sheet.Range[row, 1]
cell.NumberValue = value
cell.NumberFormat = fmt
sheet.AutoFitColumn(1)
workbook.SaveToFile("localized.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
1 番目のコードが西暦、2 番目が和暦です。和暦の出力は 2 種類の記号の組み合わせで決まり、g が元号名、e が元号の年数を表します。g を単独で置くと元号名だけが出て年数の位置に何も入らないため、年を出すには ggge のように g と e を並べます。gee のように g を 1 つにして e を続けても、元号名と年数の両方が出ます。ロケールコードは名称にも作用し、[$-411]aaaa は「月曜日」を出力します。[$-804]aaaa に変えれば「星期一」になります。1 つのブックで複数言語の日付を見せたいときも、書式コードがセルごとについてくるので、ドキュメントのロケール設定はそのままで済みます。
7 文字列と独自の接尾辞：リテラル、桁マスク、分数
書式コードで引用符に包んだ文字はそのまま出力され、数値の計算から切り離されています。@ はセルに入っている文字列そのものを表し、? は幅が可変のプレースホルダーで桁を揃えるのに使います。この 3 つを組み合わせると、データを変えずに単位を付けたり、桁で区切ったり、最も近い分数として表示したりできます。
from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]
cases = [
("@", "A-1024", True),
('0.0"kg"', 2.25, False),
('0.0" 円"', 2.25, False),
("000-0000", 1234567, False),
("# ?/?", 0.75, False),
("# ??/??", 0.3333, False),
]
for row, (fmt, value, is_text) in enumerate(cases, start=1):
cell = sheet.Range[row, 1]
if is_text:
cell.Text = value
else:
cell.NumberValue = value
cell.NumberFormat = fmt
sheet.AutoFitColumn(1)
workbook.SaveToFile("text.xlsx", ExcelVersion.Version2016)
workbook.Dispose()
0.0"kg" は単位を数値の後ろに付けて 2.3kg にします。引用符の中の空白も残るので、0.0" 円" は 2.3 円 を出力します。000-0000 は固定個数の 0 とハイフンで 7 桁の数字を 123-4567 に切り分けます。管理番号、電話番号、識別番号はこの考え方で扱え、値は数値のまま、見た目だけが区切られた文字列になります。分数の書式では ? の個数が分母の桁数を決め、# ?/? は 0.75 を 3/4 に、# ??/?? は 0.3333 に分母 2 桁の枠を与えて 1/3 にします。@ は文字列のセル用で、入力内容をそのまま出力するため、数値行と文字列行が混在する列に同じ書式を掛けるときに便利です。
API リファレンス
主要クラス：
| クラス | 説明 |
|---|---|
Workbook |
ブックのオブジェクト。作成、保存、ワークシートのコレクションを担う |
Worksheet |
ワークシート。Range の入口と列幅、描画メソッドを提供する |
CellRange |
セルまたは範囲。値、文字列、書式を保持する |
CellStyle |
セルのスタイル。NumberFormat がフォントや塗りと同じ層にある |
よく使うメソッドとプロパティ：
| 名前 | 説明 |
|---|---|
CellRange.NumberFormat |
書式コード文字列の取得と設定 |
CellRange.NumberValue |
数値の書き込み。書式はこの値に対して描画される |
CellRange.Text |
文字列の書き込み。4 区切りの書式では 4 番目の区切りがこれに効く |
CellRange.DisplayedText |
現在の書式で描画したテキストを返す |
CellRange.Style |
スタイルオブジェクトを取得し、NumberFormat、フォント、塗りを設定できる |
Worksheet.Range[row, col] |
行と列の番号でセルを取得する。"A1" 形式のアドレスも可 |
Worksheet.AutoFitColumn(col) |
内容に合わせて列幅を調整する |
Worksheet.SetColumnWidth(col, width) |
列幅を指定する |
Worksheet.ToImage(r1, c1, r2, c2) |
範囲を画像として出力する |
Workbook.SaveToFile(path, version) |
ブックを保存する |
書式コードのプレースホルダーとスイッチ：
| 書き方 | 役割 |
|---|---|
0 |
必ず表示する桁。不足分はゼロで埋める |
# |
省略できる桁。先頭のゼロは表示しない |
? |
幅が可変のプレースホルダー。桁揃えに使う |
, |
整数部では桁区切り、末尾に付けるごとに値を 1000 分の 1 にする |
% |
値を 100 倍してパーセント記号を付ける |
E+00 |
指数表記。指数部の桁数は 0 の個数で決まる |
; |
区切りの分離。正、負、ゼロ、文字列の順に対応する |
[>=1000] |
条件付きの区切り。比較結果で照合する |
[Red] [Color3]
|
色名とパレットのインデックス |
[$-411] |
ロケールコード。記号と名称のローカライズを決める |
g ggge
|
元号。文字数で表記が変わる |
[h] [m] [s]
|
時刻の累計。桁上がりを超えて加算を続ける |
@ |
文字列のプレースホルダー。セルの内容をそのまま出力する |
"文字" |
引用符の中はリテラルとしてそのまま出力する |
_) |
指定した文字と同じ幅の空白を確保する |
まとめ
7 種類の書き方で書式コードの文法をひととおり覆いました。プレースホルダーが小数位と桁区切りを決め、セミコロンが正・負・ゼロ・文字列の 4 つの場合を切り出し、角括弧が条件・色・ロケールの宣言を担い、引用符と @ がリテラルと文字列を扱います。組み立ての順序は決まっていて、ロケールが先頭、条件と色がその直後、数値のプレースホルダーとリテラルが本体を作り、セミコロンが本体を区切りに複製します。
複数の要素を重ねるときは、区切りの分割が条件より先に効きます。まずセミコロンで区切り、区切りの中で条件と色を照合します。日付と時刻は同じプレースホルダーの体系で、角括弧が累計か循環かを決めます。書式は表示にだけ作用し、NumberValue が保持するのは元の数値なので、PDF への書き出し、グラフの生成、計算のいずれも元の値を読みます。
DisplayedText があれば書式の効果をプログラムから確認できます。値と書式を書き込んだあとに DisplayedText を読み、期待する文字列と比べる手順は、帳票を一括生成するときの自己点検として、ファイルを 1 枚ずつ開くより確実です。
Free 版は 1 ブック 5 シート、1 シート 200 行までで、それを超える場合は商用版が必要です。シートの画像化は 1 回の読み込みにつき先頭 3 枚まで変換でき、まとめて図を出すときはシートごとにファイルを分けるか、変換前にほかのシートを削除すると 1 枚ずつ書き出せます。