inertia-modal-development

Inertia Modal 开发

概述

使用 inertiaui/modal，无需修改现有路由或控制器，即可在 Modal 或 Slideover 中打开任意 Laravel 路由。兼容 React 和 Vue，并支持嵌套 Modal、预取、本地 Modal、无头模式和 TypeScript。

何时启用

• 在 Laravel + Inertia.js 应用中处理 Modal 或 Slideover 时启用。
• 代码引用 ModalLink、Modal、HeadlessModal、ModalRoot、useModal、useModalStack、visitModal 或 Inertia::modal() 时启用。
• 用户希望在 Modal 中打开路由、配置 Modal 行为、使用预取、设置嵌套 Modal 或在 Modal 之间通信时启用。
• 导入语句引用 @inertiaui/modal-vue 或 @inertiaui/modal-react 时启用。

范围

• 范围内：Modal 路由、ModalLink、Modal 组件、配置、预取、本地 Modal、嵌套 Modal、事件总线、重新加载 props、延迟 props、无头模式、基础路由/URL、样式。
• 范围外：不涉及 Modal 的通用 Inertia.js 路由、非 Laravel 后端。

工作流

1. 确认任务类型（打开 Modal、配置行为、设置通信等）。
2. 阅读 references/inertia-modal-guide.md，重点关注相关章节。
3. 使用正确的框架（React 或 Vue）应用参考文档中的模式。

核心概念

后端：将路由作为 Modal 打开

在控制器中使用 Inertia::modal()，而不是 Inertia::render()：

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

使用基础路由（启用 URL 更改和浏览器历史记录）：

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

前端：应用设置

在 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));
    }
});

前端：ModalLink 组件

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

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

前端：Modal 组件

<Modal>
    <h1>Create User</h1>
    <form></form>
</Modal>

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

以编程方式使用

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

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

配置

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',
    },
})

应做与避免事项

应做：

• 将路由作为 Modal 打开时，始终使用 Inertia::modal()（不要使用 Inertia::render()）。
• 始终调用 renderApp，或在应用入口点设置 ModalRoot/ModalStackProvider。
• 需要更改 URL 并保留浏览器历史记录时，在 ModalLink 上使用 navigate 属性（或使用全局配置）。
• 使用 closeOnClickOutside 仅禁用点击背景关闭；使用 closeExplicitly 禁用点击背景和 Esc 键关闭。
• 在嵌套 Modal 中使用 Axios 提交表单，以避免关闭整个堆栈。
• 在 Modal 内使用时，从 Modal 包（而非 Inertia）导入 Deferred 和 WhenVisible。

避免：

• 不要忘记设置 renderApp 辅助函数或 ModalRoot 组件，否则 Modal 无法正常工作。
• Modal 路由不要使用 Inertia::render()，应使用 Inertia::modal()。
• 在嵌套 Modal 中不要使用 router.post()（Inertia router），它会导航到基础路由并关闭所有 Modal。请改用 Axios。
• 在 Modal 内不要从 @inertiajs/vue3 或 @inertiajs/react 导入 Deferred 或 WhenVisible，请使用 Modal 包提供的版本。
• 不要在 closeOnClickOutside 和 closeExplicitly 中同时引用转换名称；closeExplicitly 的优先级高于 closeOnClickOutside。

参考资料

• references/inertia-modal-guide.md