管理画面で最もよく使われるのは一覧画面です。件数が数十件のうちは困りませんが、数百・数千件になると「探せない」「表示が遅い」という不満が出てきます。今回は、顧客にひもづく「案件」を追加し、キーワード検索・ステータスでの絞り込み・並べ替え・ページ送りを備えた一覧画面を Laravel 12 と Vue 3 で作ります。
「一覧画面に検索と並べ替えを付けたら、データが増えたときに急に遅くなった。どこに気をつければよかったのか分からない…」
結論から言うと、一覧画面は「関連データの読み込み方(N+1 問題の対策)」「検索条件の入力チェック」「ページング」の3点を最初から押さえておけば、件数が増えても遅くなりにくく、安全に作れます。画面側は Inertia 2 の部分リロードを使うと、条件を変えたときに一覧のデータだけを取り直せます。
(2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)
前回(第3回:ロールと Policy)では、管理者・担当者・閲覧のみの権限を実装しました。今回はそこに案件(projects)を追加し、一覧画面を作り込みます。新しく作るファイルは全文を、すでにあるファイルは変更箇所を差分で載せています。
案件一覧の検索・並べ替え・ページングで作るもの
案件は「どの顧客の、何の仕事か」を表すデータで、必ず1つの顧客に属します。一覧画面には次の機能を付けます。
| 機能 | 内容 | URL の例 |
|---|---|---|
| キーワード検索 | 案件名・顧客名・顧客コードの部分一致 | /projects?q=保守 |
| 絞り込み | ステータス(見込み・進行中・完了・中止・失注) | ?status=in_progress |
| 並べ替え | 案件名・顧客名・ステータス・受注金額・納期・登録日時。昇順/降順 | ?sort=amount&direction=desc |
| ページング | 1ページ 10/20/50 件、検索条件を引き継いでページ送り | ?per_page=10&page=2 |
検索条件はすべて URL のクエリ文字列(? 以降)に載せます。こうしておくと、ブラウザの「戻る」で直前の条件に戻れ、検索結果の URL を同僚に送って同じ画面を見てもらうこともできます。
なお、案件の登録・編集画面は第2回の顧客と同じ作りになるため、この連載では一覧に絞ります。
projects テーブルとリレーションを作る
マイグレーション:外部キーで顧客にひもづける
database/migrations/2025_06_24_000000_create_projects_table.php を新しく作ります。
<?php
// database/migrations/2025_06_24_000000_create_projects_table.php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::create('projects', function (Blueprint $table): void {
$table->id();
// 案件は必ず1つの顧客に属する。案件が残っている顧客は削除できない(restrictOnDelete)
$table->foreignId('customer_id')->constrained()->restrictOnDelete();
$table->string('name', 200);
$table->string('status', 20)->default('prospect')->index();
$table->unsignedBigInteger('amount')->nullable(); // 受注金額(円)
$table->date('due_date')->nullable()->index(); // 納期
$table->timestamps();
});
}
public function down(): void
{
Schema::dropIfExists('projects');
}
};
foreignId('customer_id')->constrained() は、customers テーブルの id を参照する外部キー(=存在しない顧客を指せないようにするデータベースの制約)を作ります。restrictOnDelete() を付けたので、案件が残っている顧客はデータベースの側で削除できません。第2回で「関連データがある顧客の削除」を課題として挙げましたが、今回、顧客の削除処理にも「案件があれば削除せずにメッセージを返す」チェックを追加しました。
絞り込みや並べ替えに使う status と due_date にはインデックス(=検索を速くするための索引)を付けています。
顧客の削除を止めるチェックは、app/Http/Controllers/CustomerController.php に次の変更を加えて追加します(+ が追加、- が削除)。
--- a/app/Http/Controllers/CustomerController.php
+++ b/app/Http/Controllers/CustomerController.php
@@ -75,6 +75,11 @@ public function destroy(Customer $customer): RedirectResponse
{
Gate::authorize('delete', $customer);
+ // 案件が残っている顧客は削除しない(DB の外部キーでも restrictOnDelete で防いでいる)
+ if ($customer->projects()->exists()) {
+ return back()->with('error', 'この顧客には案件が登録されているため削除できません。');
+ }
+
$customer->delete();
return to_route('customers.index')->with('success', '顧客を削除しました。');
エラーメッセージを画面に渡すため、app/Http/Middleware/HandleInertiaRequests.php の flash にも error を足します(+ が追加、- が削除)。
--- a/app/Http/Middleware/HandleInertiaRequests.php
+++ b/app/Http/Middleware/HandleInertiaRequests.php
@@ -58,6 +58,7 @@ public function share(Request $request): array
// 登録・更新・削除後の完了メッセージ(redirect()->with('success', ...) で渡したもの)
'flash' => [
'success' => $request->session()->get('success'),
+ 'error' => $request->session()->get('error'),
],
'sidebarOpen' => ! $request->hasCookie('sidebar_state') || $request->cookie('sidebar_state') === 'true',
];
顧客一覧の画面には、エラーメッセージの表示を足します。resources/js/pages/customers/Index.vue に次の変更を加えます(+ が追加、- が削除)。
--- a/resources/js/pages/customers/Index.vue
+++ b/resources/js/pages/customers/Index.vue
@@ -34,6 +34,9 @@ const destroy = (customer: CustomerRow) => {
</Button>
</div>
+ <p v-if="page.props.flash.error" class="rounded-md bg-red-50 px-4 py-2 text-sm text-red-700">
+ {{ page.props.flash.error }}
+ </p>
<p v-if="page.props.flash.success" class="rounded-md bg-green-50 px-4 py-2 text-sm text-green-700">
{{ page.props.flash.success }}
</p>
ステータスは第3回のロールと同じく、PHP の enum(app/Enums/ProjectStatus.php)で定義します(新規作成)。画面の選択肢用に、値と日本語の表示名の組を返す options() も持たせています。
<?php
// app/Enums/ProjectStatus.php
declare(strict_types=1);
namespace App\Enums;
/**
* 案件のステータス
*/
enum ProjectStatus: string
{
case Prospect = 'prospect'; // 見込み
case InProgress = 'in_progress'; // 進行中
case Completed = 'completed'; // 完了
case Cancelled = 'cancelled'; // 中止・失注
public function label(): string
{
return match ($this) {
self::Prospect => '見込み',
self::InProgress => '進行中',
self::Completed => '完了',
self::Cancelled => '中止・失注',
};
}
/**
* 画面のセレクトボックス用の選択肢
*
* @return list<array{value: string, label: string}>
*/
public static function options(): array
{
return array_map(
fn (self $status): array => ['value' => $status->value, 'label' => $status->label()],
self::cases(),
);
}
}
モデル:belongsTo と hasMany
app/Models/Project.php を新しく作ります。顧客とのひもづけ(customer())のほか、後で説明する検索・並べ替えのスコープと、並べ替えに使える列の一覧(SORTABLE)もここに書きます。
app/Models/Project.php の全文(90行)
<?php
// app/Models/Project.php
declare(strict_types=1);
namespace App\Models;
use App\Enums\ProjectStatus;
use Database\Factories\ProjectFactory;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
class Project extends Model
{
/** @use HasFactory<ProjectFactory> */
use HasFactory;
/** 一覧で並べ替えに使える列(画面から来た値はこの一覧にあるものだけ受け付ける) */
public const SORTABLE = ['name', 'customer', 'status', 'amount', 'due_date', 'created_at'];
/** @var list<string> */
protected $fillable = [
'customer_id',
'name',
'status',
'amount',
'due_date',
];
protected function casts(): array
{
return [
'status' => ProjectStatus::class,
'amount' => 'integer',
'due_date' => 'date:Y-m-d',
];
}
/** @return BelongsTo<Customer, $this> */
public function customer(): BelongsTo
{
return $this->belongsTo(Customer::class);
}
/**
* キーワード検索:案件名 または 顧客名・顧客コード の部分一致
*
* @param Builder<Project> $query
*/
public function scopeSearch(Builder $query, ?string $keyword): void
{
if ($keyword === null || $keyword === '') {
return;
}
// LIKE の特殊文字(% と _)をエスケープして、入力をそのまま文字として検索する
$like = '%'.addcslashes($keyword, '%_\\').'%';
$query->where(function (Builder $q) use ($like): void {
$q->where('name', 'like', $like)
->orWhereHas('customer', fn (Builder $c) => $c
->where('name', 'like', $like)
->orWhere('code', 'like', $like));
});
}
/**
* 並べ替え。$column は ProjectIndexRequest で SORTABLE に含まれることを検証済み
*
* @param Builder<Project> $query
*/
public function scopeSortBy(Builder $query, string $column, string $direction): void
{
if ($column === 'customer') {
// 顧客名で並べ替え(サブクエリで顧客名を引く。JOIN しないので select 列が崩れない)
$query->orderBy(
Customer::select('name')->whereColumn('customers.id', 'projects.customer_id'),
$direction,
);
} else {
$query->orderBy($column, $direction);
}
// 同じ値が並んだときにページをまたいで順序が揺れないよう、最後に id で並べる
$query->orderBy('id', $direction);
}
}
顧客の側には、案件の一覧をたどる projects() を足します。app/Models/Customer.php に次の変更を加えます(+ が追加、- が削除)。
--- a/app/Models/Customer.php
+++ b/app/Models/Customer.php
@@ -9,6 +9,7 @@
use Database\Factories\CustomerFactory;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
class Customer extends Model
{
@@ -28,4 +29,10 @@ class Customer extends Model
'phone',
'note',
];
+
+ /** @return HasMany<Project, $this> */
+ public function projects(): HasMany
+ {
+ return $this->hasMany(Project::class);
+ }
}
「案件は顧客に属する(belongsTo)」「顧客は複数の案件を持つ(hasMany)」という関係をモデルに書いておくと、$project->customer->name のように関連データをたどれるようになります。
N+1 問題を with() と preventLazyLoading で防ぐ
N+1 問題とは
一覧で20件の案件を表示し、各行で $project->customer->name を参照すると、何も工夫しない場合は「案件20件を取る1回」+「顧客を1件ずつ取る20回」の合計21回のクエリが実行されます。このように、件数に比例してクエリが増える現象を N+1 問題と呼びます。件数が少ない開発中は気づきにくく、本番でデータが増えてから遅くなる典型的な原因です。
with('customer') を付けると、Laravel は「案件をまとめて取る1回」+「必要な顧客をまとめて取る1回」で済ませます(Eager Loading=関連データの先読み)。
📰 出典:Laravel 12.x Eloquent: Relationships(Eager Loading)
with() のし忘れを開発中に気づけるようにする
app/Providers/AppServiceProvider.php に次の変更を加えます(+ が追加、- が削除)。
--- a/app/Providers/AppServiceProvider.php
+++ b/app/Providers/AppServiceProvider.php
@@ -4,6 +4,7 @@
use App\Enums\Role;
use App\Models\User;
+use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\ServiceProvider;
@@ -22,6 +23,9 @@ public function register(): void
*/
public function boot(): void
{
+ // 本番以外では、with() し忘れた関連データの遅延読み込み(N+1 の原因)を例外にして気づけるようにする
+ Model::preventLazyLoading(! $this->app->isProduction());
+
// 管理者はすべての操作を許可する。true 以外(null)を返すと、通常どおり Policy の判定に進む
Gate::before(function (User $user, string $ability): ?bool {
return $user->role === Role::Admin ? true : null;
preventLazyLoading を有効にすると、with() で先読みしていない関連データを参照した時点で例外が発生します。開発中とテスト中だけ有効にし、本番では例外にしない(画面が止まらない)設定です。筆者の環境でも、コントローラーから with() を外してテストを実行すると、LazyLoadingViolationException で失敗することを確認しました。
📰 出典:Laravel 12.x Eloquent: Relationships(Preventing Lazy Loading)
検索条件を ProjectIndexRequest で検証する
一覧の検索条件は URL に載るため、利用者が自由に書き換えられます。特に並べ替えの列名をそのまま SQL に渡すと、存在しない列でエラーになったり、見せるべきでない列で並べ替えられたりします。第2回の登録フォームと同じく、FormRequest で検証します。
app/Http/Requests/ProjectIndexRequest.php を新しく作ります。
app/Http/Requests/ProjectIndexRequest.php の全文(83行)
<?php
// app/Http/Requests/ProjectIndexRequest.php
declare(strict_types=1);
namespace App\Http\Requests;
use App\Enums\ProjectStatus;
use App\Models\Project;
use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
/**
* 案件一覧の検索条件(URL のクエリ文字列)を検証する
*/
class ProjectIndexRequest extends FormRequest
{
public function authorize(): bool
{
return $this->user()?->can('viewAny', Project::class) ?? false;
}
/**
* @return array<string, ValidationRule|array<mixed>|string>
*/
public function rules(): array
{
return [
'q' => ['nullable', 'string', 'max:100'],
'status' => ['nullable', Rule::enum(ProjectStatus::class)],
'sort' => ['nullable', Rule::in(Project::SORTABLE)],
'direction' => ['nullable', Rule::in(['asc', 'desc'])],
'per_page' => ['nullable', 'integer', Rule::in([10, 20, 50])],
];
}
/**
* 検証済みの値に既定値を補って返す
*
* @return array{q: string, status: string, sort: string, direction: string, per_page: int}
*/
public function filters(): array
{
$validated = $this->validated();
return [
'q' => (string) ($validated['q'] ?? ''),
'status' => (string) ($validated['status'] ?? ''),
'sort' => (string) ($validated['sort'] ?? 'created_at'),
'direction' => (string) ($validated['direction'] ?? 'desc'),
'per_page' => (int) ($validated['per_page'] ?? 20),
];
}
/**
* @return array<string, string>
*/
public function attributes(): array
{
return [
'q' => 'キーワード',
'status' => 'ステータス',
'sort' => '並べ替え項目',
'direction' => '並び順',
'per_page' => '表示件数',
];
}
/**
* @return array<string, string>
*/
public function messages(): array
{
return [
'max' => ':attributeは:max文字以内で入力してください。',
'in' => ':attributeの値が正しくありません。',
'integer' => ':attributeの値が正しくありません。',
'status' => ':attributeの値が正しくありません。',
];
}
}
Rule::in(Project::SORTABLE):並べ替えに使える列を、モデルに定数で書いた一覧(案件名・顧客・ステータス・受注金額・納期・登録日時)に限定します。Rule::enum(ProjectStatus::class):ステータスは enum に定義された値だけを受け付けます。per_pageを 10・20・50 に限定:?per_page=100000のような指定で、大量のデータを一度に読み込ませないためです。
不正な値が来た場合は、第2回と同じく 302 で前の画面に戻り、エラーメッセージが表示されます。認可は第3回と同じく Policy(ProjectPolicy。一覧は全ロールが閲覧可)を使っています。
app/Policies/ProjectPolicy.php を新しく作ります。
<?php
// app/Policies/ProjectPolicy.php
declare(strict_types=1);
namespace App\Policies;
use App\Models\User;
/**
* 案件の認可ルール(第4回は一覧のみ。管理者は Gate::before で許可済み)
*/
class ProjectPolicy
{
/** 一覧を見る:ログインしていれば全ロール可 */
public function viewAny(User $user): bool
{
return true;
}
}
クエリスコープとコントローラー
キーワード検索と並べ替えのスコープ
app/Models/Project.php(スコープ部分。全文は前述)
/**
* キーワード検索:案件名 または 顧客名・顧客コード の部分一致
*
* @param Builder<Project> $query
*/
public function scopeSearch(Builder $query, ?string $keyword): void
{
if ($keyword === null || $keyword === '') {
return;
}
// LIKE の特殊文字(% と _)をエスケープして、入力をそのまま文字として検索する
$like = '%'.addcslashes($keyword, '%_\\').'%';
$query->where(function (Builder $q) use ($like): void {
$q->where('name', 'like', $like)
->orWhereHas('customer', fn (Builder $c) => $c
->where('name', 'like', $like)
->orWhere('code', 'like', $like));
});
}
/**
* 並べ替え。$column は ProjectIndexRequest で SORTABLE に含まれることを検証済み
*
* @param Builder<Project> $query
*/
public function scopeSortBy(Builder $query, string $column, string $direction): void
{
if ($column === 'customer') {
// 顧客名で並べ替え(サブクエリで顧客名を引く。JOIN しないので select 列が崩れない)
$query->orderBy(
Customer::select('name')->whereColumn('customers.id', 'projects.customer_id'),
$direction,
);
} else {
$query->orderBy($column, $direction);
}
// 同じ値が並んだときにページをまたいで順序が揺れないよう、最後に id で並べる
$query->orderBy('id', $direction);
}
scope で始まるメソッドは、Project::query()->search('保守') のように呼び出せます。
📰 出典:Laravel 12.x Eloquent(Local Scopes)
気をつけたのは2点です。
- LIKE の特殊文字のエスケープ:部分一致検索の
%は「任意の文字列」を意味します。キーワードに%が入ると全件に一致してしまうため、addcslashes()で文字として扱うようにしています。 - 並べ替えの最後に id を加える:受注金額が同じ案件が複数あると、データベースは並び順を保証しません。ページをまたいで同じ案件が2回出たり、出なかったりするのを防ぐため、最後に id で並べます。
コントローラー:with() と withQueryString()
app/Http/Controllers/ProjectController.php を新しく作ります。
<?php
// app/Http/Controllers/ProjectController.php
declare(strict_types=1);
namespace App\Http\Controllers;
use App\Enums\ProjectStatus;
use App\Http\Requests\ProjectIndexRequest;
use App\Models\Project;
use Inertia\Inertia;
use Inertia\Response;
class ProjectController extends Controller
{
public function index(ProjectIndexRequest $request): Response
{
$filters = $request->filters();
$projects = Project::query()
->select(['id', 'customer_id', 'name', 'status', 'amount', 'due_date', 'created_at'])
// N+1 対策:顧客をまとめて1回のクエリで読み込む(必要な列だけ)
->with('customer:id,code,name')
->search($filters['q'])
->when($filters['status'] !== '', fn ($query) => $query->where('status', $filters['status']))
->sortBy($filters['sort'], $filters['direction'])
->paginate($filters['per_page'])
// ページ送りのリンクに検索条件(?q=...&sort=...)を引き継ぐ
->withQueryString()
->through(fn (Project $project): array => [
'id' => $project->id,
'name' => $project->name,
'customer' => $project->customer->only(['id', 'code', 'name']),
'status' => $project->status->value,
'status_label' => $project->status->label(),
'amount' => $project->amount,
'due_date' => $project->due_date?->format('Y-m-d'),
]);
return Inertia::render('projects/Index', [
'projects' => $projects,
'filters' => $filters,
// 選択肢は検索のたびに変わらないので、部分リロード(only: ['projects', 'filters'])では送らない
'statuses' => fn () => ProjectStatus::options(),
]);
}
}
withQueryString() を付けないと、2ページ目へのリンクが ?page=2 だけになり、検索条件が消えてしまいます。
📰 出典:Laravel 12.x Pagination(Appending Query String Values)
statuses を fn () => ... のように関数で渡しているのは、後述の部分リロードで「必要なときだけ計算する」ためです。
Vue の一覧画面:DataTable と部分リロード
部分リロードで一覧だけを取り直す
一覧画面 resources/js/pages/projects/Index.vue を新しく作ります。
resources/js/pages/projects/Index.vue の全文(129行)
<!-- resources/js/pages/projects/Index.vue -->
<script setup lang="ts">
import DataTable, { type Column } from '@/components/DataTable.vue';
import Heading from '@/components/Heading.vue';
import { Input } from '@/components/ui/input';
import AppLayout from '@/layouts/AppLayout.vue';
import { type BreadcrumbItem, type Paginated, type ProjectFilters, type ProjectRow, type SelectOption } from '@/types';
import { Head, router, usePage } from '@inertiajs/vue3';
import { useDebounceFn } from '@vueuse/core';
import { reactive, watch } from 'vue';
const props = defineProps<{
projects: Paginated<ProjectRow>;
filters: ProjectFilters;
statuses: SelectOption[];
}>();
const page = usePage();
const breadcrumbs: BreadcrumbItem[] = [{ title: '案件', href: '/projects' }];
const columns: Column[] = [
{ key: 'name', label: '案件名', sortable: true },
{ key: 'customer', label: '顧客', sortable: true },
{ key: 'status', label: 'ステータス', sortable: true },
{ key: 'amount', label: '受注金額', sortable: true, align: 'right' },
{ key: 'due_date', label: '納期', sortable: true },
];
// 絞り込みフォームの状態(初期値はサーバーが検証・補完した filters)
const form = reactive({
q: props.filters.q,
status: props.filters.status,
per_page: props.filters.per_page,
});
// 検索条件を URL のクエリにして一覧だけを取り直す(Inertia 2 の部分リロード)
const reload = (overrides: Partial<ProjectFilters> = {}) => {
const query = {
q: form.q,
status: form.status,
sort: props.filters.sort,
direction: props.filters.direction,
per_page: form.per_page,
...overrides,
};
router.get(
route('projects.index'),
// 空の条件は URL に載せない(page も付けないので、条件を変えると1ページ目に戻る)
Object.fromEntries(Object.entries(query).filter(([, value]) => value !== '')),
{
only: ['projects', 'filters'],
preserveState: true,
preserveScroll: true,
replace: true,
},
);
};
// キーワードは入力のたびに送らず、入力が 300ms 止まってから検索する
watch(
() => form.q,
useDebounceFn(() => reload(), 300),
);
watch(
() => [form.status, form.per_page],
() => reload(),
);
const onSort = (key: string) => {
const direction = props.filters.sort === key && props.filters.direction === 'asc' ? 'desc' : 'asc';
reload({ sort: key, direction });
};
const yen = new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' });
</script>
<template>
<Head title="案件一覧" />
<AppLayout :breadcrumbs="breadcrumbs">
<div class="space-y-4 p-4">
<Heading title="案件一覧" />
<div class="flex flex-wrap items-end gap-3">
<div class="grid gap-1">
<label for="q" class="text-sm">キーワード(案件名・顧客名・顧客コード)</label>
<Input id="q" v-model="form.q" type="search" class="w-72" placeholder="例:保守" />
</div>
<div class="grid gap-1">
<label for="status" class="text-sm">ステータス</label>
<select id="status" v-model="form.status" class="border-input h-9 rounded-md border bg-transparent px-3 text-sm">
<option value="">すべて</option>
<option v-for="status in statuses" :key="status.value" :value="status.value">{{ status.label }}</option>
</select>
</div>
<div class="grid gap-1">
<label for="per_page" class="text-sm">表示件数</label>
<select id="per_page" v-model.number="form.per_page" class="border-input h-9 rounded-md border bg-transparent px-3 text-sm">
<option v-for="n in [10, 20, 50]" :key="n" :value="n">{{ n }} 件</option>
</select>
</div>
</div>
<!-- 不正な検索条件(URL を直接書き換えた場合など)のエラー -->
<ul v-if="Object.keys(page.props.errors).length > 0" class="rounded-md bg-red-50 px-4 py-2 text-sm text-red-700">
<li v-for="(message, key) in page.props.errors" :key="key">{{ message }}</li>
</ul>
<DataTable
:columns="columns"
:paginator="projects"
:sort="filters.sort"
:direction="filters.direction"
:only="['projects', 'filters']"
@sort="onSort"
>
<template #cell-customer="{ row }">
<span class="text-muted-foreground font-mono text-xs">{{ row.customer.code }}</span>
{{ row.customer.name }}
</template>
<template #cell-status="{ row }">{{ row.status_label }}</template>
<template #cell-amount="{ row }">{{ row.amount === null ? '-' : yen.format(row.amount) }}</template>
<template #cell-due_date="{ row }">{{ row.due_date ?? '-' }}</template>
</DataTable>
</div>
</AppLayout>
</template>
router.get() の only: ['projects', 'filters'] が部分リロードの指定です。サーバーは指定された props だけを返し、関数で渡した statuses は計算すらしません。preserveState で入力中の検索ボックスの状態を保ち、replace でブラウザの履歴を1文字ごとに増やさないようにしています。キーワードの入力は、@vueuse/core(スターターキットに同梱)の useDebounceFn で 300ミリ秒待ってから送ります。
📰 出典:Inertia.js v2 Partial reloads
DataTable.vue:並べ替えの見出しとページ送りを部品にする
resources/js/components/DataTable.vue を新しく作ります。
resources/js/components/DataTable.vue の全文(97行)
<!-- resources/js/components/DataTable.vue -->
<script setup lang="ts" generic="T extends { id: number }">
import { Button } from '@/components/ui/button';
import { type Paginated } from '@/types';
import { Link } from '@inertiajs/vue3';
import { ArrowDown, ArrowUp, ArrowUpDown } from 'lucide-vue-next';
export interface Column {
key: string;
label: string;
sortable?: boolean;
align?: 'left' | 'right';
}
const props = defineProps<{
columns: Column[];
paginator: Paginated<T>;
sort: string;
direction: 'asc' | 'desc';
// ページ送りで再取得する props(部分リロード)。省略時はページ全体を取り直す
only?: string[];
}>();
const emit = defineEmits<{
sort: [key: string];
}>();
// 「« Previous」「Next »」を除いた、ページ番号(と「...」)のリンク
const pageLinks = () => props.paginator.links.slice(1, -1);
// スロットで差し替えない列は、行データの同名のキーをそのまま表示する
const cell = (row: T, key: string): unknown => (row as Record<string, unknown>)[key];
</script>
<template>
<div class="space-y-3">
<table class="w-full text-left text-sm">
<thead class="text-muted-foreground border-b">
<tr>
<th
v-for="column in columns"
:key="column.key"
class="py-2"
:class="column.align === 'right' ? 'text-right' : ''"
:aria-sort="column.sortable && sort === column.key ? (direction === 'asc' ? 'ascending' : 'descending') : undefined"
>
<button
v-if="column.sortable"
type="button"
class="hover:text-foreground inline-flex items-center gap-1"
@click="emit('sort', column.key)"
>
{{ column.label }}
<ArrowUp v-if="sort === column.key && direction === 'asc'" class="size-3" />
<ArrowDown v-else-if="sort === column.key && direction === 'desc'" class="size-3" />
<ArrowUpDown v-else class="size-3 opacity-40" />
</button>
<span v-else>{{ column.label }}</span>
</th>
</tr>
</thead>
<tbody>
<tr v-for="row in paginator.data" :key="row.id" class="border-b">
<td v-for="column in columns" :key="column.key" class="py-2" :class="column.align === 'right' ? 'text-right' : ''">
<!-- 列ごとの表示を親から差し替えられる(例:#cell-customer) -->
<slot :name="`cell-${column.key}`" :row="row">
{{ cell(row, column.key) }}
</slot>
</td>
</tr>
<tr v-if="paginator.data.length === 0">
<td :colspan="columns.length" class="text-muted-foreground py-8 text-center">該当するデータがありません。</td>
</tr>
</tbody>
</table>
<div class="flex flex-wrap items-center justify-between gap-2 text-sm">
<span>全 {{ paginator.total }} 件中 {{ paginator.from ?? 0 }}〜{{ paginator.to ?? 0 }} 件目</span>
<nav class="flex items-center gap-1" aria-label="ページ送り">
<Button variant="outline" size="sm" :disabled="!paginator.prev_page_url" as-child>
<Link v-if="paginator.prev_page_url" :href="paginator.prev_page_url" :only="only" preserve-state preserve-scroll>前へ</Link>
<span v-else>前へ</span>
</Button>
<template v-for="(link, index) in pageLinks()" :key="index">
<Button v-if="link.url" :variant="link.active ? 'default' : 'ghost'" size="sm" as-child>
<Link :href="link.url" :only="only" preserve-state preserve-scroll>{{ link.label }}</Link>
</Button>
<span v-else class="text-muted-foreground px-2">{{ link.label }}</span>
</template>
<Button variant="outline" size="sm" :disabled="!paginator.next_page_url" as-child>
<Link v-if="paginator.next_page_url" :href="paginator.next_page_url" :only="only" preserve-state preserve-scroll>次へ</Link>
<span v-else>次へ</span>
</Button>
</nav>
</div>
</div>
</template>
DataTable は列の定義(columns)と Laravel のページング結果(paginator)を受け取り、並べ替えの見出しをクリックすると sort イベントを親に知らせます。どの列で並べ替えるかを決めるのは親(とサーバー)です。ページ送りのリンクにも同じ only を渡し、ページを移るときも一覧だけを取り直します。
一覧画面からは、次のように使います。顧客名や金額のように表示を工夫したい列だけ、スロット(=部品の一部を差し替える仕組み)で書き換えます。
resources/js/pages/projects/Index.vue(テンプレートの抜粋。全文は前述)
<DataTable
:columns="columns"
:paginator="projects"
:sort="filters.sort"
:direction="filters.direction"
:only="['projects', 'filters']"
@sort="onSort"
>
<template #cell-customer="{ row }">
<span class="text-muted-foreground font-mono text-xs">{{ row.customer.code }}</span>
{{ row.customer.name }}
</template>
<template #cell-status="{ row }">{{ row.status_label }}</template>
<template #cell-amount="{ row }">{{ row.amount === null ? '-' : yen.format(row.amount) }}</template>
<template #cell-due_date="{ row }">{{ row.due_date ?? '-' }}</template>
</DataTable>
テストでクエリ数と不正な条件を確かめる
tests/Feature/ProjectIndexTest.php を新しく作ります。
tests/Feature/ProjectIndexTest.php の全文(161行)
<?php
// tests/Feature/ProjectIndexTest.php
declare(strict_types=1);
namespace Tests\Feature;
use App\Enums\ProjectStatus;
use App\Http\Middleware\HandleInertiaRequests;
use App\Models\Customer;
use App\Models\Project;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Inertia\Testing\AssertableInertia as Assert;
use Tests\TestCase;
class ProjectIndexTest extends TestCase
{
use RefreshDatabase;
public function test_guests_are_redirected_to_the_login_page(): void
{
$this->get('/projects')->assertRedirect('/login');
}
public function test_viewer_can_see_the_list_with_customer(): void
{
$customer = Customer::factory()->create(['code' => 'C00001', 'name' => '株式会社サンプル']);
Project::factory()->for($customer)->create(['name' => '管理画面の新規開発']);
$this->actingAs(User::factory()->viewer()->create())
->get('/projects')
->assertOk()
->assertInertia(fn (Assert $page) => $page
->component('projects/Index')
->where('projects.data.0.name', '管理画面の新規開発')
->where('projects.data.0.customer.name', '株式会社サンプル')
->where('filters.sort', 'created_at')
->has('statuses', 4)
);
}
public function test_keyword_matches_project_name_or_customer(): void
{
$acme = Customer::factory()->create(['code' => 'C00001', 'name' => 'アクメ商事']);
$other = Customer::factory()->create(['code' => 'C00002', 'name' => '別の会社']);
Project::factory()->for($acme)->create(['name' => '基幹システム改修']);
Project::factory()->for($other)->create(['name' => '保守・運用']);
Project::factory()->for($other)->create(['name' => 'データ移行']);
$user = User::factory()->create();
// 案件名での一致
$this->actingAs($user)->get('/projects?q=保守')
->assertInertia(fn (Assert $page) => $page->has('projects.data', 1)->where('projects.data.0.name', '保守・運用'));
// 顧客名での一致
$this->actingAs($user)->get('/projects?q=アクメ')
->assertInertia(fn (Assert $page) => $page->has('projects.data', 1)->where('projects.data.0.name', '基幹システム改修'));
// % は「任意の文字列」ではなく文字として扱う
$this->actingAs($user)->get('/projects?q=%25')
->assertInertia(fn (Assert $page) => $page->has('projects.data', 0));
}
public function test_status_filter_and_sort(): void
{
Project::factory()->create(['name' => 'A', 'status' => ProjectStatus::InProgress, 'amount' => 1_000_000]);
Project::factory()->create(['name' => 'B', 'status' => ProjectStatus::InProgress, 'amount' => 3_000_000]);
Project::factory()->create(['name' => 'C', 'status' => ProjectStatus::Completed, 'amount' => 2_000_000]);
$this->actingAs(User::factory()->create())
->get('/projects?status=in_progress&sort=amount&direction=desc')
->assertInertia(fn (Assert $page) => $page
->has('projects.data', 2)
->where('projects.data.0.name', 'B')
->where('projects.data.1.name', 'A')
->where('filters.status', 'in_progress')
);
}
public function test_sort_by_customer_name(): void
{
Project::factory()->for(Customer::factory()->state(['name' => 'いろは']))->create(['name' => 'X']);
Project::factory()->for(Customer::factory()->state(['name' => 'あいう']))->create(['name' => 'Y']);
$this->actingAs(User::factory()->create())
->get('/projects?sort=customer&direction=asc')
->assertInertia(fn (Assert $page) => $page->where('projects.data.0.name', 'Y'));
}
public function test_invalid_query_is_rejected(): void
{
$this->actingAs(User::factory()->create())
->from('/projects')
->get('/projects?sort=password&direction=up&per_page=1000&status=unknown')
->assertRedirect('/projects')
->assertSessionHasErrors(['sort', 'direction', 'per_page', 'status']);
}
public function test_pagination_keeps_query_string(): void
{
Project::factory()->count(25)->create(['status' => ProjectStatus::Prospect]);
$this->actingAs(User::factory()->create())
->get('/projects?status=prospect&per_page=10')
->assertInertia(fn (Assert $page) => $page
->has('projects.data', 10)
->where('projects.total', 25)
->where('projects.last_page', 3)
->where('projects.next_page_url', fn (string $url) => str_contains($url, 'status=prospect') && str_contains($url, 'page=2'))
);
}
public function test_query_count_does_not_grow_with_rows(): void
{
$user = User::factory()->create();
$countQueries = function () use ($user): int {
$count = 0;
DB::listen(function () use (&$count): void {
$count++;
});
$this->actingAs($user)->get('/projects?per_page=50')->assertOk();
return $count;
};
Project::factory()->count(5)->create();
$few = $countQueries();
Project::factory()->count(45)->create();
$many = $countQueries();
// 5件でも50件でもクエリ数は同じ(顧客を1件ずつ読みに行く N+1 が起きていない)
$this->assertSame($few, $many);
}
public function test_partial_reload_skips_status_options(): void
{
Project::factory()->create();
// 画面のビルド結果から計算されるアセットのバージョン(食い違うと 409 が返る)
$version = (new HandleInertiaRequests)->version(Request::create('/'));
// Inertia 2 の部分リロード:only に指定した props だけが返る
$this->actingAs(User::factory()->create())
->withHeaders([
'X-Inertia' => 'true',
'X-Inertia-Version' => (string) $version,
'X-Inertia-Partial-Component' => 'projects/Index',
'X-Inertia-Partial-Data' => 'projects,filters',
])
->get('/projects?q=')
->assertOk()
->assertJsonPath('component', 'projects/Index')
->assertJsonStructure(['props' => ['projects', 'filters']])
->assertJsonMissingPath('props.statuses');
}
}
DB::listen() は、実行された SQL を1件ずつ受け取れる仕組みです。表示件数が5件と50件でクエリの数が同じなら、件数に比例して増える N+1 は起きていません。
このほか、キーワード検索(% を入力しても全件一致にならないことを含む)、絞り込みと並べ替え、ページ送りでの条件の引き継ぎ、部分リロード、のテストを書きました。案件がある顧客の削除防止のテストも追加し、全体で52件になりました。
tests/Feature/CustomerTest.php に次の変更を加えます(+ が追加、- が削除)。
--- a/tests/Feature/CustomerTest.php
+++ b/tests/Feature/CustomerTest.php
@@ -7,6 +7,7 @@
namespace Tests\Feature;
use App\Models\Customer;
+use App\Models\Project;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Inertia\Testing\AssertableInertia as Assert;
@@ -119,4 +120,19 @@ public function test_customer_can_be_deleted(): void
$this->assertModelMissing($customer);
}
+
+ public function test_customer_with_projects_cannot_be_deleted(): void
+ {
+ $customer = Customer::factory()->create();
+ Project::factory()->for($customer)->create();
+
+ // 案件がある顧客は削除できない(第4回)
+ $this->actingAs(User::factory()->admin()->create())
+ ->from('/customers')
+ ->delete("/customers/{$customer->id}")
+ ->assertRedirect('/customers')
+ ->assertSessionHas('error');
+
+ $this->assertModelExists($customer);
+ }
}
ルート・メニュー・型・テストデータ
最後に、画面を開けるようにするための変更と、テスト・動作確認用のデータの準備です。
routes/web.php に次の変更を加えます(+ が追加、- が削除)。
--- a/routes/web.php
+++ b/routes/web.php
@@ -1,6 +1,7 @@
<?php
use App\Http\Controllers\CustomerController;
+use App\Http\Controllers\ProjectController;
use Illuminate\Support\Facades\Route;
use Inertia\Inertia;
@@ -15,6 +16,9 @@
Route::middleware(['auth', 'verified'])->group(function () {
// 顧客マスタ(一覧・登録・編集・削除)。詳細画面は使わないので show は除外
Route::resource('customers', CustomerController::class)->except(['show']);
+
+ // 案件一覧(検索・並べ替え・ページング)
+ Route::get('projects', [ProjectController::class, 'index'])->name('projects.index');
});
require __DIR__.'/settings.php';
左のメニューに「案件」を追加します。resources/js/components/AppSidebar.vue に次の変更を加えます(+ が追加、- が削除)。
--- a/resources/js/components/AppSidebar.vue
+++ b/resources/js/components/AppSidebar.vue
@@ -5,7 +5,7 @@ import NavUser from '@/components/NavUser.vue';
import { Sidebar, SidebarContent, SidebarFooter, SidebarHeader, SidebarMenu, SidebarMenuButton, SidebarMenuItem } from '@/components/ui/sidebar';
import { type NavItem } from '@/types';
import { Link } from '@inertiajs/vue3';
-import { BookOpen, Folder, LayoutGrid, Users } from 'lucide-vue-next';
+import { BookOpen, Briefcase, Folder, LayoutGrid, Users } from 'lucide-vue-next';
import AppLogo from './AppLogo.vue';
const mainNavItems: NavItem[] = [
@@ -19,6 +19,11 @@ const mainNavItems: NavItem[] = [
href: '/customers',
icon: Users,
},
+ {
+ title: '案件',
+ href: '/projects',
+ icon: Briefcase,
+ },
];
const footerNavItems: NavItem[] = [
画面で使う型を追加します。resources/js/types/index.d.ts に次の変更を加えます(+ が追加、- が削除)。
--- a/resources/js/types/index.d.ts
+++ b/resources/js/types/index.d.ts
@@ -26,7 +26,7 @@ export interface SharedData extends PageProps {
quote: { message: string; author: string };
auth: Auth;
ziggy: Config & { location: string };
- flash: { success: string | null };
+ flash: { success: string | null; error: string | null };
sidebarOpen: boolean;
}
@@ -78,3 +78,29 @@ export interface Customer {
export interface CustomerRow extends Customer {
can: { update: boolean; delete: boolean };
}
+
+export type ProjectStatus = 'prospect' | 'in_progress' | 'completed' | 'cancelled';
+
+// 案件一覧の1行(ProjectController::index の through() で組み立てた形)
+export interface ProjectRow {
+ id: number;
+ name: string;
+ customer: Pick<Customer, 'id' | 'code' | 'name'>;
+ status: ProjectStatus;
+ status_label: string;
+ amount: number | null;
+ due_date: string | null;
+}
+
+export interface ProjectFilters {
+ q: string;
+ status: ProjectStatus | '';
+ sort: string;
+ direction: 'asc' | 'desc';
+ per_page: number;
+}
+
+export interface SelectOption {
+ value: string;
+ label: string;
+}
テストとシーダーで使う database/factories/ProjectFactory.php を新しく作ります。
<?php
// database/factories/ProjectFactory.php
declare(strict_types=1);
namespace Database\Factories;
use App\Enums\ProjectStatus;
use App\Models\Customer;
use App\Models\Project;
use Illuminate\Database\Eloquent\Factories\Factory;
/**
* @extends Factory<Project>
*/
class ProjectFactory extends Factory
{
/**
* @return array<string, mixed>
*/
public function definition(): array
{
return [
'customer_id' => Customer::factory(),
'name' => fake()->randomElement(['基幹システム改修', '管理画面の新規開発', 'Webサイト リニューアル', '保守・運用', 'データ移行', '業務アプリ開発'])
.' '.fake()->numberBetween(1, 999),
'status' => fake()->randomElement(ProjectStatus::cases()),
'amount' => fake()->boolean(80) ? fake()->numberBetween(10, 3000) * 10000 : null,
'due_date' => fake()->optional(0.8)->dateTimeBetween('-6 months', '+1 year'),
];
}
}
database/seeders/DatabaseSeeder.php に次の変更を加えます(+ が追加、- が削除)。
--- a/database/seeders/DatabaseSeeder.php
+++ b/database/seeders/DatabaseSeeder.php
@@ -3,6 +3,7 @@
namespace Database\Seeders;
use App\Models\Customer;
+use App\Models\Project;
use App\Models\User;
// use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Seeder;
@@ -24,7 +25,9 @@ public function run(): void
User::factory()->create(['name' => '担当者', 'email' => 'staff@example.com']);
User::factory()->viewer()->create(['name' => '閲覧者', 'email' => 'viewer@example.com']);
- // 一覧の確認用に、顧客を10件作る
- Customer::factory(10)->create();
+ // 一覧の検索・並べ替え・ページングを試すため、顧客50件・案件500件(1顧客10件)を作る
+ Customer::factory(50)
+ ->has(Project::factory()->count(10))
+ ->create();
}
}
動作確認の方法
docker compose run --rm --no-deps app php artisan test
docker compose run --rm --no-deps node sh -c "npm run build"
docker compose up -d mysql app
docker compose exec app php artisan migrate:fresh --seed # 顧客50件・案件500件(ローカルのDBを作り直すので注意)
シーダーは、顧客50件のそれぞれに案件を10件ずつ、合計500件作ります。筆者の環境では次のことを確認しました。
- 全52件のテストが成功し、
npm run buildも成功 - 一覧が「全 500 件中 1〜20 件目」で表示され、キーワード「保守」+ステータス「進行中」+受注金額の降順+10件表示で絞り込める。次ページのリンクに条件がすべて残る
- 顧客名での並べ替えと、3ページ目への移動ができる
?sort=passwordのような不正な並べ替えでは「並べ替え項目の値が正しくありません。」が表示される- tinker で
DB::enableQueryLog()を使い、50件表示のときのクエリが「件数」「案件」「顧客」の3回であることを確認
つまずきやすい点・セキュリティ上の注意
- 並べ替えの列名を検証せずに使わない:
orderBy($request->sort)のように利用者の入力をそのまま渡すと、存在しない列でエラー画面が出たり、画面に出していない列(金額や内部のフラグなど)で並べ替えて中身を推測されたりするおそれがあります。必ず許可した列の一覧で検証します。 - 部分一致検索は件数が増えると遅くなる:
LIKE '%保守%'のような前後の部分一致は、通常のインデックスが効きません。数万件程度までは問題になりにくいですが、それ以上の件数や全文検索が必要な場合は、全文検索インデックスや検索エンジンの導入を検討します。 with()した列の指定に外部キーを含める:with('customer:id,code,name')のように列を絞るときは、idを必ず含めます。含めないと顧客と案件を結び付けられず、顧客が空になります。同じ理由で、案件側のselect()にもcustomer_idが必要です。- ページを大きくしすぎない:「全件表示したい」という要望には、表示件数を増やすのではなく CSV 出力など別の機能で応えるのが安全です。
発注者向けメモ:一覧画面の要望は最初に列挙して優先度をつける
一覧画面は、運用が始まってから要望が膨らみやすい画面です。「この列でも並べ替えたい」「この条件でも絞り込みたい」「CSVで出したい」「前回の検索条件を覚えておいてほしい」と、1つずつは小さく見えても、積み重なると大きな工数になります。
最初に、次の項目を一覧にして優先度をつけておくのが工数管理のコツです。
- 表示する列:どの列を、どの順で出すか。金額など、ロールによって隠したい列はあるか
- 検索・絞り込みの条件:キーワードの対象項目、期間指定、複数条件の組み合わせ(AND か OR か)
- 並べ替えできる列と初期の並び順
- 1ページの件数と、想定するデータ件数:数百件なのか、数十万件なのかで作り方が変わります
- CSV出力・一括操作:必要なら、出力件数の上限や権限も決めます
開発会社には、次のように確認してみてください。
- 「データが今の10倍に増えても、一覧画面の表示速度は保てますか?そのためにどんな対策をしていますか?」
- 「検索条件や並べ替えを URL で共有できますか?ブラウザの『戻る』で条件は残りますか?」
- 「一覧に列や検索条件を1つ追加する場合、どのくらいの工数になりますか?」
- 「表示速度の確認は、本番に近い件数のデータで行いますか?」
まとめと次回予告
第4回では、顧客にひもづく案件を追加し、検索・並べ替え・ページングを備えた一覧画面を作りました。
- 案件は外部キーで顧客にひもづけ、案件がある顧客は削除できないようにした
with()で関連データを先読みし、preventLazyLoadingで N+1 を開発中に検知。テストでクエリ数が件数に比例しないことを確かめる- 検索条件は
ProjectIndexRequestで検証し、並べ替えの列・表示件数・ステータスは許可した値だけを受け付ける withQueryString()でページ送りに条件を引き継ぎ、Inertia 2 の部分リロード(only)で一覧だけを取り直す
次回は「請求と非同期処理:キューとスケジューラをローカルで動かす」です。案件にひもづく請求を追加し、請求書の発行を裏側で順番に処理するキューと、月次の締め処理・支払期限の超過チェックを定期実行するスケジューラを、Docker の開発環境で動かします。
この連載の記事一覧
この記事は連載「Laravel+Vue.jsで作る管理画面をECSで動かす」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第1回】全体像と開発環境:Laravel 12+Vue 3 スターターキットを Docker で動かす
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第2回】顧客マスタの一覧と登録:FormRequest でバリデーションする
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第3回】ロールと Policy:誰が何をできるかをコードで決める
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第4回】案件管理と一覧画面の作り込み:検索・並べ替え・ページング(この記事)
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第5回】請求と非同期処理:キューとスケジューラをローカルで動かす
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第6回】本番用コンテナイメージを作る:マルチステージ Dockerfile
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第7回】Terraform の土台とネットワーク:state 管理と VPC
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第8回】RDS for MySQL と秘密情報:パスワードをコードに書かない
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第9回】ECR・ECS on Fargate・ALB:管理画面をインターネットに公開する
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第10回】キューワーカーとスケジューラを ECS で動かす
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第11回】GitHub Actions で CI/CD:OIDC でキーを持たずにデプロイ
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第12回】運用編:ログ・監視・スケーリング・切り戻し










コメント
コメント一覧 (1件)
[…] 前回(第4回:案件管理と一覧画面の作り込み)では、案件一覧に検索・並べ替え・ページングを付けました。今回はその案件に請求を追加し、Docker の開発環境にキューワーカーとスケジューラのコンテナを加えます。 […]