# Rails 的本机对话框模式使用原生 HTML `` 元素以及 Turbo Frames 和 Stimulus 构建可访问的现代对话框 UI。不需要 JavaScript 框架或繁重的库。 ## 何时使用此技能 * 构建表单、确认或内容的模式对话框 * 创建 toast/警报通知 * 实现确认对话框（删除、破坏性操作） * 任何需要焦点管理和可访问性的覆盖 UI ## 为什么使用原生 ``？特色 |本机 `` |自定义模态 ---|---|--- 焦点捕捉 |内置|手动实施 ESC关闭|内置|手动实施背景|内置 (`::backdrop`) |手动叠加无障碍 |本机 `role="dialog"` |手动 ARIA 顶层|自动（首先是所有内容）| z 索引之战滚动锁 |自动|手动`溢出：隐藏` ## 零 JavaScript 确认对话框（推荐）现代浏览器支持用于声明性对话框控制的 **Invoker Commands API** - 无需 JavaScript。有关完整示例，请参阅 [references/zero-js-patterns.md]()。 ### 快速参考 <%= button_tag "删除", 命令: "delete-#{post.id}", 命令: "show-modal" %>

删除“<%= post.title %>”？

<%= button_to“删除”，帖子，方法：:delete %> ### 关键属性属性 |目的 ---|--- `commandfor="id"` |引用对话框来控制 `命令=“显示模态”` |作为模态打开（背景、焦点陷阱） `命令=“关闭”` |关闭对话框 `closeby="任何"` |启用背景单击和 ESC 关闭 ### 何时使用 Zero-JS 与 Stimulus 场景 |方法 ---|--- 简单确认 |零 JS（调用器命令）具有异步内容的模态 |刺激+涡轮框架复杂的多步骤对话框 |刺激控制器动画 | CSS `@starting-style` ### 附加模式（参见参考资料/） * **CSS 动画** 使用 `@starting-style` 用于进入/退出过渡 * **Turbo.config.forms.confirm** 替换丑陋的浏览器对话框 * **逐步增强**跨浏览器兼容性 ## 核心模式：带有 Turbo 帧的异步模态 Rails 模态的推荐模式结合了三种技术： 1. **Turbo Frame** \- 异步内容加载，无需重新加载页面 2. **Native``** \- 可访问的模式呈现 3. **刺激控制器** \- 生命周期管理 ### 第 1 步：布局容器将模态涡轮框架添加到您的布局中： <%# app/views/layouts/application.html.erb %> <正文> <%=产率%> <%# 模态注入点 %> <%=turbo_frame_tag:模态%> ### 第 2 步：触发链接从任何链接定位模态框架： <%# 任何视图 %> <%= link_to "新帖子", new_post_path, 数据: { Turbo_frame: :modal } %> <%= link_to "编辑", edit_post_path(@post), 数据: { Turbo_frame: :modal } %> <%= link_to "确认删除",confirm_delete_post_path(@post), data: { Turbo_frame: :modal } %> ### 步骤 3：模态内容视图将模态内容包装在与嵌套内部框架匹配的涡轮框架中： <%# app/views/posts/new.html.erb %> <%= Turbo_frame_tag :模态 %> <%# 内部框架可防止表单验证期间出现闪烁 %> <%= Turbo_frame_tag :modal_content 执行 %> <文章> <标题>

新帖子

<%= 渲染“表单”，帖子：@post %> <％结束％> <％结束％> ### 步骤 4：刺激控制器关键行为：连接时的“showModal()”、断开连接时的“replaceChildren()”（防止陈旧内容）、背景关闭时的“clickOutside”。有关完整的 Stimulus 控制器、CSS 样式和 Tailwind 变体，请参阅 [references/dialog-examples.md]()。 ## 为什么使用嵌套 Turbo 框架？嵌套框架模式 (`modal` > `modal_content`) 防止内容闪烁： <%= Turbo_frame_tag :模态 %> <%= Turbo_frame_tag :modal_content 执行 %> <对话框>... <％结束％> <％结束％> **没有嵌套框架的问题：** 当模式内的表单出现验证错误并重新渲染时，外框架会在替换之前短暂显示旧内容。 **嵌套框架的解决方案：** 内部框架手柄独立重新渲染，保持模态结构稳定。 ## 模态中的表单处理 ### 提交成功使用 Turbo 重定向以关闭模式并更新页面： # 应用程序/控制器/posts_controller.rb 定义创建 @post = Post.new(post_params) 如果@post.save redirect_to posts_path，注意：“帖子已创建！” 否则渲染：新，状态：：unprocessable_entity 结束结束重定向导航“_top”（整页），有效地关闭模式。 ### 验证错误以“422”状态重新渲染表单以保持模式打开：渲染：新，状态：：unprocessable_entity ### Turbo Stream 响应（保持模态）使用 `turbo_stream.update("modal", "")` 清除模态而不完全重定向。有关完整示例，请参阅 [references/dialog-examples.md]()。 ## 确认对话框模式对于破坏性操作：添加“confirm_delete”成员路由，在 Turbo 框架中渲染对话框，通过“link_to”和“data: {turbo_frame: :modal }”触发。有关完整的确认对话框视图、路由和触发器，请参阅 [references/dialog-examples.md]()。 ## 警报/Toast 模式用于闪现消息和通知。使用“show()”代替“showModal()”进行非模态演示。请参阅 [references/toast-slideover-patterns.md]() 了解完整的实现。

<%=消息%>

主要区别：“show()”打开时没有背景或焦点陷阱（toasts），“showModal()”以背景（模态）为中心。 ## 滑动面板图案用于侧面板（设置、过滤器、详细信息）。有关样式和动画，请参阅 [references/toast-slideover-patterns.md]()。 <旁白>

过滤器

<%= 渲染“过滤器”%> ## 辅助功能原生 `` 提供焦点捕获、ESC 关闭、背景惰性和自动顶层。另外确保： * 可见的关闭按钮（不仅仅是ESC） * `aria-labelledby` / `aria-scribedby` 用于描述性上下文 * 关闭时焦点返回到触发元素（将 `document.activeElement` 存储在 `connect()` 中）有关增强的可访问性和焦点返回示例，请参阅 [references/dialog-examples.md]()。 ## 常见模式总结图案|集装箱|刺激 | `显示`方法 ---|---|---|--- 情态形式| `turbo_frame_tag：模态` | `对话框` | `showModal()` 确认| `turbo_frame_tag：模态` | `对话框` | `showModal()` 祝酒/警报 |固定位置| `吐司` | `显示()` 滑盖| `turbo_frame_tag：模态` | `对话框` | `showModal()` ## 要避免的反模式反模式|问题 |解决方案 ---|---|--- 没有 `` 的自定义模式 |没有本机可访问性 |使用本机 `` 缺少嵌套涡轮框架|验证时内容闪烁 |添加内框关闭时不清除框架|重新打开时过时的内容 |在 `disconnect()` 中使用 `replaceChildren()` 清除用于堆叠的 z 索引 |与其他元素的战斗| `` 使用顶层手动对焦陷阱|复杂、容易出错 | `showModal()` 处理它内嵌背景 div |额外标记 |使用 `::backdrop` 伪元素 ## 测试对话框 # 系统测试 - 使用 `within "dialog"` 来确定断言的范围在“对话框”内做 fill_in“标题”，其中：“我的帖子” 单击按钮“创建” 结束 Expect(page).not_to have_selector("dialog[open]") # 模态关闭 ## 浏览器支持图案|铬 |火狐 |狩猎之旅 ---|---|---|--- 本机 `` | 37+ | 98+ | 15.4+ 调用者命令 | 135+ | 144+ | 26.2+ `@starting-style` | 117+ | 129+ | 17.5+ 对于较旧的浏览器：[dialog polyfill]()、[invokers polyfill]()。请参阅 [references/zero-js-patterns.md]() 了解渐进增强策略。

对话模式

包含技能