セルツールチップ

セルツールチップを使うと、個々のセルや範囲にコンテキストメッセージを関連付けることができます。入力ヒント、バリデーションフィードバック、情報メモの表示に活用できます。

Note: セルツールチップは Pro 版で利用可能です。

ツールチップの設定

setCellTooltip() でセルにツールチップを登録します。ツールチップは保存されますが、明示的に表示するまでは表示されません。

worksheet.setCellTooltip(
  { row: 1, col: 0 },
  { text: '顧客名を入力してください', backgroundColor: '#1e40af', color: '#ffffff' }
)

TooltipRange

CellTooltipConfig

表示と非表示

// 特定のセルにツールチップを表示
worksheet.showCellTooltip({ row: 1, col: 0 })

// 現在表示中のツールチップを非表示
worksheet.hideCellTooltip()

一度に表示できるツールチップは 1 つだけです。showCellTooltip() を呼ぶと、前のツールチップは自動的に非表示になります。

ツールチップの更新

同じセルに対して setCellTooltip() を再度呼び出すと、テキストや色が更新されます。ツールチップが現在表示中の場合、即座に更新されます。

// 最初はヒントを表示
worksheet.setCellTooltip({ row: 1, col: 1 }, {
  text: '有効なメールアドレスを入力してください',
  backgroundColor: '#1e40af',
})

// バリデーション失敗後、エラーに切り替え
worksheet.setCellTooltip({ row: 1, col: 1 }, {
  text: 'メールアドレスの形式が無効です',
  backgroundColor: '#b91c1c',
})

ツールチップの削除

// 特定のツールチップを削除（表示中の場合は先に非表示）
worksheet.clearCellTooltip({ row: 1, col: 0 })

実践例 — フォームバリデーション

ツールチップの一般的な活用パターンは入力バリデーションです。必須フィールドにヒントツールチップを登録し、バリデーション後にエラーツールチップに切り替えます。

const FIELDS = [
  { row: 1, label: '氏名',       hint: '必須 — フルネームを入力してください' },
  { row: 2, label: 'メール',     hint: '必須 — 有効なメールアドレスを入力' },
  { row: 3, label: '電話番号',   hint: '必須 — 電話番号を入力してください' },
]

// ステップ 1: 未入力の必須フィールドにヒントを登録（青）
FIELDS.forEach(field => {
  worksheet.setCellTooltip({ row: field.row, col: 1 }, {
    text: field.hint,
    backgroundColor: '#1e40af',
    color: '#ffffff',
  })
})

// 最初のヒントを表示
worksheet.showCellTooltip({ row: FIELDS[0].row, col: 1 })

ユーザーが値を入力して送信した後、バリデーションを行いエラーツールチップに切り替えます:

function validate() {
  const errors = []

  // 空のフィールドをチェック
  FIELDS.forEach(field => {
    const value = worksheet.cell(field.row, 1).value
    if (!value || String(value).trim() === '') {
      errors.push({ row: field.row, message: `${field.label}は必須です` })
    }
  })

  // メール形式をチェック
  const email = worksheet.cell(2, 1).value
  if (email && !String(email).includes('@')) {
    errors.push({ row: 2, message: 'メールアドレスの形式が無効です' })
  }

  // ツールチップをエラーに更新（赤）
  errors.forEach(err => {
    worksheet.setCellTooltip({ row: err.row, col: 1 }, {
      text: err.message,
      backgroundColor: '#b91c1c',
      color: '#ffffff',
    })
  })

  // 最初のエラーを表示
  if (errors.length > 0) {
    worksheet.showCellTooltip({ row: errors[0].row, col: 1 })
  }
}

複数セルにまたがるツールチップ

rowSpan と colSpan を使ってツールチップを複数セルにまたがらせることができます:

worksheet.setCellTooltip(
  { row: 0, col: 0, rowSpan: 1, colSpan: 3 },
  { text: 'このセクションは読み取り専用です', backgroundColor: '#6b7280' }
)
worksheet.showCellTooltip({ row: 0, col: 0, rowSpan: 1, colSpan: 3 })