Thiết lập phía client

Bạn đang xem tài liệu Inertia.js v2. Inertia.js v3 đã được phát hành và hiện là phiên bản mặc định. Hãy xem hướng dẫn nâng cấp để bắt đầu.

Sau khi đã cấu hình framework phía máy chủ, bạn cần thiết lập framework phía client. Inertia hiện hỗ trợ React, Vue và Svelte.

Laravel Starter Kit

Các starter kit của Laravel cung cấp scaffold sẵn dùng cho ứng dụng Inertia mới.Đây là cách nhanh nhất để bắt đầu dự án Inertia mới bằng Laravel và Vue hoặc React. Tuy nhiên, nếu muốn cài Inertia thủ công vào ứng dụng, hãy xem tài liệu bên dưới.

Điều kiện tiên quyết

Trước khi cài Inertia, bạn cần cài và cấu hình framework phía client cùng Vite plugin tương ứng. Có thể bỏ qua phần này nếu ứng dụng đã thiết lập sẵn.

npm install vue @vitejs/plugin-vue

npm install react react-dom @vitejs/plugin-react

npm install svelte @sveltejs/vite-plugin-svelte

Sau đó, thêm plugin của framework vào file vite.config.js.

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

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            refresh: true,
        }),
        vue(),
    ],
})

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

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.jsx'],
            refresh: true,
        }),
        react(),
    ],
})

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            refresh: true,
        }),
        svelte(),
    ],
})

Để biết thêm về cấu hình các plugin này, hãy xem tài liệu Vite của Laravel.

Cài đặt

Install dependencies

Cài adapter phía client của Inertia tương ứng với framework bạn lựa chọn.

npm install @inertiajs/vue3

npm install @inertiajs/react

npm install @inertiajs/svelte

Initialize the Inertia app

Tiếp theo, cập nhật file JavaScript chính để khởi động ứng dụng Inertia. Để làm việc này, chúng ta sẽ khởi tạo framework phía client với component Inertia cơ sở.

import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

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

import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true })
        return pages[`./Pages/${name}.jsx`]
    },
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />)
    },
})

import { createInertiaApp } from '@inertiajs/svelte'
import { mount } from 'svelte'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.svelte', { eager: true })
        return pages[`./Pages/${name}.svelte`]
    },
    setup({ el, App, props }) {
        mount(App, { target: el, props })
    },
})

Callback setup nhận mọi thứ cần thiết để khởi tạo framework phía client, bao gồm root component App của Inertia.

Cấu hình giá trị mặc định

Bạn có thể truyền object defaults vào createInertiaApp() để cấu hình giá trị mặc định cho nhiều tính năng. Không cần truyền mặc định cho mọi key, chỉ cần những key bạn muốn điều chỉnh.

createInertiaApp({
    // ...
    defaults: {
        form: {
            recentlySuccessfulDuration: 5000,
        },
        prefetch: {
            cacheFor: "1m",
            hoverDelay: 150,
        },
        visitOptions: (href, options) => {
            return {
                headers: {
                    ...options.headers,
                    "X-Custom-Header": "value",
                },
            };
        },
    },
});

Callback visitOptions nhận URL đích và visit options hiện tại, sau đó trả object chứa các option cần ghi đè. Để biết chi tiết các cấu hình có sẵn, xem tài liệu form, prefetch và manual visit.

Cập nhật cấu hình khi runtime

Bạn cũng có thể cập nhật giá trị cấu hình khi runtime bằng instance config được export. Điều này đặc biệt hữu ích khi cần điều chỉnh setting dựa trên preference của người dùng hoặc state ứng dụng.

import { config } from '@inertiajs/vue3'

// Set a single value using dot notation...
config.set('form.recentlySuccessfulDuration', 1000)
config.set('prefetch.cacheFor', '5m')

// Set multiple values at once...
config.set({
    'form.recentlySuccessfulDuration': 1000,
    'prefetch.cacheFor': '5m',
})

import { config } from '@inertiajs/react'

// Set a single value using dot notation...
config.set('form.recentlySuccessfulDuration', 1000)
config.set('prefetch.cacheFor', '5m')

// Set multiple values at once...
config.set({
    'form.recentlySuccessfulDuration': 1000,
    'prefetch.cacheFor': '5m',
})

// Get a configuration value...
const duration = config.get('form.recentlySuccessfulDuration')

import { config } from '@inertiajs/svelte'

// Set a single value using dot notation...
config.set('form.recentlySuccessfulDuration', 1000)
config.set('prefetch.cacheFor', '5m')

// Set multiple values at once...
config.set({
    'form.recentlySuccessfulDuration': 1000,
    'prefetch.cacheFor': '5m',
})

// Get a configuration value...
const duration = config.get('form.recentlySuccessfulDuration')

Resolve component

Callback resolve cho Inertia biết cách tải một page component. Nó nhận tên trang (chuỗi) và trả về module page component. Cách triển khai callback này phụ thuộc vào bundler bạn đang sử dụng (Vite hoặc Webpack).

// Vite
resolve: name => {
    const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
    return pages[`./Pages/${name}.vue`]
},

// Webpack
resolve: name => require(`./Pages/${name}`),

// Vite
resolve: name => {
    const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true })
    return pages[`./Pages/${name}.jsx`]
},

// Webpack
resolve: name => require(`./Pages/${name}`),

// Vite
resolve: name => {
    const pages = import.meta.glob('./Pages/**/*.svelte', { eager: true })
    return pages[`./Pages/${name}.svelte`]
},

// Webpack
resolve: name => require(`./Pages/${name}.svelte`),

Mặc định, chúng tôi khuyến nghị eager load component để tạo một JavaScript bundle duy nhất. Nếu muốn lazy-load component, xem tài liệu code splitting. Package laravel-vite-plugin cũng cung cấp helper resolvePageComponent có thể dùng để resolve page component.

import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

resolve: name => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),

import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

resolve: name => resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx')),

import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

resolve: name => resolvePageComponent(`./Pages/${name}.svelte`, import.meta.glob('./Pages/**/*.svelte')),

Định nghĩa root element

Mặc định, Inertia giả định root template của ứng dụng có root element với id là app. Nếu root element của ứng dụng có id khác, bạn có thể cung cấp nó bằng thuộc tính id.

createInertiaApp({
    id: 'my-app',
    // ...
})

Nếu thay đổi id của root element, hãy nhớ cập nhật cả phía máy chủ.

Phần tử script cho dữ liệu trang

Mặc định, Inertia lưu dữ liệu trang ban đầu trong attribute data-page trên root element. Bạn có thể cấu hình Inertia dùng phần tử <script type="application/json"> thay thế; cách này nhanh hơn một chút và dễ kiểm tra hơn trong devtools của trình duyệt.

createInertiaApp({
    // ...
    defaults: {
        future: {
            useScriptElementForInitialPage: true,
        },
    },
})

Nếu dùng server-side rendering, hãy nhớ cập nhật cả SSR entry point. Người dùng Laravel cũng nên đặt config inertia.use_script_element_for_initial_page thành true để Blade directive @inertia xuất ra phần tử script.

Tài liệu chính thức

Bài dịch này được đối chiếu từ tài liệu Inertia.js v2 chính thức. Nếu có khác biệt do phiên bản hoặc cập nhật mới, hãy ưu tiên tài liệu chính thức làm nguồn tham chiếu.

Bắt đầu

Cài đặt

Khái niệm cốt lõi

Kiến thức cơ bản

Dữ liệu & Props

Bảo mật

Nâng cao

Laravel Starter Kit

Điều kiện tiên quyết

Cài đặt

Cấu hình giá trị mặc định

Cập nhật cấu hình khi runtime

Resolve component

Định nghĩa root element

Phần tử script cho dữ liệu trang

Tài liệu chính thức

Laravel Starter Kit

​Điều kiện tiên quyết

​Cài đặt

​Cấu hình giá trị mặc định

​Cập nhật cấu hình khi runtime

​Resolve component

​Định nghĩa root element

​Phần tử script cho dữ liệu trang

​Tài liệu chính thức

Điều kiện tiên quyết

Cài đặt

Cấu hình giá trị mặc định

Cập nhật cấu hình khi runtime

Resolve component

Định nghĩa root element

Phần tử script cho dữ liệu trang

Tài liệu chính thức