Livewire 离线检测指南用wire:offline指令优雅处理断网状态【免费下载链接】livewireA full-stack framework for Laravel that takes the pain out of building dynamic UIs.项目地址: https://gitcode.com/gh_mirrors/li/livewire导读在实时交互的 Livewire 应用中用户的设备随时可能断开网络连接。wire:offline指令允许你在组件内声明式地切换元素的显示状态、CSS 类或 HTML 属性从而在断网时给出明确的视觉反馈例如提示用户当前设备已离线或禁用保存按钮。本文将完整介绍wire:offline的三种用法显隐切换、类切换、属性切换并结合仓库源码剖析其底层实现原理。为什么需要wire:offlineLivewire 应用是实时双向交互的用户在前端输入数据组件通过 AJAX 请求与服务器同步。一旦用户设备断网这些请求就会失败——数据既无法保存组件也无法更新。此时如果界面毫无提示用户可能会继续输入大量内容却不知道这些内容根本无法提交到服务器。例如如果你基于 Livewire 搭建了一个博客平台用户正在撰写一篇文章。如果设备断网而界面毫无反馈用户可能写完一整篇博客却无法保存。此时通过wire:offline给出设备当前离线的明确提示就能帮助用户避免这种损失。wire:offline正是为此设计的在 Livewire 组件内的任意元素上加上该指令该元素默认隐藏当用户失去网络连接时自动变为可见网络恢复后元素又自动消失。基础用法断网时显示提示将wire:offline指令添加到 Livewire 组件内的任意元素上该元素在正常情况下会被隐藏display: none一旦浏览器触发offline事件元素就会变为可见div {{-- 组件其余内容 --}} div wire:offline This device is currently offline. /div /div当网络连接恢复时该元素会再次隐藏。整个过程完全由浏览器原生的offline/online事件驱动无需任何手动刷新或组件请求。完整示例博客撰写场景结合文章开头的博客场景一个更完整的实践是在表单区域附近放置离线提示同时禁用提交按钮下一节介绍属性切换form wire:submitsavePost textarea wire:modelcontent placeholder撰写你的文章.../textarea div wire:offline ⚠️ 当前设备已离线内容暂无法保存。 /div button typesubmit wire:offline.attrdisabled保存文章/button /form切换 CSS 类wire:offline.class有时你不希望隐藏/显示整个元素而是希望在断网时给元素附加或移除某个 CSS 类从而实现颜色变化、透明度调整、边框高亮等视觉效果。.class修饰符断网时添加类使用.class修饰符并传入类名当用户断网时该类会被添加到元素上用户恢复在线后该类被移除div wire:offline.classbg-red-300这段代码在断网时会为div添加bg-red-300类假设你使用 Tailwind CSS元素背景会变为红色网络恢复后自动移除。支持多个类名类的表达式支持以空格分隔的多个类名底层实现会将其拆分后逐一添加。例如div wire:offline.classbg-red-300 text-white p-4.class.remove修饰符断网时移除类.class.remove与.class相反断网时移除指定的类恢复在线后重新加回。下面的例子中bg-green-300类在用户断网期间会被移除元素失去绿色背景div classbg-green-300 wire:offline.class.removebg-green-300提示.remove修饰符的语义是反转布尔状态。底层实现中toggleBooleanStateDirective会先判断remove修饰符将isTruthy取反后再执行类/属性的增删逻辑详见下文底层实现小节。切换 HTML 属性wire:offline.attr.attr修饰符允许你在断网时向元素添加一个 HTML 属性网络恢复后移除。最常见的应用场景是断网时禁用表单按钮避免用户提交注定失败的数据button wire:offline.attrdisabledSave/button断网时上述按钮会获得disabled属性值为true点击无效恢复在线后disabled属性被移除按钮恢复正常可用。结合.remove反向操作与类切换一样.attr也可以与.remove组合使用实现断网时移除属性的效果。例如某元素默认带有disabled属性断网时反而移除它适用于某些特殊交互需求button wire:offline.attr.removedisabled disabledtrue该用法在仓库的浏览器测试 legacy_tests/Browser/Offline/Test.php 中也有覆盖。指令速查 Referencewire:offline的完整语法与修饰符汇总如下wire:offline修饰符一览修饰符说明.classclass-name断网时向元素添加 CSS 类支持空格分隔的多个类名恢复在线后移除.class.removeclass-name断网时从元素移除 CSS 类恢复在线后重新添加.attrattribute断网时向元素添加 HTML 属性恢复在线后移除.attr.removeattribute断网时从元素移除 HTML 属性恢复在线后重新添加说明attr变体虽未列在原文档的速查表中但其行为由共享的状态切换实现toggleBooleanStateDirective与.class.remove完全对称并在浏览器测试中明确断言因此一并收录。底层实现offline事件驱动的状态切换wire:offline的前端实现位于 js/directives/wire-offline.js并在 js/directives/index.js 中被注册加载。其核心逻辑非常简洁import { toggleBooleanStateDirective } from ./shared import { directive } from /directives let offlineHandlers new Set let onlineHandlers new Set window.addEventListener(offline, () offlineHandlers.forEach(i i())) window.addEventListener(online, () onlineHandlers.forEach(i i())) directive(offline, ({ el, directive, cleanup }) { let setOffline () toggleBooleanStateDirective(el, directive, true) let setOnline () toggleBooleanStateDirective(el, directive, false) offlineHandlers.add(setOffline) onlineHandlers.add(setOnline) cleanup(() { offlineHandlers.delete(setOffline) onlineHandlers.delete(setOnline) }) })要点解析依赖浏览器原生事件整个机制建立在window的offline/online事件之上没有自定义网络探测或轮询。处理器集合管理offlineHandlers和onlineHandlers是两个Set存放所有已注册元素的状态切换回调浏览器事件触发时统一遍历执行。使用Set可天然去重避免同一元素重复注册。cleanup钩子当元素被移除如组件销毁或 DOM 更新后不再存在时从两个集合中删除对应回调防止内存泄漏与幽灵更新。实际状态切换逻辑具体的显隐、类、属性切换逻辑集中在 js/directives/shared.js 的toggleBooleanStateDirective中export function toggleBooleanStateDirective(el, directive, isTruthy, cachedDisplay null) { isTruthy directive.modifiers.includes(remove) ? ! isTruthy : isTruthy if (directive.modifiers.includes(class)) { let classes directive.expression.split( ).filter(String) if (isTruthy) { el.classList.add(...classes) } else { el.classList.remove(...classes) } } else if (directive.modifiers.includes(attr)) { if (isTruthy) { el.setAttribute(directive.expression, true) } else { el.removeAttribute(directive.expression) } } else { // 纯显隐模式缓存原始 display切换 display 值 let cache cachedDisplay ?? window .getComputedStyle(el, null) .getPropertyValue(display) let display ([inline, list-item, block, table, flex, grid, inline-flex] .filter(i directive.modifiers.includes(i))[0] || inline-block) display (directive.modifiers.includes(remove) ! isTruthy) ? cache : display el.style.display isTruthy ? display : none } }三个分支分别对应三种用法纯显隐模式无修饰符断网时把元素的display设为inline-block或由修饰符指定的值恢复在线后设为none。它会先通过getComputedStyle缓存元素的原始display值并在.remove组合时恢复原始值——这就是为什么裸写wire:offline的元素默认是隐藏的。类模式.class将表达式按空格拆分成多个类名filter(String)过滤空串断网时批量classList.add恢复时classList.remove。属性模式.attr断网时setAttribute(expr, true)恢复时removeAttribute(expr)。这也是前面例子中按钮disabled属性值呈现为true的原因。与wire:loading等指令共享同一套实现值得留意的是toggleBooleanStateDirective是 Livewire 前端多个布尔状态型指令的共享实现——它同样服务于wire:loading请求进行中等指令。wire:offline只是把事件源从组件请求状态换成了浏览器网络状态。js/directives/wire-loading.js 中的nonActionOrModelLivewireDirectives列表也把offline与其他纯状态指令归为一类说明它不会触发组件请求。与其他离线能力的关系wire:offline只是 Livewire 对离线状态的视觉反馈手段仓库中还存在其他与离线相关的机制它们各司其职轮询自动暂停js/directives/wire-poll.js 中维护了一个模块级isOffline标志同样监听offline/online事件。wire:poll指令通过pauseWhile(() livewireIsOffline())js/directives/wire-poll.js在断网期间暂停轮询请求避免无意义的失败请求轰炸服务器网络恢复后自动恢复轮询。导航降级js/plugins/navigate/index.js 中wire:navigate在浏览器报告离线时会把导航交还给浏览器默认行为从而展示浏览器自带的离线页面。如果你需要更完整的离线体验例如配合 Service Worker 实现 PWA 离线缓存wire:offline的视觉提示可以与上述行为组合使用。浏览器测试验证仓库在 legacy_tests/Browser/Offline/Test.php 中提供了针对wire:offline的完整 Dusk 浏览器测试覆盖了全部四种组合场景public function test_wire_offline() { Livewire::visit(new class extends Component { public function render() { return HTML div span wire:offline duskwhileOfflineOffline/span span wire:offline.classfoo duskaddClass/span span classhidden wire:offline.class.removehidden duskremoveClass/span span wire:offline.attrdisabled duskwithAttribute/span span wire:offline.attr.removedisabled disabledtrue duskwithoutAttribute/span /div HTML; } }) -assertMissing(whileOffline) // 在线时元素隐藏 -offline() -assertSeeIn(whileOffline, Offline) // 断网后元素可见 -online() -assertMissing(whileOffline) // 恢复后再次隐藏 // ... 类与属性的添加/移除断言见原文件 ; }测试通过-offline()与-online()模拟浏览器断网/恢复逐条断言了裸wire:offline的显隐切换.class断网时添加foo类、恢复后移除.class.remove断网时移除hidden类、恢复后加回.attr断网时添加disabled属性值为true、恢复后移除.attr.remove断网时移除disabled属性、恢复后加回。这五组断言与本文介绍的全部用法一一对应可以作为你理解指令行为的权威参考。小结wire:offline是 Livewire 处理离线反馈的最小、最优雅的方案零配置直接写在组件模板中即可无需任何 JavaScript 代码事件驱动基于浏览器原生offline/online事件实时响应网络状态变化三种形态纯显隐wire:offline、类切换.class/.class.remove、属性切换.attr/.attr.remove源码可循完整实现见 js/directives/wire-offline.js 与 js/directives/shared.js并配有 legacy_tests/Browser/Offline/Test.php 浏览器测试背书。在实现类似断网提示条、离线禁用提交等交互时优先考虑wire:offline它能让你的界面在网络不稳定时依然保持诚实与可用。【免费下载链接】livewireA full-stack framework for Laravel that takes the pain out of building dynamic UIs.项目地址: https://gitcode.com/gh_mirrors/li/livewire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
