Layouts

Hầu hết ứng dụng chia sẻ các phần tử UI chung giữa nhiều trang như thanh điều hướng chính, sidebar hoặc footer. Layout component cho phép bạn định nghĩa UI dùng chung một lần rồi tự động bao bọc các trang bằng nó.

Tạo layout

Layout là component tiêu chuẩn nhận nội dung con. Không có gì đặc thù Inertia trong bản thân layout.

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

<template>
    <main>
        <header>
            <Link href="/">Home</Link>
            <Link href="/about">About</Link>
            <Link href="/contact">Contact</Link>
        </header>
        <article>
            <slot />
        </article>
    </main>
</template>

import { Link } from "@inertiajs/react"

export default function Layout({ children }) {
    return (
        <main>
            <header>
                <Link href="/">Home</Link>
                <Link href="/about">About</Link>
                <Link href="/contact">Contact</Link>
            </header>
            <article>{children}</article>
        </main>
    )
}

<script>
    import { inertia } from '@inertiajs/svelte'

    let { children } = $props()
</script>

<main>
    <header>
        <a use:inertia href="/">Home</a>
        <a use:inertia href="/about">About</a>
        <a use:inertia href="/contact">Contact</a>
    </header>
    <article>
        {@render children()}
    </article>
</main>

Bạn có thể dùng layout bằng cách trực tiếp bao nội dung trang bằng nó. Tuy nhiên cách này buộc instance layout bị hủy và tạo lại giữa các visit.

<script setup>
import Layout from './Layout'

defineProps({ user: Object })
</script>

<template>
    <Layout>
        <h1>Welcome</h1>
        <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
    </Layout>
</template>

import Layout from './Layout'

export default function Welcome({ user }) {
    return (
        <Layout>
            <h1>Welcome</h1>
            <p>Hello {user.name}, welcome to your first Inertia app!</p>
        </Layout>
    )
}

<script>
    import Layout from './Layout.svelte'

    let { user } = $props()
</script>

<Layout>
    <h1>Welcome</h1>
    <p>Hello {user.name}, welcome to your first Inertia app!</p>
</Layout>

Layout duy trì xuyên suốt

Bao page bằng layout dưới dạng child component vẫn hoạt động, nhưng đồng nghĩa layout bị hủy và tạo lại ở mọi visit. Điều này ngăn duy trì layout state qua các lần điều hướng, chẳng hạn audio player cần tiếp tục phát hoặc sidebar cần giữ vị trí cuộn. Persistent layout giải quyết vấn đề này bằng cách cho Inertia biết layout nào được dùng cho page. Inertia quản lý instance layout riêng và giữ nó sống giữa các visit.

<script>
import Layout from './Layout'

export default {
    layout: Layout,
}
</script>

<script setup>
defineProps({ user: Object })
</script>

<template>
    <h1>Welcome</h1>
    <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
</template>

import Layout from './Layout'

const Welcome = ({ user }) => {
    return (
        <>
            <h1>Welcome</h1>
            <p>Hello {user.name}, welcome to your first Inertia app!</p>
        </>
    )
}

Welcome.layout = (page) => <Layout>{page}</Layout>

export default Welcome

<script module>
    export { default as layout } from './Layout.svelte'
</script>

<script>
    let { user } = $props()
</script>

<h1>Welcome</h1>
<p>Hello {user.name}, welcome to your first Inertia app!</p>

Nested layouts

Bạn có thể tạo bố cục layout phức tạp hơn bằng nested layout. Truyền một mảng layout component để bao page qua nhiều lớp.

<script>
import SiteLayout from './SiteLayout'
import NestedLayout from './NestedLayout'

export default {
    layout: [SiteLayout, NestedLayout],
}
</script>

<script setup>
defineProps({ user: Object })
</script>

<template>
    <h1>Welcome</h1>
    <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
</template>

import SiteLayout from './SiteLayout'
import NestedLayout from './NestedLayout'

const Welcome = ({ user }) => {
    return (
        <>
            <h1>Welcome</h1>
            <p>Hello {user.name}, welcome to your first Inertia app!</p>
        </>
    )
}

Welcome.layout = [SiteLayout, NestedLayout]

export default Welcome

<script module>
    import SiteLayout from './SiteLayout.svelte'
    import NestedLayout from './NestedLayout.svelte'

    export const layout = [SiteLayout, NestedLayout]
</script>

<script>
    let { user } = $props()
</script>

<h1>Welcome</h1>
<p>Hello {user.name}, welcome to your first Inertia app!</p>

Layout mặc định

Tùy chọn layout trong createInertiaApp cho phép định nghĩa layout mặc định cho mọi page, tránh phải khai báo ở từng page. Layout theo từng page luôn ưu tiên hơn layout mặc định.

import Layout from './Layout'

createInertiaApp({
    layout: () => Layout,
    // ...
})

Bạn cũng có thể trả layout có điều kiện dựa trên tên page. Ví dụ có thể muốn loại các public page khỏi layout mặc định.

import Layout from './Layout'

createInertiaApp({
    layout: (name) => {
        if (name.startsWith('Public/')) {
            return null
        }

        return Layout
    },
    // ...
})

Full page object cũng có sẵn dưới dạng đối số thứ hai, cho phép truy cập URL, props và metadata khác của page. Callback layout hỗ trợ mọi định dạng layout, bao gồm mảng cho nested layouts, object có tên cho named layouts, và tuple cho static props.

Sử dụng Resolve callback

Bạn cũng có thể đặt layout mặc định bên trong callback resolve bằng cách mutate page component đã resolve. Callback nhận tên component và full page object, hữu ích khi cần áp dụng layout có điều kiện dựa trên page data.

import Layout from './Layout'

createInertiaApp({
    resolve: (name) => {
        const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
        let page = pages[`./Pages/${name}.vue`]
        page.default.layout = page.default.layout || Layout
        return page
    },
    // ...
})

import Layout from './Layout'

createInertiaApp({
    resolve: (name) => {
        const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true })
        let page = pages[`./Pages/${name}.jsx`]
        page.default.layout = page.default.layout || ((page) => <Layout>{page}</Layout>)
        return page
    },
    // ...
})

import Layout from './Layout'

createInertiaApp({
    resolve: (name) => {
        const pages = import.meta.glob('./Pages/**/*.svelte', { eager: true })
        let page = pages[`./Pages/${name}.svelte`]
        return { default: page.default, layout: page.layout || Layout }
    },
    // ...
})

Layout props

Persistent layout thường cần dữ liệu động từ page hiện tại, chẳng hạn page title, navigation item đang active hoặc trạng thái bật/tắt sidebar. Layout prop cung cấp cách định nghĩa giá trị mặc định trong layout và override từ bất kỳ page nào.

Định nghĩa giá trị mặc định

Layout prop được định nghĩa như component prop thông thường với giá trị mặc định.

<script setup>
const props = withDefaults(defineProps<{
    title?: string
    showSidebar?: boolean
}>(), {
    title: 'My App',
    showSidebar: true,
})
</script>

<template>
    <header>{{ title }}</header>
    <aside v-if="showSidebar">Sidebar</aside>
    <main>
        <slot />
    </main>
</template>

export default function Layout({ title = 'My App', showSidebar = true, children }) {
    return (
        <>
            <header>{title}</header>
            {showSidebar && <aside>Sidebar</aside>}
            <main>{children}</main>
        </>
    )
}

<script>
let { title = 'My App', showSidebar = true, children } = $props()
</script>

<header>{title}</header>
{#if showSidebar}
    <aside>Sidebar</aside>
{/if}
<main>
    {@render children()}
</main>

Static props

Bạn có thể truyền static prop trực tiếp trong định nghĩa persistent layout bằng tuple. Các prop này được đặt một lần khi layout được định nghĩa và không thay đổi giữa các lần điều hướng page.

<script setup>
import Layout from './Layout'

defineProps({ user: Object })
defineOptions({
    layout: [Layout, { title: 'Dashboard' }],
})
</script>

<template>
    <h1>Dashboard</h1>
</template>

import Layout from './Layout'

const Dashboard = ({ user }) => {
    return <h1>Dashboard</h1>
}

Dashboard.layout = [Layout, { title: 'Dashboard' }]

export default Dashboard

<script module>
    import Layout from './Layout.svelte'

    export const layout = [Layout, { title: 'Dashboard' }]
</script>

<script>
    let { user } = $props()
</script>

<h1>Dashboard</h1>

Callback props

Đôi khi layout prop cần được suy ra từ prop của page hiện tại. Callback function nhận page props và trả về layout definition với static prop đã tính toán.

<script setup>
import Layout from './Layout'

defineOptions({
    layout: (props) => [Layout, { title: 'Profile: ' + props.auth.user.name }],
})
</script>

<template>
    <h1>Profile</h1>
</template>

import Layout from './Layout'

const Profile = () => {
    return <h1>Profile</h1>
}

Profile.layout = (props) => [Layout, { title: 'Profile: ' + props.auth.user.name }]

export default Profile

<script module>
    import Layout from './Layout.svelte'

    export const layout = (props) => [Layout, { title: 'Profile: ' + props.auth.user.name }]
</script>

<h1>Profile</h1>

Callback nhận props của page và có thể trả bất kỳ định dạng layout hợp lệ nào: một component, tuple kèm static props, mảng cho nested layouts hoặc named layout object. Người dùng TypeScript có thể dùng type LayoutCallback để đảm bảo type safety.

Chỉ trả props

Khi default layout được cấu hình trong createInertiaApp, callback có thể trả plain props object thay vì full layout definition. Inertia tự động dùng default layout và merge các prop được trả vào layout đó.

<script setup>
defineOptions({
    layout: (props) => ({ title: 'Profile: ' + props.auth.user.name, showSidebar: false }),
})
</script>

<template>
    <h1>Profile</h1>
</template>

const Profile = () => {
    return <h1>Profile</h1>
}

Profile.layout = (props) => ({ title: 'Profile: ' + props.auth.user.name, showSidebar: false })

export default Profile

<script module>
    export const layout = (props) => ({
        title: 'Profile: ' + props.auth.user.name,
        showSidebar: false,
    })
</script>

<h1>Profile</h1>

Bạn cũng có thể dùng static object khi prop không phụ thuộc page data.

Dashboard.layout = { title: 'Dashboard', showSidebar: true }

Dynamic props

Bạn cũng có thể cập nhật layout prop động từ bất kỳ page component nào bằng hàm setLayoutProps. Người dùng TypeScript có thể khai báo type cho các prop này trên toàn cục.

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

setLayoutProps({
    title: 'Dashboard',
    showSidebar: false,
})
</script>

<template>
    <h1>Dashboard</h1>
</template>

import { setLayoutProps } from '@inertiajs/react'

export default function Dashboard() {
    setLayoutProps({
        title: 'Dashboard',
        showSidebar: false,
    })

    return <h1>Dashboard</h1>
}

<script>
import { setLayoutProps } from '@inertiajs/svelte'

setLayoutProps({
    title: 'Dashboard',
    showSidebar: false,
})
</script>

<h1>Dashboard</h1>

Nhắm đến named layouts

Nested layouts cũng có thể được định nghĩa dưới dạng named object thay vì mảng, cho phép nhắm tới layout cụ thể bằng prop.

<script>
import AppLayout from './AppLayout'
import ContentLayout from './ContentLayout'

export default {
    layout: {
        app: AppLayout,
        content: ContentLayout,
    },
}
</script>

import AppLayout from './AppLayout'
import ContentLayout from './ContentLayout'

Dashboard.layout = {
    app: AppLayout,
    content: ContentLayout,
}

<script module>
    import AppLayout from './AppLayout.svelte'
    import ContentLayout from './ContentLayout.svelte'

    export const layout = {
        app: AppLayout,
        content: ContentLayout,
    }
</script>

Bạn có thể nhắm tới named layout cụ thể bằng cách truyền tên layout làm đối số đầu tiên của setLayoutProps.

import { setLayoutProps } from '@inertiajs/vue3'

setLayoutProps('sidebar', {
    collapsed: true,
})

import { setLayoutProps } from '@inertiajs/react'

setLayoutProps('sidebar', {
    collapsed: true,
})

import { setLayoutProps } from '@inertiajs/svelte'

setLayoutProps('sidebar', {
    collapsed: true,
})

Nested layouts và named layout cũng có thể bao gồm static prop bằng cú pháp tuple.

// Nested layouts with static props
Dashboard.layout = [
    [AppLayout, { title: 'Dashboard' }],
    [ContentLayout, { padding: 'sm' }],
]

// Named layouts with static props
Dashboard.layout = {
    app: [AppLayout, { theme: 'dark' }],
    content: [ContentLayout, { padding: 'sm' }],
}

Thứ tự ưu tiên khi merge

Layout prop được resolve từ nhiều nguồn theo thứ tự ưu tiên sau, từ cao xuống thấp:

Dynamic props - được đặt qua setLayoutProps()
Static props - được định nghĩa trong persistent layout definition (bao gồm callback props)
Defaults - được khai báo là giá trị mặc định trên prop của layout component

Tự động reset khi điều hướng

Dynamic layout prop tự động reset khi điều hướng tới page mới (trừ khi bật preserveState). Điều này đảm bảo mỗi page bắt đầu với trạng thái sạch và chỉ áp dụng các layout prop được page đó thiết lập rõ ràng.

Reset props

Bạn cũng có thể reset thủ công toàn bộ dynamic layout prop bằng resetLayoutProps.

import { resetLayoutProps } from '@inertiajs/vue3'

resetLayoutProps()

import { resetLayoutProps } from '@inertiajs/react'

resetLayoutProps()

import { resetLayoutProps } from '@inertiajs/svelte'

resetLayoutProps()

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 v3 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

Tạo layout

Layout duy trì xuyên suốt

Nested layouts

Layout mặc định

Sử dụng Resolve callback

Layout props

Định nghĩa giá trị mặc định

Static props

Callback props

Chỉ trả props

Dynamic props

Nhắm đến named layouts

Thứ tự ưu tiên khi merge

Tự động reset khi điều hướng

Reset props

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

​Tạo layout

​Layout duy trì xuyên suốt

​Nested layouts

​Layout mặc định

​Sử dụng Resolve callback

​Layout props

​Định nghĩa giá trị mặc định

​Static props

​Callback props

​Chỉ trả props

​Dynamic props

​Nhắm đến named layouts

​Thứ tự ưu tiên khi merge

​Tự động reset khi điều hướng

​Reset props

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

Tạo layout

Layout duy trì xuyên suốt

Nested layouts

Layout mặc định

Sử dụng Resolve callback

Layout props

Định nghĩa giá trị mặc định

Static props

Callback props

Chỉ trả props

Dynamic props

Nhắm đến named layouts

Thứ tự ưu tiên khi merge

Tự động reset khi điều hướng

Reset props

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