Ant-Design-Vue Image-Preview 组件箭头图标局部替换.md

# Ant-Design-Vue Image-Preview 组件箭头图标局部替换 在实习时，UI 的设计稿将 antdv 的 image-preview 组件的左右箭头替换为 UI 所设计的icon，尝试了多次后才成功替换，在此做一个记录  ## 需求 1. icon替换：将 `a-image-preview-group` 的默认左右箭头替换为自定义图标，并分别提供 normal、hover、click 三种状态的icon 2. 局部替换，不影响全局：同时要求本次修改只作用于当前 `a-image-preview-group`，不能影响项目中其他页面的图片预览组件 ## 踩坑记录 ### `preview.rootClassName` 没有生效 最开始让 deepseek-v4 pro 更改，尝试通过 `preview.rootClassName` 给当前图片预览面板添加独立类名 ```vue ... ``` 然后通过该类名限制箭头样式的作用范围 ```scss .facility-image-preview { .ant-image-preview-switch-left { ... } } ``` 但实际测试发现，antdv 根本没有提供 rootClassName 的api，纯 AI 幻觉 > https://antdv.com/components/image-cn#api > >  > 后续发现 Ant Design Vue 4.x 的 `PreviewGroup` 封装层会覆盖用户传入的 `rootClassName`，并使用组件内部生成的 `hashId` >  ```js // node_modules/ant-design-vue/es/image/PreviewGroup.js const _preview = typeof preview === 'object' ? preview : {} return _extends(_extends({}, _preview), { rootClassName: hashId.value }) ``` 这里先展开用户传入的 `_preview`，然后再次设置 `rootClassName` 因此，用户传入的： ```js rootClassName: 'facility-image-preview' ``` 最终会被`hashId` 覆盖： ```js rootClassName: hashId.value ``` 所以不能依赖 `preview.rootClassName` 实现当前预览组件的样式隔离 ### `scoped CSS` 无法命中预览面板 另一种尝试是在当前 Vue 组件的 `scoped` 样式中直接修改箭头 ```vue ``` 但图片预览面板默认通过 Portal 挂载到 `document.body`，并不在当前 Vue 组件的 DOM 树中 Vue 的 `scoped` 样式会被编译为带有 `data-v-xxx` 属性的选择器 ```css [data-v-xxx] .ant-image-preview-switch-left { ... } ``` 而预览面板位于 `document.body` 下，不属于当前带有 `data-v-xxx` 的组件节点，因此选择器无法命中 即使使用 `:deep()`，也无法改变预览面板已经脱离当前组件 DOM 树这一事实 ### 全局选择器会影响其他组件 如果直接使用全局选择器，样式可以正常生效 ```scss .ant-image-preview-switch-left { ... } .ant-image-preview-switch-right { ... } ``` 但这种方式会修改项目中所有 `a-image-preview-group` 的左右箭头，其他页面中的 `ImageViewer.vue` 也会被影响 因此，全局选择器虽然可行，但不满足本次需求中的局部作用域要求 ## 解决方案 最终采用 `getContainer + ref + 后代选择器` 实现局部替换 整体思路分为两步： - 通过 `ref` 获取当前组件的容器节点 - 通过后代选择器，只修改该容器内部的图片预览箭头 ### 通过 ref 指定预览面板的挂载位置 首先，在当前组件的根容器上绑定 `rootRef` ```vue ``` 在脚本中声明对应的模板引用 ```js import { ref } from 'vue' const rootRef = ref(null) ``` 在 Vue 模板表达式中，`ref` 会被自动解包，因此： ```js getContainer: () => rootRef ``` 实际返回的是 `rootRef.value` 对应的 DOM 元素 Ant Design Vue 获取到该容器后，会将当前 `a-image-preview-group` 的预览面板挂载到 `.scroll-container` 内部，而不是默认挂载到 `document.body` ### 使用后代选择器精确替换箭头 预览面板挂载到 `.scroll-container` 后，最终生成的左右切换按钮会成为该容器的后代元素 此时可以通过： ```scss .scroll-container .ant-image-preview-switch-left ``` 精确匹配当前组件中的预览箭头 ```vue ``` 这部分样式不能使用普通的 `scoped` 写法 预览面板虽然被挂载到了 `.scroll-container` 内部，但预览组件生成的 DOM 元素不会自动携带当前组件的 `data-v-xxx` 属性 因此这里使用非 `scoped` 样式，再通过 `.scroll-container` 限定作用范围 ### 样式处理说明 隐藏 Ant Design Vue 默认箭头背景： ```scss background: none !important; ``` 隐藏默认的 SVG 图标： ```scss > .anticon { display: none !important; } ``` 使用伪元素承载自定义图标： ```scss &::before { content: ''; display: block; width: 56px; height: 56px; background-position: center; background-size: contain; background-repeat: no-repeat; } ``` 通过不同的伪类切换图片状态： ```scss &::before { background-image: url('normal.png'); } &:hover::before { background-image: url('hover.png'); } &:active::before { background-image: url('click.png'); } ``` 在第一张或最后一张图片时，Ant Design Vue 会添加 disabled 类名，此时降低自定义箭头的透明度： ```scss .ant-image-preview-switch-left-disabled, .ant-image-preview-switch-right-disabled { cursor: not-allowed; &::before { opacity: 0.6; } } ``` ## DOM 结构变化 修改前，预览面板默认挂载在 `document.body` 下： ```html ... ``` 此时 `.scroll-container` 和预览箭头之间不存在父子关系，下面的选择器无法命中： ```scss .scroll-container { .ant-image-preview-switch-left { ... } } ``` 增加 `getContainer` 后，预览面板被挂载到 `rootRef` 对应的 `.scroll-container` 内： ```html ... ``` 此时预览箭头是 `.scroll-container` 的后代元素，因此后代选择器能够正常命中： ```scss .scroll-container { .ant-image-preview-switch-left { ... } } ``` ## 最终效果 | 状态 | 图标 | 触发方式 | | -------- | ------------------------------------ | ---------------- | | normal | `normal-left.png`、`normal-right.png` | 默认状态 | | hover | `hover-left.png`、`hover-right.png` | 鼠标悬停 | | click | `click-left.png`、`click-right.png` | 鼠标按下 | | disabled | 自定义图标透明度降低 | 第一张的左箭头或最后一张的右箭头 | 最终方案虽然使用了非 `scoped` 样式，但所有规则都被限制在 `.scroll-container` 后代中 其他图片预览组件仍然挂载在默认容器中，不属于当前 `.scroll-container`，因此不会受到本次样式修改的影响 ## `getContainer` 带来的副作用 通过 `getContainer` 将预览面板挂载到当前组件容器后，虽然解决了箭头样式只能局部生效的问题，但也引入了一个新的生命周期问题 ### 问题现象 存在详情态和编辑态两种状态，详情态可全屏预览图片，并通过 getContainer 将全屏预览的上/下切换箭头进行了替换，但却产生了新的问题： ```text 详情态点击图片全屏预览 ↓ 关闭图片预览 ↓ 点击“编辑”按钮 ↓ 页面白屏，编辑态内容完全不可见 ``` 这里的“白屏”并不一定表示编辑态内容没有渲染，更可能是图片预览遗留的遮罩层仍然覆盖在编辑内容上方 ### 再次踩坑 最初判断是 `v-if / v-else` 切换时，`a-image-preview-group` 销毁过快，而 Preview Dialog 的关闭和清理还没有完成 围绕这个方向尝试了两种方案 #### 将 Preview 改为受控模式 通过变量控制预览状态，并在进入编辑态前主动关闭预览 ```js const previewOpen = ref(false) function enterEdi