Vue.js 入門 — 搭配 Inertia × Laravel 使用的基礎知識

什麼是 Vue.js

Vue.js（以下簡稱 Vue）是用於建構使用者介面的漸進式 JavaScript 框架。「漸進式」意指可以從小規模開始，並依需要追加功能，既能部分嵌入既有 HTML 頁面，也能建構大規模的 SPA。 Vue 的核心是反應式。當資料變化時 DOM 會自動更新，因此開發者不需要手動管理「何時、更新哪個元素」。

本頁介紹的是 Vue 3 與 Inertia v3 的組合。Laravel 13 的入門套件預設使用此組合。

Options API 與 Composition API

Vue 3 提供了兩種撰寫元件的風格：Options API 與 Composition API。 Options API 是延續 Vue 2 的傳統風格。以 data、methods、computed、mounted 等選項物件定義元件。

<!-- Options API 範例 -->
<script>
export default {
    data() {
        return { count: 0 }
    },
    methods: {
        increment() {
            this.count++
        }
    }
}
</script>

<template>
    <button @click="increment">{{ count }}</button>
</template>

Composition API 是 Vue 3 導入的新風格。結合 <script setup> 語法後可以更簡潔地撰寫。邏輯的可重用性也更高，與 TypeScript 相容性也很好。

<!-- Composition API（<script setup>）範例 -->
<script setup>
import { ref } from 'vue'

const count = ref(0)

function increment() {
    count.value++
}
</script>

<template>
    <button @click="increment">{{ count }}</button>
</template>

Inertia × Laravel 的入門套件標準採用 <script setup> 的 Composition API 風格。本頁範例也全部以 <script setup> 撰寫。

在 Laravel 中的定位

歷史

Vue 與 Laravel 的關係歷史悠久，可追溯至 Laravel 5.3（2016 年） 採用 Vue 作為預設前端框架。當時的 package.json 中就包含 Vue，並附有 resources/js/components/ExampleComponent.vue 這樣的範例元件。 Laravel 6（2019 年） 將認證 scaffold 切分為 laravel/ui 套件，Vue 的 scaffold 也移至該套件。目前主流是透過 laravel new 的入門套件選擇 Inertia + Vue 組合。對 Laravel 使用者來說，Vue 是最熟悉的 JS 框架，日文學習資源也很豐富。

目前的主流方式：Inertia × Vue

目前 Laravel 中使用 Vue 的主要方式是 Inertia × Vue。Inertia 可以不設計 API，直接從 Laravel 的 controller 將資料傳給 Vue 元件，實現「現代單體式」架構。

安裝設定

透過入門套件（推薦）

要新建專案時，使用入門套件是最方便的方式。

laravel new my-app

在互動式提示中選擇 Vue，以下項目就會全部自動設定完成。

inertiajs/inertia-laravel（伺服器端 adapter）
@inertiajs/vue3（客戶端 adapter）
vue（Vue 3 主體）
@vitejs/plugin-vue（Vite plugin）
HandleInertiaRequests middleware
登入、註冊等認證畫面（以 Inertia + Vue 實作完畢）

手動安裝

要加入既有專案時，需將伺服器端與客戶端分開安裝。

# 伺服器端（PHP）
composer require inertiajs/inertia-laravel

# 客戶端（JavaScript）
npm install @inertiajs/vue3 vue
npm install --save-dev @vitejs/plugin-vue

接著，在 vite.config.js 中加入 Vue plugin。

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
})

在 resources/js/app.js 啟動 Inertia 應用。

import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

createInertiaApp({
    resolve: (name) =>
        resolvePageComponent(
            `./pages/${name}.vue`,
            import.meta.glob('./pages/**/*.vue'),
        ),
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el)
    },
})

手動安裝的詳情（root template 設定、middleware 註冊等）請參考 Inertia 官方文件。

目錄結構

入門套件將 Vue 的頁面元件放在 resources/js/pages/ 目錄下。

resources/js/
├── app.js             # Inertia 應用的起點
├── bootstrap.js
├── components/        # 可重用的 UI 元件
│   ├── NavBar.vue
│   └── ...
├── layouts/           # 版面配置元件
│   ├── AppLayout.vue
│   └── AuthLayout.vue
└── pages/             # Inertia 頁面元件（對應 controller 名稱）
    ├── Auth/
    │   ├── Login.vue
    │   └── Register.vue
    ├── Dashboard.vue
    └── Posts/
        ├── Index.vue
        ├── Create.vue
        └── Show.vue

寫成 Inertia::render('Posts/Index', [...]) 時，resources/js/pages/Posts/Index.vue 就會是對應的元件。

Vue 模板語法

介紹讀寫入門套件程式碼所需的基本模板 directive。

`{{ }}` — 變數展開

使用雙大括號將 JavaScript 值或運算式內嵌到模板中。

<script setup>
const name = '世界'
const count = 3
</script>

<template>
    <p>你好，{{ name }}！</p>
    <p>兩倍是 {{ count * 2 }}</p>
</template>

`v-if` — 條件分支

<template>
    <p v-if="isLoggedIn">歡迎！</p>
    <p v-else-if="role === 'admin'">以管理員身份登入中</p>
    <a v-else href="/login">登入</a>
</template>

相當於 Svelte 的 {#if} 或 React 的三元運算子。

`v-for` — 清單渲染

<template>
    <ul>
        <li v-for="post in posts" :key="post.id">{{ post.title }}</li>
    </ul>
</template>

為了高效的差異更新，:key 必須指定。相當於 React 的 Array.map()。

`v-model` — 雙向繫結

使用 v-model 可讓表單元素的值與反應式變數進行雙向同步。

<script setup>
import { ref } from 'vue'

const title = ref('')
const agreed = ref(false)
const role = ref('viewer')
</script>

<template>
    <!-- 文字輸入 -->
    <input v-model="title" type="text" />
    <p>輸入中: {{ title }}</p>

    <!-- 核取方塊 -->
    <input v-model="agreed" type="checkbox" />
    <p>同意: {{ agreed }}</p>

    <!-- 下拉選單 -->
    <select v-model="role">
        <option value="viewer">閱覽者</option>
        <option value="editor">編輯者</option>
        <option value="admin">管理員</option>
    </select>
</template>

`:` (v-bind) 與 `@` (v-on)

:attr="value" — 對 HTML 屬性動態繫結值（v-bind:attr 的簡寫）
@event="handler" — 註冊事件監聽器（v-on:event 的簡寫）

<template>
    <!-- 動態屬性繫結 -->
    <img :src="imageUrl" :alt="imageAlt" />

    <!-- 事件處理器 -->
    <button @click="handleClick">點選</button>
    <form @submit.prevent="handleSubmit">...</form>
</template>

頁面元件的基本

Inertia 的頁面元件就是一般的 Vue 元件。可將從 Laravel controller 傳入的資料作為 props 接收。

Controller

// app/Http/Controllers/PostController.php
use Inertia\Inertia;
use App\Models\Post;

class PostController extends Controller
{
    public function index()
    {
        return Inertia::render('Posts/Index', [
            'posts' => Post::latest()->paginate(10),
        ]);
    }
}

Vue 頁面元件

<!-- resources/js/pages/Posts/Index.vue -->
<script setup>
import { Link } from '@inertiajs/vue3'

defineProps({
    posts: Object,
})
</script>

<template>
    <div>
        <h1>貼文列表</h1>
        <article v-for="post in posts.data" :key="post.id">
            <h2>
                <Link :href="`/posts/${post.id}`">{{ post.title }}</Link>
            </h2>
            <p>{{ post.created_at }}</p>
        </article>
    </div>
</template>

只要以 defineProps() 宣告 props，就能在模板中使用 controller 傳入的資料。不需要定義 REST API。

`Link` 元件

使用 @inertiajs/vue3 提供的 <Link> 元件時，頁面切換以 XHR 進行，可避免瀏覽器整頁重新載入。

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
    <!-- 基本連結 -->
    <Link href="/posts">貼文列表</Link>

    <!-- 使用 POST 方法的連結（如刪除） -->
    <Link href="/posts/1" method="delete" as="button" type="button">
        刪除
    </Link>

    <!-- 預先載入（hover 時預取資料） -->
    <Link href="/posts/1" preload>查看貼文</Link>
</template>

寫法與一般 <a> 標籤相同，但背後 Inertia 只會替換頁面元件，帶來如 SPA 般的操作體驗。

`Form` 元件

@inertiajs/vue3 提供的 <Form> 元件是入門套件認證畫面中所採用的表單送出推薦寫法。以 props 指定 action 與 method，用 v-slot 存取 errors 與 processing。

基本用法

<script setup>
import { Form } from '@inertiajs/vue3'
</script>

<template>
    <Form action="/posts" method="post" class="flex flex-col gap-4" v-slot="{ errors, processing }">
        <div>
            <label for="title">標題</label>
            <input id="title" name="title" type="text" required />
            <p v-if="errors.title" class="error">{{ errors.title }}</p>
        </div>

        <div>
            <label for="content">內文</label>
            <textarea id="content" name="content"></textarea>
            <p v-if="errors.content" class="error">{{ errors.content }}</p>
        </div>

        <button type="submit" :disabled="processing">
            {{ processing ? '傳送中...' : '發布' }}
        </button>
    </Form>
</template>

v-slot="{ errors, processing }" 是 Vue 的 scoped slot 語法，Form 元件會自動計算這些值並傳入。表單欄位不使用 v-model，而是使用 HTML 原生的 name 屬性，讓瀏覽器標準的表單資料蒐集機制正常運作。

入門套件的模式

入門套件使用 Wayfinder 以物件形式管理路由。store.form() 會回傳包含路由物件 action 與 method 的物件，用 v-bind spread 到 <Form>。

<script setup lang="ts">
import { Form } from '@inertiajs/vue3'
import { store } from '@/routes/login'
</script>

<template>
    <Form
        v-bind="store.form()"
        :reset-on-success="['password']"
        v-slot="{ errors, processing }"
        class="flex flex-col gap-6"
    >
        <!-- 表單內容 -->
    </Form>
</template>

指定為 reset-on-success 的欄位會在送出成功時自動重設。適用於密碼欄位等送出後想清空的欄位。

若不使用 Wayfinder，也可直接傳入 action="/login" 之類的 URL，效果相同。

`useForm` helper

表單處理使用 @inertiajs/vue3 的 useForm helper。可以簡潔地實作表單狀態管理、送出與驗證錯誤顯示。

Controller 側

// app/Http/Controllers/PostController.php
class PostController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'title'   => ['required', 'string', 'max:255'],
            'content' => ['required', 'string'],
        ]);

        Post::create($validated + ['user_id' => auth()->id()]);

        return redirect()->route('posts.index')
            ->with('success', '貼文已建立。');
    }
}

Vue 表單元件

<!-- resources/js/pages/Posts/Create.vue -->
<script setup>
import { useForm } from '@inertiajs/vue3'

const form = useForm({
    title: '',
    content: '',
})

function submit() {
    form.post('/posts')
}
</script>

<template>
    <form @submit.prevent="submit">
        <div>
            <label>標題</label>
            <input v-model="form.title" type="text" />
            <p v-if="form.errors.title" class="error">{{ form.errors.title }}</p>
        </div>

        <div>
            <label>內文</label>
            <textarea v-model="form.content"></textarea>
            <p v-if="form.errors.content" class="error">{{ form.errors.content }}</p>
        </div>

        <button type="submit" :disabled="form.processing">
            {{ form.processing ? '傳送中...' : '發布' }}
        </button>
    </form>
</template>

以下整理 useForm 回傳物件的主要屬性。

屬性 / 方法	說明
`form.data`	表單資料物件
`form.errors`	驗證錯誤（以欄位名存取）
`form.processing`	傳送中為 `true`（用於禁用按鈕）
`form.isDirty`	若已從初始值變更則為 `true`
`form.post(url)`	以 POST 請求送出
`form.put(url)`	以 PUT 請求送出（更新）
`form.delete(url)`	以 DELETE 請求送出
`form.reset()`	重設表單為初始值

當驗證錯誤返回時，useForm 會保留輸入內容並顯示錯誤。搭配 v-model 即可實現無縫的表單體驗。

共享資料（Shared Data）

所有頁面都需要的共通資料（登入使用者資訊、flash 訊息等），在 HandleInertiaRequests middleware 的 share() 方法中定義。

// app/Http/Middleware/HandleInertiaRequests.php
use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            'auth' => [
                'user' => $request->user()
                    ? $request->user()->only('id', 'name', 'email')
                    : null,
            ],
            'flash' => [
                'success' => $request->session()->get('success'),
                'error'   => $request->session()->get('error'),
            ],
        ]);
    }
}

在 Vue 元件中透過 usePage() 存取共享資料。

<script setup>
import { computed } from 'vue'
import { usePage } from '@inertiajs/vue3'

const page = usePage()

// 存取共享資料
const user = computed(() => page.props.auth.user)
const flash = computed(() => page.props.flash)
</script>

<template>
    <header>
        <span v-if="user">{{ user.name }}</span>
        <span v-else>訪客</span>
    </header>

    <div v-if="flash.success" class="alert-success">
        {{ flash.success }}
    </div>
</template>

共享資料會包含在所有請求中，因此建議只放最必要的資料。使用 fn() 進行 lazy 求值時，只在實際被存取時才會被求值。

Vue 3 反應式基礎

以下介紹以 Inertia × Vue 開發時，需要了解的 Vue 3 反應式 API。

`ref` — 原始型反應式值

<script setup>
import { ref } from 'vue'

const count = ref(0)
const isOpen = ref(false)

// 以 .value 存取（在模板中不需要）
count.value++
</script>

<template>
    <p>{{ count }}</p>
    <button @click="isOpen = !isOpen">切換</button>
</template>

`computed` — 計算屬性

<script setup>
import { ref, computed } from 'vue'

const posts = ref([])

const publishedPosts = computed(() =>
    posts.value.filter(post => post.published)
)
</script>

`onMounted` — 掛載後處理

<script setup>
import { onMounted } from 'vue'

onMounted(() => {
    console.log('元件已掛載')
})
</script>

總結

Vue.js 與 Laravel 相容性極佳，特別是透過 Inertia 的「現代單體式」架構下能發揮實力。

元素	角色
Laravel Controller	路由、資料取得、驗證
`Inertia::render()`	從 Controller 傳資料到 Vue 元件
Vue 頁面元件	接收 props 並渲染 UI
`useForm`	表單狀態管理、送出、錯誤顯示
`Link` 元件	不重新整頁的頁面切換
`usePage().props`	存取共享資料

使用 Inertia × Vue 可同時享有 Laravel 後端的簡潔性與 Vue 反應式 UI 兩者的優點。使用入門套件建立專案時，包含認證畫面在內都能立即開始開發。

Inertia.js 官方文件

Inertia v3 完整功能請參考官方文件。

​什麼是 Vue.js

​Options API 與 Composition API

​在 Laravel 中的定位

​歷史

​目前的主流方式：Inertia × Vue

​安裝設定

​透過入門套件（推薦）

​手動安裝

​目錄結構

​Vue 模板語法

​{{ }} — 變數展開

​v-if — 條件分支

​v-for — 清單渲染

​v-model — 雙向繫結

​: (v-bind) 與 @ (v-on)

​頁面元件的基本

​Controller

​Vue 頁面元件

​Link 元件

​Form 元件

​基本用法

​入門套件的模式

​useForm helper

​Controller 側

​Vue 表單元件

​共享資料（Shared Data）

​Vue 3 反應式基礎

​ref — 原始型反應式值

​computed — 計算屬性

​onMounted — 掛載後處理

​總結

Inertia.js 官方文件

什麼是 Vue.js

Options API 與 Composition API

在 Laravel 中的定位

歷史

目前的主流方式：Inertia × Vue

安裝設定

透過入門套件（推薦）

手動安裝

目錄結構

Vue 模板語法

`{{ }}` — 變數展開

`v-if` — 條件分支

`v-for` — 清單渲染

`v-model` — 雙向繫結

`:` (v-bind) 與 `@` (v-on)

頁面元件的基本

Controller

Vue 頁面元件

`Link` 元件

`Form` 元件

基本用法

入門套件的模式

`useForm` helper

Controller 側

Vue 表單元件

共享資料（Shared Data）

Vue 3 反應式基礎

`ref` — 原始型反應式值

`computed` — 計算屬性

`onMounted` — 掛載後處理

總結