# 画面設計書 24-InsertMediaSettings画面

## 概要

本ドキュメントは、Wikipedia iOSアプリにおけるメディア挿入設定画面（InsertMediaSettingsViewController）の設計仕様を記載したものである。

### 本画面の処理概要

InsertMediaSettings画面は、ユーザーがWikipedia記事に挿入する画像のキャプション、代替テキスト、および詳細設定（位置、サイズ、タイプ）を入力・設定するための画面である。InsertMedia画面で画像を選択した後に表示され、設定完了後に画像挿入用のWikitextを生成する。

**業務上の目的・背景**：Wikipedia記事の画像には、適切なキャプションと代替テキスト（アクセシビリティ）を設定することが推奨されている。本画面は、これらのメタデータを入力するためのUIを提供し、最終的に正しいWikitext形式で画像を挿入できるようにする。また、Image Recommendations機能からも利用され、画像提案の詳細設定にも対応している。

**画面へのアクセス方法**：
- InsertMedia画面でNextボタンをタップ
- Image Recommendations機能からの直接表示

**主要な操作・処理内容**：
1. キャプションテキストを入力する
2. 代替テキスト（alt text）を入力する
3. 「Advanced settings」から詳細設定画面に遷移する
4. 「Insert」または「Next」ボタンで挿入を確定する
5. 画像タイトルをタップしてファイルページを開く

**画面遷移**：
- 遷移元：InsertMedia画面 / Image Recommendations機能
- 遷移先：InsertMediaAdvancedSettings画面 / Wikitext生成後にdelegateへ通知

**権限による表示制御**：特になし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | メディア挿入 | 補助機能 | キャプション、代替テキストの設定 |

## 画面種別

設定 / 入力画面

## URL/ルーティング

iOSネイティブアプリのため、URLベースのルーティングは存在しない。

## 入出力項目

### 入力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|----------|------|------|
| image | 入力 | UIImage | 必須 | 挿入する画像 |
| searchResult | 入力 | InsertMediaSearchResult | 必須 | 選択された画像の検索結果情報 |
| fromImageRecommendations | 入力 | Bool | 必須 | Image Recommendations機能からの遷移かどうか |
| delegate | 入力 | InsertMediaSettingsViewControllerDelegate | 必須 | 設定完了時の通知先 |
| imageRecLoggingDelegate | 入力 | InsertMediaSettingsViewControllerLoggingDelegate? | 任意 | ロギング用delegate |
| theme | 入力 | Theme | 必須 | アプリのテーマ設定 |
| siteURL | 入力 | URL | 必須 | WikipediaサイトのURL |

### 出力項目（delegate経由）

| 項目名 | 種別 | データ型 | 説明 |
|--------|------|----------|------|
| imageWikitext | 出力 | String | 生成された画像挿入用Wikitext |
| caption | 出力 | String? | 入力されたキャプション |
| altText | 出力 | String? | 入力された代替テキスト |
| localizedFileTitle | 出力 | String | ローカライズされたファイルタイトル |

## 表示項目

### ナビゲーションバー

| 項目名 | 表示内容 | 条件 | 備考 |
|--------|----------|------|------|
| タイトル | "Media settings" | fromImageRecommendations = false | 通常の画像挿入 |
| タイトル | "Add image details" | fromImageRecommendations = true | Image Recommendations |
| 右ボタン | "Insert" | fromImageRecommendations = false | 挿入確定 |
| 右ボタン | "Next" | fromImageRecommendations = true | 次のステップへ |

### ヘッダー（画像情報）

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| 画像プレビュー | 選択された画像 | InsertMediaSettingsImageView |
| 画像タイトル | displayTitle | タップでファイルページを開く |
| 画像説明 | imageDescription | searchResultまたはimageInfoから取得 |

### 入力フィールド

| 項目名 | ヘッダー | プレースホルダー | フッター | Learn More URL |
|--------|----------|------------------|----------|----------------|
| キャプション | "Caption" | "How does this image relate to the article?" | "Label that shows next to the item for all readers" | MediaWiki iOS Suggested edits#Image_captions |
| 代替テキスト | "Alternative text" | "Describe this image" | "Text description for readers who cannot see the image" | MediaWiki iOS Suggested edits#Tips_for_creating_alt-text |

### フッター（詳細設定ボタン）

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| ボタン | "Advanced settings" | InsertMediaAdvancedSettingsViewControllerに遷移 |

## イベント仕様

### 1-キャプション入力

キャプションテキストフィールドに入力する。

**処理フロー**：
1. UITextViewDelegateのtextViewDidChangeが呼び出される
2. テキストビューの高さを自動調整
3. fromImageRecommendationsの場合、キャプションが空かどうかでNextボタンの色を変更

### 2-代替テキスト入力

代替テキストフィールドに入力する。

**処理フロー**：
1. UITextViewDelegateのtextViewDidChangeが呼び出される
2. テキストビューの高さを自動調整

### 3-Advanced Settingsボタンタップ

詳細設定画面に遷移する。

**処理フロー**：
1. buttonView.buttonActionが呼び出される
2. imageRecLoggingDelegate?.logInsertMediaSettingsViewControllerDidTapAdvancedSettingsを呼び出し
3. InsertMediaAdvancedSettingsViewControllerにテーマを適用
4. navigationControllerでpush遷移

### 4-Insert/Nextボタンタップ

画像挿入を確定する。

**処理フロー**：
1. tappedProgress(_:)メソッドが呼び出される
2. imageInsertInfo(searchResult:settings:siteURL:)で情報を生成
3. Wikitextを生成（位置、タイプ、サイズ、キャプション、代替テキストを含む）
4. delegate?.insertMediaSettingsViewControllerDidTapProgressを呼び出し

### 5-画像タイトルタップ

ファイルページをSafariで開く。

**処理フロー**：
1. imageView.titleActionが呼び出される
2. imageRecLoggingDelegate?.logInsertMediaSettingsViewControllerDidTapFileNameを呼び出し
3. navigate(to:useSafari:false)でファイルページを開く

### 6-Learn Moreリンクタップ

ヘルプページを開く。

**処理フロー**：
1. cell.learnMoreActionが呼び出される
2. ロギングdelegateに通知（キャプション/代替テキストで異なる）
3. navigate(to:useSafari:false)でヘルプページを開く

## データベース更新仕様

### 操作別データベース影響一覧

この画面ではローカルデータベースへの直接的な更新は行われない。Wikitext生成はメモリ上で行われる。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| なし | - | - | - |

## Wikitext生成仕様

### 生成形式

```wikitext
[[{localizedFileTitle}{imageType}{imageSize} | {imagePosition} | {altText} | {caption}]]
```

### 各パラメータの生成ルール

| パラメータ | 生成ルール |
|-----------|-----------|
| localizedFileTitle | MagicWordUtils.getMagicWordForKeyで言語別に取得 |
| imageType | thumb/frameless/frame/basic（basicは空文字） |
| imageSize | default: 220x124px / custom: {width}x{height}px |
| imagePosition | right/left/center/none（言語別にローカライズ） |
| altText | alt={value}形式（言語別にローカライズ） |
| caption | そのまま使用 |

## メッセージ仕様

| ID | 種別 | メッセージ内容 | 表示条件 |
|----|------|----------------|----------|
| MSG-01 | エラー | "No internet connection" | オフライン時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| オフライン | WMFAlertManagerでエラーメッセージを表示 |
| オンライン復帰 | アラートを非表示 |

## 備考

- ReachabilityNotifierでネットワーク状態を監視
- キーボード表示時にtableViewのcontentInsetを自動調整
- MagicWordUtilsを使用して画像パラメータをローカライズ
- VoiceOver対応（UIAccessibility.post）

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

設定データの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | InsertMediaSettingsViewController.swift | `Wikipedia/Code/InsertMediaSettingsViewController.swift` | 行37-145: Settings構造体とAdvanced設定 |

**読解のコツ**: Settings構造体の入れ子構造（Advanced内のImagePosition, ImageType, ImageSize）を理解することが重要。

#### Step 2: エントリーポイントを理解する

ViewControllerの初期化とUI構成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | InsertMediaSettingsViewController.swift | `Wikipedia/Code/InsertMediaSettingsViewController.swift` | 行243-256: init, 行258-298: viewDidLoad |

**主要処理フロー**:
1. **行243-252**: init - 必要なパラメータを受け取りプロパティに設定
2. **行258-271**: viewDidLoad - tableViewの設定、セル登録、キーボード通知の登録
3. **行313-317**: viewWillAppear - ナビゲーションバーの設定
4. **行319-330**: viewDidAppear - ReachabilityNotifier開始、アクセシビリティ通知

#### Step 3: Wikitext生成ロジックを理解する

imageInsertInfoメソッドの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | InsertMediaSettingsViewController.swift | `Wikipedia/Code/InsertMediaSettingsViewController.swift` | 行389-433: imageInsertInfo静的メソッド |

**主要処理フロー**:
- **行391**: localizedFileTitleの生成
- **行401-406**: imageTypeName, imagePositionName, altTextFormatの取得
- **行405-406**: imageSizeとimageTypeNameの整形
- **行408-429**: キャプションと代替テキストの組み合わせに応じたWikitext生成

#### Step 4: ローカライズ処理を理解する

MagicWordUtilsを使用したローカライズ処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | InsertMediaSettingsViewController.swift | `Wikipedia/Code/InsertMediaSettingsViewController.swift` | 行435-509: ローカライズ関連の静的メソッド |

**主要処理フロー**:
- **行435-448**: localizedFileTitle - File:プレフィックスのローカライズ
- **行450-472**: localizedImageTypeName - 画像タイプのローカライズ
- **行474-496**: localizedImagePositionName - 画像位置のローカライズ
- **行498-509**: localizedAltTextFormat - alt=形式のローカライズ

### プログラム呼び出し階層図

```
InsertMediaSettingsViewController
    │
    ├─ UITableView
    │      ├─ Header: InsertMediaSettingsImageView
    │      │      └─ titleAction → navigate(to:)
    │      │
    │      ├─ Cells: InsertMediaSettingsTextTableViewCell x 2
    │      │      ├─ Caption入力
    │      │      └─ AltText入力
    │      │
    │      └─ Footer: InsertMediaSettingsButtonView
    │             └─ buttonAction → InsertMediaAdvancedSettingsVC
    │
    ├─ InsertMediaAdvancedSettingsViewController (遷移先)
    │      ├─ ImagePositionSettingsVC
    │      ├─ ImageTypeSettingsVC
    │      └─ ImageSizeSettingsVC
    │
    ├─ ReachabilityNotifier
    │      └─ ネットワーク状態監視
    │
    └─ InsertMediaSettingsViewControllerDelegate
           └─ didTapProgress(imageWikitext:caption:altText:localizedFileTitle:)
```

### データフロー図

```
[入力]                     [処理]                              [出力]

image ─────────────────▶ imageView表示
searchResult ──────────▶ タイトル・説明表示

ユーザー入力
    │
    ├─▶ キャプション入力 ──────▶ settings.caption
    │
    └─▶ 代替テキスト入力 ─────▶ settings.alternativeText

advancedSettings ──────▶ settings.advanced
                              │
                              ├─▶ imagePosition
                              ├─▶ imageType
                              └─▶ imageSize

Insert/Nextタップ
    │
    ▼
imageInsertInfo()
    │
    ├─▶ localizedFileTitle()
    ├─▶ localizedImageTypeName()
    ├─▶ localizedImagePositionName()
    └─▶ localizedAltTextFormat()
           │
           ▼
    Wikitext生成 ──────────▶ delegate.didTapProgress()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| InsertMediaSettingsViewController.swift | `Wikipedia/Code/InsertMediaSettingsViewController.swift` | ソース | 本画面のコントローラ |
| InsertMediaSettingsImageView.swift | `Wikipedia/Code/InsertMediaSettingsImageView.swift` | ソース | ヘッダーの画像表示ビュー |
| InsertMediaSettingsButtonView.swift | `Wikipedia/Code/InsertMediaSettingsButtonView.swift` | ソース | フッターのボタンビュー |
| InsertMediaSettingsTextTableViewCell.swift | `Wikipedia/Code/InsertMediaSettingsTextTableViewCell.swift` | ソース | テキスト入力セル |
| InsertMediaAdvancedSettingsViewController.swift | `Wikipedia/Code/Advanced Settings/InsertMediaAdvancedSettingsViewController.swift` | ソース | 詳細設定画面 |
| MagicWordUtils.swift | `WMF Framework/MagicWordUtils.swift` | ソース | ローカライズユーティリティ |
| ReachabilityNotifier.swift | `Wikipedia/Code/ReachabilityNotifier.swift` | ソース | ネットワーク監視 |
| InsertMediaSearchResult.swift | `Wikipedia/Code/InsertMediaSearchResult.swift` | ソース | 検索結果データモデル |
