diff --git a/layouts/admin/components/AdminTagsView.uvue b/layouts/admin/components/AdminTagsView.uvue index d7dcc394..aa8db2a4 100644 --- a/layouts/admin/components/AdminTagsView.uvue +++ b/layouts/admin/components/AdminTagsView.uvue @@ -1,6 +1,22 @@ diff --git a/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md b/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md index e06080df..1a5566ba 100644 --- a/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md +++ b/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md @@ -206,6 +206,65 @@ 2. **移除组件级 Margin**: Grid 布局应使用 `gap` 属性控制间距,组件自身 (`.user-map-card`) 不应自带外部 Margin,否则会破坏等高计算。 3. **强制 Canvas 填充**: 图表组件容器需设置 `width: 100% !important; height: 100% !important;` 且 `position: absolute` (配合父级 relative) 或 `flex: 1`,确保填满 Flex 空间。 +#### **原因二十五:uni-app x 悬停菜单功能失效 (鼠标事件兼容性)** + +- **现象**: `@mouseenter` 和 `@mouseleave` 事件完全无响应,悬停菜单不显示;控制台显示状态变化但菜单不可见或定位错误;鼠标悬停在蓝色方格功能按钮上无任何反应。 +- **根本原因**: + 1. **平台条件编译缺失**: uni-app x 对鼠标事件有特殊处理机制,所有 `@mouseenter/@mouseleave` 的处理函数必须包装在 `#ifdef H5` 条件编译中才能生效,直接编写的代码会被平台忽略。 + 2. **CSS 定位兼容性**: 使用 `top: 100%` 百分比定位在 uni-app x 中计算不准确,导致菜单定位错误或不可见。 + 3. **容器设置不当**: 缺少 `height: 100%` 和 `overflow: visible` 设置,导致悬停检测区域不完整或菜单被裁切。 +- **对比分析**: 参考 `AdminHeader.uvue` 中工作正常的个人信息悬停菜单实现,发现以下关键差异: + + ```javascript + // ❌ 错误写法 - 不工作 + function handleFunctionMenuOver(e: any): void { + functionMenuVisible.value = true // 直接执行,被 uni-app x 忽略 + } + + // ✅ 正确写法 - 工作 + function handleFunctionMenuOver(e: any): void { + // #ifdef H5 + functionMenuVisible.value = true // 包装在条件编译中才生效 + // #endif + } + ``` + +- **完整解决方案**: + 1. **添加条件编译** (最关键): + ```javascript + function handleFunctionMenuOver(e: any): void { + // #ifdef H5 + if (hideFunctionMenuTimer !== null) { + clearTimeout(hideFunctionMenuTimer as number) + hideFunctionMenuTimer = null + } + functionMenuVisible.value = true + // #endif + } + ``` + 2. **修复 CSS 定位**: + ```css + .function-menu { + position: absolute; + top: 44px; /* 使用固定像素值,44px是tags容器高度 */ + right: 0; + overflow: visible; /* 确保菜单不被裁切 */ + } + ``` + 3. **优化容器设置**: + ```css + .function-btn-wrapper { + height: 100%; /* 确保悬停不中断,仿照AdminHeader */ + overflow: visible; + } + ``` + 4. **统一定时器延迟**: 所有定时器延迟设置为 150ms,与 AdminHeader 保持一致。 +- **推广规则**: + 1. uni-app x 中的所有鼠标事件处理必须包装在 `#ifdef H5` 中。 + 2. 悬停菜单定位优先使用固定像素值而非百分比。 + 3. 容器必须设置正确的 `height` 和 `overflow` 属性。 + 4. 成功的悬停菜单实现应该作为模板复用到其他组件。 + ## 🛠️ 完整修复流程 ``` @@ -1947,23 +2006,23 @@ const iconMap: Record = { - **CRMEB 路由映射**: 1:1 复刻 CRMEB 的路由和菜单结构 - **双侧边栏布局**: 主侧边栏(一级) + 二级侧边栏(分组) - ## 🎯 阶段十八: Vue/Vite 编译失败导致的连锁依赖雪崩 (500 错误与动态导入阻断) ### **原因三十二:SCSS 括号闭合错误引发的 ?import 连锁报错** -- **现象**: +- **现象**: 1. 浏览器控制台出现核心组件的 SCSS 编译失败:GET /pages/mall/admin/product/product-management/index.uvue?...&lang.scss 500 2. 随后出现警告:[Vue warn]: Unhandled error during execution of async component loader 3. 最终报错阻断页面级加载:TypeError: Failed to fetch dynamically imported module: /pages/mall/admin/homePage/index.uvue?import -- **原因**: +- **原因**: 在修改或合并页面(如整合目录结构)时,不慎破坏了 )。由于 Vite 处理 uni-app-x 时是按块编译的,CSS 预处理报错会导致服务端直接向该组件抛出 **500 错误**。 在 "内部路由/状态驱动" 模式下,我们的系统依赖 dminComponentMap.uts 全量静态扫描所有的管理页面。一旦链路树中的某个子节点(例如 product-management/index.uvue)发生了 500 编译失败,会导致整个模块依赖树发生雪崩。父级页面(如引了全局 Layout 的 homePage/index.uvue)会因为底层的依赖断裂,无法组装出正确的 JS 模块,最终导致 **动态导入失败** 的假象。 -- **解决方案**: +- **解决方案**: 1. **禁止盲目改路由**:**绝对不要**因为看到 homePage 报错就去重写 homePage 或者怀疑路由表配错了。 2. **顺藤摸瓜找源头**:沿着浏览器 Network 或者 Console 错误的最顶部往上翻,找到第一个且唯一一个抛出 500 的资源(在本例中是 lang.scss)。 - 3. **修复语法树**:回到那个触发 500 的文件,检查并修复 emplate、script、style 标签的闭锁以及其内部(特别是 SCSS 嵌套)的语法错误(如括号配对)。语法自洽后,整个异步组件树便会瞬间全量恢复正常。 + 3. **修复语法树**:回到那个触发 500 的文件,检查并修复 emplate、script、style 标签的闭锁以及其内部(特别是 SCSS 嵌套)的语法错误(如括号配对)。语法自洽后,整个异步组件树便会瞬间全量恢复正常。 - **防止复发规范**: 当执行文件全局批量替换或目录大迁移后,切勿遗留未闭合的代码块。修复问题必须采用“由底向外”的收敛原则。 + --- 这个指南现在涵盖了 uni-app-x 项目开发中最常见的 17 类问题(新增动态导入与语法遮蔽解析),为后续开发提供了完整的故障排除和最佳实践指导。 🚀 @@ -2206,4 +2265,3 @@ curl -i -X OPTIONS "http://192.168.1.61:9122/rest/v1/ml_coupon_templates?select= --- 这个指南现在涵盖了 uni-app-x 项目开发中最常见的 33 类问题(包含全局组件化最佳实践),为后续开发提供了完整的故障排除和标准化指导。 🚀 -