Instruction file imported from otayoshino/panel-for-word (.github/instructions/word-panel-mock.instructions.md). Copyright stays with the author.

Word パネル モック 実装ガイド

プロジェクト概要

VBA 製 Word カスタム作業ウィンドウを Office.js Add-in（React + TypeScript + Vite）として作り替えるプロジェクト。

機能対応状況（VBA_vs_OfficeJS_比較表.xlsx より）

凡例: ○ 対応可 / △ 部分対応 / × 非対応（廃止）

〈基本設定〉ページ設定

〈文字組み〉インデント

〈文字組み〉行間

〈文字組み〉タブとリーダー

〈文字組み〉表

〈文字組み〉ドキュメント使用フォント一覧・置換

〈文字組み〉ルビ機能

〈枠〉画像・オブジェクト挿入

〈枠〉テキスト・画像枠作成

〈枠〉重ね順・枠揃え

〈数式〉数式入力

〈定型文〉定型文入力

〈ウィンドウ下部〉メニュー

実装対象サマリー（○ 対応可 および △ 部分対応）

○ 対応可（完全実装）

△ 部分対応（制約付き実装）

非対応機能（廃止）

以下は Office.js Word API で実現不可のため廃止:

• ルビ（モノルビ）: phonetic guide API なし
• Wordダイアログ直接呼び出し: ページ設定・段落・タブ・表プロパティ・罫線等のダイアログ全般
• 数式リボン操作: 数式エディタパレット・記号パレット全般、OfficeMath挿入
• 図形挿入・操作: 図形・画像枠の作成、重ね順、枠揃え（Shape API Word非対応）
• ズーム・ミニツールバー: Word UI 制御系 API 非対応
• Wordアプリ設定: オプション・オートコレクトダイアログ

コーディング規約

Office.js の使い方

// ✅ 正しいパターン: Word.run + context.sync
const runWord = async (action: (context: Word.RequestContext) => Promise<void>) => {
  try {
    await Word.run(async (context) => {
      await action(context)
    })
  } catch (e) {
    setStatus({ type: 'error', message: `エラー: ${e instanceof Error ? e.message : String(e)}` })
  }
}

// ✅ プロパティ読み込みパターン
const getSelection = () =>
  runWord(async (context) => {
    const range = context.document.getSelection()
    range.load('text')         // 読み取るプロパティを宣言
    await context.sync()       // サーバーと同期
    console.log(range.text)    // sync 後にプロパティにアクセス
  })

// ✅ 書き込みパターン（load 不要）
const applyBold = () =>
  runWord(async (context) => {
    const range = context.document.getSelection()
    range.font.bold = true
    await context.sync()
  })

ステータス管理

type Status = { type: 'success' | 'error' | 'warning'; message: string }

// 成功・エラー・警告を統一的に管理
const [status, setStatus] = useState<Status | null>(null)

UIコンポーネント

• 必須: @fluentui/react-components を使用する（HTML ネイティブ要素を直接使わない）
• スタイル: makeStyles + tokens を使用（インラインスタイル禁止）
• アイコン: @fluentui/react-icons から選択

コンポーネント分割方針

VBA アプリのタブ構成（基本設定 / 文字組 / 枠 / 数式 / 定型文）に対応させる。

src/
  App.tsx                        # ルートコンポーネント（TabList + レイアウト）
  components/
    tabs/
      BasicSettingsTab.tsx       # 基本設定タブ（ページ設定・用紙・余白・文字サイズ等）
      CharCompositionTab.tsx     # 文字組タブ（インデント・行間・表・フォント置換）
      FrameTab.tsx               # 枠タブ（画像挿入・ContentControl枠作成）
      FormulaTab.tsx             # 数式タブ（# $ % & @ 入力のみ実装）
      TemplateTextTab.tsx        # 定型文タブ（定型文・記号管理）
    shared/
      StatusBar.tsx              # ステータス表示（MessageBar）
      SectionHeader.tsx          # セクションヘッダー（Divider + Text）
  hooks/
    useWordRun.ts                # Word.run ラッパーフック

useWordRun フック

// hooks/useWordRun.ts
import { useState } from 'react'

type Status = { type: 'success' | 'error'; message: string }

export function useWordRun() {
  const [status, setStatus] = useState<Status | null>(null)

  const runWord = async (action: (context: Word.RequestContext) => Promise<void>) => {
    try {
      await Word.run(async (context) => {
        await action(context)
      })
    } catch (e) {
      setStatus({
        type: 'error',
        message: `エラー: ${e instanceof Error ? e.message : String(e)}`,
      })
    }
  }

  return { runWord, status, setStatus }
}

UIレイアウト方針

• パネルは縦スクロール可能な単一カラム
• 最上部: タブ（基本設定 / 文字組 / 枠 / 数式 / 定型文）
• タブ内の各機能セクションは <Divider> で区切る
• セクションヘッダーは 【セクション名】 形式の <Text weight="semibold">（VBIツールボックスに準拠）
• ボタン行は flexWrap: 'wrap' でレスポンシブに
• パネル幅: 最小 280px、パディング tokens.spacingHorizontalM
• 最下部: ステータスバー（MessageBar 固定表示）

タブ別セクション構成

基本設定タブ

1. 【ページ設定】— ドキュメント設定値取得、用紙サイズ、横組方向
2. 【文字サイズ・フォント】— 基本文字サイズ（SpinButton）
3. 【段組み】— 段数（SpinButton）
4. 【余白設定（ミリ）】— 上・下・左・右（Input + 実行ボタン）

文字組タブ

1. 【インデント】— 左・右・最初の行（SpinButton）+ 全て0
2. 【行間】— 倍数・固定値（SpinButton + RadioGroup）
3. 【表】— 表の挿入ボタン
4. 【ドキュメント使用フォント一覧・置換】— フォントリスト取得 + 置換 Dropdown + 実行

枠タブ

1. 【画像挿入】— ファイル選択 + 挿入ボタン
2. 【テキスト枠作成（ContentControl）】— サイズ指定 + 作成ボタン

数式タブ

1. 【記号入力】— # $ % & @ ボタン（range.insertText で挿入）
2. ※数式リボン系は非対応のため廃止（旨をUI上に表示）

定型文タブ

1. 【定型文入力】— 定型文1〜5（Input + ラジオ + 文章からコピー登録 + 実行）
2. 【記号入力】— 記号表示・変更・実行・リセット

Fluent UI コンポーネント対応表

TypeScript 規約

• strict: true 必須
• any 型禁止（unknown → 型ガードで絞る）
• Office.js 型は @types/office-js から参照（グローバル Word 名前空間）
• コンポーネント Props は interface で定義

禁止事項

• document.getElementById など DOM 直接操作
• console.log を製品コードに残す（デバッグ後削除）
• インラインスタイル（style={{ ... }}）
• Office API 呼び出しを Word.run 外で行う