セル結合

複数のセルを一つに結合する機能です。結合されたセルでは、左上セルの値とスタイルのみが表示され、範囲内の他のセルは非表示になります。

セルを結合する

RangeHandle の merge() を呼び出し、左上セルに値とスタイルを設定します。

// A1:E1 を一つのセルに結合
worksheet.range('A1:E1').merge()
worksheet.cell('A1').setValue('Q3 売上レポート').setStyle({
  bold: true,
  fontSize: 14,
  textAlign: 'center',
  backgroundColor: '#0f172a',
  color: '#f8fafc',
})

行高は自動調整されないため、必要に応じて手動で設定します。

worksheet.row(0).height = 40

結合の解除

unmerge() で範囲を個別のセルに戻します。左上セルの値は保持され、非表示だったセルは空になります。

worksheet.range('A1:E1').unmerge()

チェーンメソッド

merge() はチェーンメソッドとして使えます。

worksheet.range('A1:E1')
  .merge()
  .setStyle({ bold: true, fontSize: 16, textAlign: 'center' })
  .setBackgroundColor('#1e40af')

よくあるパターン

タイトル行を全列に結合

worksheet.range('A1:F1').merge()
worksheet.cell('A1')
  .setValue('年間予算概要')
  .setStyle({ bold: true, fontSize: 13, textAlign: 'center', backgroundColor: '#0f172a', color: '#f8fafc' })
worksheet.row(0).height = 36

グループ化された列ヘッダー

// "上半期" を Q1 と Q2 にまたがって結合
worksheet.range('C1:D1').merge()
worksheet.cell('C1').setValue('上半期').setStyle({ bold: true, textAlign: 'center', backgroundColor: '#1e3a5f', color: '#e2e8f0' })

// "下半期" を Q3 と Q4 にまたがって結合
worksheet.range('E1:F1').merge()
worksheet.cell('E1').setValue('下半期').setStyle({ bold: true, textAlign: 'center', backgroundColor: '#1e3a5f', color: '#e2e8f0' })

複数行にまたがるサイドラベル

worksheet.range('A2:A5').merge()
worksheet.cell('A2').setValue('北部').setStyle({
  bold: true,
  textAlign: 'center',
  verticalAlign: 'middle',
  backgroundColor: '#f1f5f9',
})

結合状態の確認

CellHandle の isMerged と mergeRange を使って結合状態を確認できます。

const cell = worksheet.cell('A1')

if (cell.isMerged) {
  const range = cell.mergeRange
  // range: { topRow, leftColumn, bottomRow, rightColumn }
  console.log(`行 ${range.topRow} から ${range.bottomRow} まで結合`)
}

アンカーセル（左上）と結合範囲内のすべてのセルが同じ mergeRange を返します。

低レベル API

// 結合
ws.mergeCells(0, 0, 0, 4) // topRow, leftColumn, bottomRow, rightColumn

// 解除
ws.unmergeCells(0, 0, 0, 4)

// 全結合を解除
ws.clearMergedRanges()

結合範囲の一括設定

setMergedRanges() で複数の結合を一度に設定します。既存の結合はすべて置き換えられます。

ws.setMergedRanges([
  { topRow: 0, bottomRow: 0, leftColumn: 0, rightColumn: 4 },
  { topRow: 5, bottomRow: 5, leftColumn: 0, rightColumn: 2 },
])

注意事項

• 左上セルのみが有効です。 結合範囲内の他のセルに値やスタイルを設定しても、結合を解除するまで表示に反映されません。
• ボーダーは通常通り動作します。 range.border() は結合セルの外側の辺に適用されます。
• xlsx との往復。 結合セルは xlsx ファイルの読み込み時に保持されます。
• 重複する結合はサポートされていません。 既存の結合と重なる範囲を結合すると予期しない動作になります。先に結合を解除してください。