# 画面設計書 11-デフォルトページネーション

## 概要

本ドキュメントは、Laravelフレームワークにおけるデフォルトページネーションビューの設計仕様を定義する。

### 本画面の処理概要

デフォルトページネーションは、データベースから取得した大量のデータを複数のページに分割して表示するための標準的なナビゲーションコンポーネントである。このビューはCSSフレームワークに依存しない汎用的なHTML構造を提供し、独自スタイルの適用やBootstrap 3との互換性を維持する。

**業務上の目的・背景**：Webアプリケーションでは、検索結果や一覧データが数百件から数万件に及ぶことが多い。全データを一度に表示すると、ページ読み込み時間の増大やユーザビリティの低下を招く。ページネーションにより、適切な単位でデータを分割表示し、ユーザーが目的のデータに効率的にアクセスできるようにする。デフォルトビューは、特定のCSSフレームワークに依存せず、開発者が自由にスタイリングできる基盤を提供する。

**画面へのアクセス方法**：Bladeテンプレート内で`$paginator->links()`または`$paginator->render()`メソッドを呼び出すことで表示される。明示的にビュー名を指定しない場合は、設定されたデフォルトビュー（`pagination::default`）が使用される。Bootstrap 3スタイリングを使用する場合は`Paginator::useBootstrapThree()`をサービスプロバイダで呼び出す。

**主要な操作・処理内容**：
1. 前のページへのナビゲーション - 現在のページが1ページ目でない場合、前ページへのリンクを表示
2. ページ番号リンク - 各ページへの直接ジャンプリンクを表示
3. 省略記号（...）の表示 - ページ数が多い場合に中間ページを省略
4. 次のページへのナビゲーション - 次ページが存在する場合、次ページへのリンクを表示
5. 現在ページのハイライト - 現在閲覧中のページ番号を視覚的に強調

**画面遷移**：各ページ番号リンクをクリックすると、該当ページのURLにGETリクエストで遷移する。前へ/次へリンクもそれぞれ対応するページURLへ遷移する。

**権限による表示制御**：ページネーションコンポーネント自体には権限制御機能はない。アクセス権限は呼び出し元のコントローラーやミドルウェアで制御される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 50 | ページネーション | 主機能 | 標準ページネーションのリンク生成・表示 |
| 17 | URL生成 | 補助機能 | ページリンクURL生成処理 |

## 画面種別

コンポーネント（ページネーションナビゲーション）

## URL/ルーティング

このコンポーネント自体はルーティングを持たない。ページネーションリンクのURLは以下の形式で生成される：
- `{base_path}?page={page_number}`
- クエリパラメータが追加されている場合：`{base_path}?{query}&page={page_number}`
- フラグメントが設定されている場合：`{base_path}?page={page_number}#{fragment}`

## 入出力項目

| 項目名 | 型 | I/O | 説明 |
|--------|-----|-----|------|
| $paginator | LengthAwarePaginator | 入力 | ページネーション情報を含むPaginatorインスタンス |
| $elements | array | 入力 | ページリンク要素の配列（ページ番号とURL、または省略記号） |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 前へリンク | `<` 記号 | 前のページへのナビゲーションリンク |
| ページ番号 | 数字 | 各ページへの直接リンク |
| 省略記号 | `...` | 省略されたページ範囲を示す |
| 次へリンク | `>` 記号 | 次のページへのナビゲーションリンク |
| 現在ページ | 数字（active状態） | 現在表示中のページ番号 |

## イベント仕様

### 1-ページ番号クリック

ユーザーがページ番号リンクをクリックすると、該当ページのURLへGETリクエストで遷移する。
- URL形式：`{path}?page={clicked_page_number}`
- 現在のクエリパラメータは保持される（`appends()`で追加された場合）

### 2-前へリンククリック

現在のページ番号から1を引いたページへ遷移する。
- 条件：`$paginator->onFirstPage()`がfalseの場合のみリンクが有効
- URL：`$paginator->previousPageUrl()`で生成

### 3-次へリンククリック

現在のページ番号に1を加えたページへ遷移する。
- 条件：`$paginator->hasMorePages()`がtrueの場合のみリンクが有効
- URL：`$paginator->nextPageUrl()`で生成

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ページリンククリック | - | SELECT | ページネーションコンポーネント自体はDB操作を行わない。呼び出し元で新しいページのデータ取得が行われる |

### テーブル別更新項目詳細

ページネーションビューはデータベースの更新を行わない。データ取得はPaginatorインスタンス生成時に呼び出し元で実行される。

## メッセージ仕様

| 種別 | メッセージキー | 表示内容 | 表示条件 |
|------|---------------|----------|----------|
| ラベル | pagination.previous | Previous | 前へリンクのaria-label |
| ラベル | pagination.next | Next | 次へリンクのaria-label |

## 例外処理

| 状態 | 処理内容 |
|------|----------|
| ページ数が1以下 | `$paginator->hasPages()`がfalseを返し、ページネーション全体が非表示となる |
| 無効なページ番号 | Paginatorが自動的に有効なページ番号（1以上、最大ページ以下）に正規化する |
| 空のコレクション | ページネーションリンクは表示されない |

## 備考

- このビューはBootstrap 3のマークアップと互換性がある
- `Paginator::useBootstrapThree()`を呼び出すことで、デフォルトビューとして設定される
- アクセシビリティ対応として`aria-disabled`、`aria-current`、`aria-label`属性が設定される
- HTML特殊文字（`&lsaquo;`、`&rsaquo;`）を使用した前後ナビゲーション記号を表示

---

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

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

### 推奨読解順序

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

まず、ページネーションで使用されるデータ構造とインターフェースを理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | LengthAwarePaginator.php | `src/Illuminate/Pagination/LengthAwarePaginator.php` | ページネーションの主要データ構造、total/lastPage/currentPageなどのプロパティ |
| 1-2 | AbstractPaginator.php | `src/Illuminate/Pagination/AbstractPaginator.php` | 共通メソッド群、URL生成ロジック、ビューファクトリ連携 |

**読解のコツ**: Laravelのページネーションは抽象クラスを継承した具象クラスで実装されている。AbstractPaginatorで定義されたurl()メソッドがページリンクURLを生成する。

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

ビューがどのように呼び出されるかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | LengthAwarePaginator.php | `src/Illuminate/Pagination/LengthAwarePaginator.php` | render()メソッド（100-106行目）でビューが呼び出される |

**主要処理フロー**:
1. **100行目**: `render()`メソッドがビュー名を受け取る
2. **102-105行目**: ViewFactoryを使用してビューを生成、`$paginator`と`$elements`を渡す
3. **146-157行目**: `elements()`メソッドでUrlWindowからページリンク配列を生成

#### Step 3: UrlWindowによるリンク生成を理解する

ページ番号リンクの配列がどのように生成されるかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | UrlWindow.php | `src/Illuminate/Pagination/UrlWindow.php` | ページ数に応じたスライダー形式のリンク配列生成 |

**主要処理フロー**:
- **32-35行目**: `make()`スタティックメソッドでインスタンス生成
- **42-51行目**: `get()`メソッドでページ数に応じた配列形式を決定
- **57-65行目**: ページ数が少ない場合は全ページをfirstに格納
- **73-99行目**: ページ数が多い場合はfirst/slider/lastの3部構成

#### Step 4: Bladeテンプレートを理解する

実際の描画ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | default.blade.php | `src/Illuminate/Pagination/resources/views/default.blade.php` | 条件分岐による描画、アクセシビリティ属性 |

**主要処理フロー**:
- **1行目**: `hasPages()`で表示要否を判定
- **5-13行目**: 前へリンク（先頭ページ判定による無効化制御）
- **16-31行目**: ページ要素のループ（文字列は省略記号、配列はページリンク）
- **35-43行目**: 次へリンク（次ページ有無による無効化制御）

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

```
$paginator->links() / $paginator->render()
    │
    ├─ LengthAwarePaginator::render()
    │      │
    │      ├─ elements() → UrlWindow::make()
    │      │                    └─ get()
    │      │                         ├─ getSmallSlider()
    │      │                         └─ getUrlSlider()
    │      │                              ├─ getSliderTooCloseToBeginning()
    │      │                              ├─ getSliderTooCloseToEnding()
    │      │                              └─ getFullSlider()
    │      │
    │      └─ ViewFactory::make('pagination::default')
    │              └─ default.blade.php
    │
    └─ AbstractPaginator (URL生成)
           ├─ url($page)
           ├─ previousPageUrl()
           ├─ nextPageUrl()
           ├─ onFirstPage()
           └─ hasMorePages()
```

### データフロー図

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

LengthAwarePaginator  ──▶ UrlWindow::make()         ──▶ $elements配列
  - items                    - first: [1=>url, 2=>url]    (ページリンク情報)
  - total                    - slider: [4=>url, 5=>url]
  - perPage                  - last: [9=>url, 10=>url]
  - currentPage              - '...' (省略記号)
  - lastPage
                                    │
                                    ▼
                         default.blade.php           ──▶ HTML出力
                           - @foreach ($elements)         <nav>
                           - ページリンク生成              <ul class="pagination">
                           - 前後ナビ生成                  <li>...</li>
                                                          </ul>
                                                          </nav>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| default.blade.php | `src/Illuminate/Pagination/resources/views/default.blade.php` | テンプレート | デフォルトページネーションの描画 |
| LengthAwarePaginator.php | `src/Illuminate/Pagination/LengthAwarePaginator.php` | ソース | 総件数を把握したページネーター |
| AbstractPaginator.php | `src/Illuminate/Pagination/AbstractPaginator.php` | ソース | ページネーターの基底クラス |
| UrlWindow.php | `src/Illuminate/Pagination/UrlWindow.php` | ソース | ページリンク配列の生成 |
| Paginator.php | `src/Illuminate/Pagination/Paginator.php` | ソース | シンプルページネーター |
| PaginationServiceProvider.php | `src/Illuminate/Pagination/PaginationServiceProvider.php` | ソース | ビュー登録とパブリッシュ設定 |
