inertia-modal-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inertia Modal Development

Inertia 模态框开发

Overview

概述

Use inertiaui/modal to open any Laravel route in a Modal or Slideover without modifying existing routes or controllers. Works with both React and Vue, supports nested modals, prefetching, local modals, headless mode, and TypeScript.

使用inertiaui/modal无需修改现有路由或控制器，即可在模态框或侧边滑出面板中打开任意Laravel路由。该工具兼容React和Vue，支持嵌套模态框、预加载、本地模态框、无头模式以及TypeScript。

When to Activate

适用场景

Activate when working with modals or slideovers in a Laravel + Inertia.js application.

Activate when code references

ModalLink

Modal

HeadlessModal

ModalRoot

useModal

useModalStack

visitModal

, or

Inertia::modal()

Activate when the user wants to open a route in a modal, configure modal behavior, use prefetching, set up nested modals, or communicate between modals.

Activate when imports reference

@inertiaui/modal-vue

@inertiaui/modal-react

当在Laravel + Inertia.js应用中处理模态框或侧边滑出面板时启用。

当代码引用

ModalLink

、

Modal

、

HeadlessModal

、

ModalRoot

、

useModal

、

useModalStack

、

visitModal

或

Inertia::modal()

时启用。

当用户希望在模态框中打开路由、配置模态框行为、使用预加载、设置嵌套模态框或实现模态框间通信时启用。

当导入语句引用

@inertiaui/modal-vue

或

@inertiaui/modal-react

时启用。

Scope

适用范围

In scope: modal routes, ModalLink, Modal component, configuration, prefetching, local modals, nested modals, event bus, reload props, deferred props, headless mode, base route/URL, styling.
Out of scope: general Inertia.js routing without modals, non-Laravel backends.

包含：模态框路由、ModalLink、Modal组件、配置、预加载、本地模态框、嵌套模态框、事件总线、重载属性、延迟属性、无头模式、基础路由/URL、样式。
不包含：无模态框的常规Inertia.js路由、非Laravel后端。

Workflow

工作流程

Identify the task (opening a modal, configuring behavior, setting up communication, etc.).
Read
```
references/inertia-modal-guide.md
```
and focus on the relevant section.
Apply the patterns from the reference, using the correct framework (React or Vue).

确定任务（打开模态框、配置行为、设置通信等）。
阅读
```
references/inertia-modal-guide.md
```
并聚焦相关章节。
参考文档中的模式，使用对应框架（React或Vue）实现。

Core Concepts

核心概念

Backend: Opening a Route as a Modal

后端：以模态框形式打开路由

Use

Inertia::modal()

instead of

Inertia::render()

in your controller:

php

return Inertia::modal('EditUser', [
    'user' => $user,
    'roles' => Role::pluck('name', 'id'),
]);

With a base route (enables URL changes and browser history):

php

return Inertia::modal('EditUser', ['user' => $user])
    ->baseRoute('users.index');

在控制器中使用

Inertia::modal()

代替

Inertia::render()

：

php

return Inertia::modal('EditUser', [
    'user' => $user,
    'roles' => Role::pluck('name', 'id'),
]);

配置基础路由（支持URL变更和浏览器历史记录）：

php

return Inertia::modal('EditUser', ['user' => $user])
    ->baseRoute('users.index');

Frontend: App Setup

前端：应用配置

Use

renderApp

in your

app.js

app.jsx

// Vue
import { renderApp } from '@inertiaui/modal-vue'
createInertiaApp({
    setup({ el, App, props, plugin }) {
        createApp({ render: renderApp(App, props) })
            .use(plugin)
            .mount(el)
    }
})

// React
import { renderApp } from '@inertiaui/modal-react'
createInertiaApp({
    setup({ el, App, props }) {
        const root = createRoot(el);
        root.render(renderApp(App, props));
    }
});

在

app.js

app.jsx

中使用

renderApp

：

// Vue
import { renderApp } from '@inertiaui/modal-vue'
createInertiaApp({
    setup({ el, App, props, plugin }) {
        createApp({ render: renderApp(App, props) })
            .use(plugin)
            .mount(el)
    }
})

// React
import { renderApp } from '@inertiaui/modal-react'
createInertiaApp({
    setup({ el, App, props }) {
        const root = createRoot(el);
        root.render(renderApp(App, props));
    }
});

Frontend: ModalLink Component

前端：ModalLink组件

vue

<!-- Vue -->
<ModalLink href="/users/create">Create User</ModalLink>

jsx

// React
<ModalLink href="/users/create">Create User</ModalLink>

vue

<!-- Vue -->
<ModalLink href="/users/create">Create User</ModalLink>

jsx

// React
<ModalLink href="/users/create">Create User</ModalLink>

Frontend: Modal Component

前端：Modal组件

vue

<!-- Vue -->
<Modal>
    <h1>Create User</h1>
    <form><!-- ... --></form>
</Modal>

jsx

// React
<Modal>
    <h1>Create User</h1>
    <form>{/* ... */}</form>
</Modal>

vue

<!-- Vue -->
<Modal>
    <h1>Create User</h1>
    <form><!-- ... --></form>
</Modal>

jsx

// React
<Modal>
    <h1>Create User</h1>
    <form>{/* ... */}</form>
</Modal>

Programmatic Usage

程序化调用

// Vue
import { visitModal } from '@inertiaui/modal-vue'
visitModal('/users/create')

// React
const { visitModal } = useModalStack()
visitModal('/users/create')

// Vue
import { visitModal } from '@inertiaui/modal-vue'
visitModal('/users/create')

// React
const { visitModal } = useModalStack()
visitModal('/users/create')

Configuration

配置项

import { putConfig } from '@inertiaui/modal-vue' // or modal-react

putConfig({
    type: 'modal',
    navigate: false,
    useNativeDialog: true,
    appElement: '#app',
    modal: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: '2xl',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white rounded',
        position: 'center',
    },
    slideover: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: 'md',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white min-h-screen',
        position: 'right',
    },
})

import { putConfig } from '@inertiaui/modal-vue' // or modal-react

putConfig({
    type: 'modal',
    navigate: false,
    useNativeDialog: true,
    appElement: '#app',
    modal: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: '2xl',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white rounded',
        position: 'center',
    },
    slideover: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: 'md',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white min-h-screen',
        position: 'right',
    },
})

Do and Don't

注意事项

Do:

Always use
```
Inertia::modal()
```
(not
```
Inertia::render()
```
) when opening routes as modals.
Always call
```
renderApp
```
or set up
```
ModalRoot
```
/
```
ModalStackProvider
```
in your app entry point.
Use the
```
navigate
```
prop on
```
ModalLink
```
(or global config) when you want URL changes and browser history.
Use
```
closeOnClickOutside
```
to disable only backdrop clicks; use
```
closeExplicitly
```
to disable both backdrop clicks and Esc key.
Use Axios for form submissions in nested modals to avoid closing the entire stack.
Import
```
Deferred
```
and
```
WhenVisible
```
from the modal package (not Inertia) when used inside modals.

Don't:

Don't forget to set up the
```
renderApp
```
helper or
```
ModalRoot
```
component — modals won't work without it.
Don't use
```
Inertia::render()
```
for modal routes — use
```
Inertia::modal()
```
.
Don't use
```
router.post()
```
(Inertia router) in nested modals — it navigates to the base route and closes all modals. Use Axios instead.
Don't import
```
Deferred
```
or
```
WhenVisible
```
from
```
@inertiajs/vue3
```
or
```
@inertiajs/react
```
when inside a modal — use the modal package's versions.

Don't reference conversion names in

closeOnClickOutside

and

closeExplicitly

together —

closeExplicitly

supersedes

closeOnClickOutside

需要遵循的操作：

当以模态框形式打开路由时，务必使用
```
Inertia::modal()
```
（而非
```
Inertia::render()
```
）。
务必在应用入口文件中调用
```
renderApp
```
或配置
```
ModalRoot
```
/
```
ModalStackProvider
```
。
当需要修改URL和浏览器历史记录时，在
```
ModalLink
```
上使用
```
navigate
```
属性（或全局配置）。
使用
```
closeOnClickOutside
```
仅禁用点击背景关闭；使用
```
closeExplicitly
```
同时禁用点击背景和Esc键关闭。
在嵌套模态框中使用Axios提交表单，避免关闭整个模态框栈。
在模态框内使用
```
Deferred
```
和
```
WhenVisible
```
时，从模态框包中导入（而非Inertia核心包）。

禁止的操作：

不要忘记设置
```
renderApp
```
辅助函数或
```
ModalRoot
```
组件——没有它们模态框将无法工作。
不要为模态框路由使用
```
Inertia::render()
```
——请使用
```
Inertia::modal()
```
。
不要在嵌套模态框中使用
```
router.post()
```
（Inertia路由）——这会导航到基础路由并关闭所有模态框，请改用Axios。
在模态框内不要从
```
@inertiajs/vue3
```
或
```
@inertiajs/react
```
导入
```
Deferred
```
或
```
WhenVisible
```
——请使用模态框包中的版本。

不要同时设置

closeOnClickOutside

和

closeExplicitly

——

closeExplicitly

会覆盖

closeOnClickOutside

的设置。

References

参考资料

```
references/inertia-modal-guide.md
```

```
references/inertia-modal-guide.md
```