Ant Design Image 组件预览遮罩Preview Mask自定义指南mask 与 maskClassName 完全解析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本文围绕 Ant DesignantdImage组件在 components/image/demo/preview-mask.md 演示中展示的自定义预览文本能力展开深入讲解通过preview.mask与preview.maskClassName两个属性定制缩略图遮罩的完整方案。读完本文你将掌握默认遮罩的内部渲染机制、如何在 hover 时展示自定义提示文本与图标、如何通过 className 精确覆写遮罩样式以及在Image.PreviewGroup多图场景下的等价用法。一、什么是 Image 的预览遮罩Preview MaskAnt Design 的Image组件可预览的图片默认在缩略图上覆盖一层遮罩mask当鼠标悬停hover时淡入显示提示用户点击可预览大图。从组件实现 components/image/index.tsx 可以看到Ant Design 在preview未显式传入mask时会自动注入一套默认遮罩const mergedPreview React.useMemoImageProps[preview](() { if (preview false) { return preview; } const _preview typeof preview object ? preview : {}; const { getContainer, closeIcon, ...restPreviewProps } _preview; return { mask: ( div className{${prefixCls}-mask-info} EyeOutlined / {imageLocale?.preview} /div ), icons, ...restPreviewProps, // ... }; }, [preview, imageLocale, image?.preview?.closeIcon]);也就是说默认遮罩由眼睛图标EyeOutlined 当前 locale 的preview文案如中文环境下的预览两部分组成文案来自ConfigProvider提供的 locale参见 components/locale/zh_CN.ts。preview-mask这个 demo 的作用就是演示如何用自定义的 ReactNode 替换这套默认遮罩并配合maskClassName调整其样式。二、最小实现通过preview.mask自定义预览文本preview-mask演示的完整源码位于 components/image/demo/preview-mask.tsx其核心代码如下import React from react; import { ZoomInOutlined } from ant-design/icons; import { Image, Space } from antd; const App: React.FC () ( Image width{96} srchttps://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png preview{{ maskClassName: customize-mask, mask: ( Space directionvertical aligncenter ZoomInOutlined / 示例 /Space ), }} / ); export default App;要点拆解preview.mask接收任意ReactNode直接替换默认的眼睛图标 预览文案。此处使用了Space组件将放大镜图标ZoomInOutlined与文字示例纵向排列并居中preview.maskClassName将自定义类名customize-mask追加到遮罩根元素上供后续 CSS 覆写width{96}控制缩略图显示宽度与遮罩的绝对定位inset: 0无关遮罩始终铺满整个缩略图区域。在 components/image/index.zh-CN.md 的PreviewTypeAPI 表中这两个属性的定义分别为参数说明类型默认值版本mask缩略图遮罩ReactNode-4.9.0maskClassName缩略图遮罩类名string-4.11.0三、配套样式maskClassName与覆写规则preview-mask.md文档中给出了配套的 CSS.customize-mask { font-size: 20px; opacity: 1; } .customize-mask .anticon { font-size: 32px; }这里两条规则分别解决两个核心诉求文字字号与常显控制font-size: 20px放大提示文字opacity: 1让遮罩始终可见不再只出现在 hover 时。其中opacity: 1之所以有效是因为默认遮罩样式通过opacity控制显隐——默认opacity: 0、hover 时才变为1具体见下文源码分析图标尺寸联动Ant Design 图标统一挂载在.anticon类下因此mask中的ZoomInOutlined也适用.customize-mask .anticon这一选择器将图标放大到32px形成图标大、文字小的层级对比。默认遮罩样式源码依据默认遮罩的样式由 components/image/style/index.ts 中的genImageMaskStyle生成export const genImageMaskStyle (token: ImageToken): CSSObject { const { iconCls, motionDurationSlow, paddingXXS, marginXXS, prefixCls, colorTextLightSolid } token; return { position: absolute, inset: 0, display: flex, alignItems: center, justifyContent: center, color: colorTextLightSolid, background: new TinyColor(#000).setAlpha(0.5).toRgbString(), cursor: pointer, opacity: 0, transition: opacity ${motionDurationSlow}, // ... }; };关键事实遮罩是绝对定位铺满缩略图position: absolute; inset: 0并采用 Flex 居中布局align-items: center; justify-content: center因此传入的maskReactNode 天然居中背景为半透明黑rgba(0, 0, 0, 0.5)文字颜色取colorTextLightSolid亮色文字保证在深色背景上清晰可读默认opacity: 0通过opacity过渡动画淡入hover 时由 components/image/style/index.ts 的规则置为1。这就是 demo 中.customize-mask { opacity: 1 }能实现常显的底层原因。四、在 PreviewGroup 多图场景中使用mask与maskClassName同样适用于Image.PreviewGroup。根据 components/image/index.zh-CN.md 的PreviewGroupTypeAPI 表PreviewGroup的preview配置中也包含完全一致的mask4.9.0 起与maskClassName4.11.0 起属性因此多图相册模式下每一张缩略图都可复用同一套自定义遮罩import { Image } from antd; const App () ( Image.PreviewGroup preview{{ maskClassName: customize-mask, mask: div点击查看大图/div, }} Image srchttps://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png / Image srchttps://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg / /Image.PreviewGroup ); export default App;在 components/image/PreviewGroup.tsx 的实现中PreviewGroup会把preview配置原样透传给底层的RcImage.PreviewGroup因此缩略图遮罩的渲染逻辑与单图Image完全一致。测试用例 components/image/tests/index.test.tsx 中 Customize Group preview props 一节也验证了组级预览参数含遮罩过渡动画等可被正确透传。五、完整可运行示例组合用法将上述内容整合为一个可直接粘贴运行的完整示例同时覆盖自定义内容、自定义样式与多图场景import React from react; import { EyeOutlined } from ant-design/icons; import { Image, Space } from antd; const mask ( Space directionvertical aligncenter EyeOutlined / 查看大图 /Space ); const App: React.FC () ( Image.PreviewGroup preview{{ maskClassName: customize-mask, mask, }} Image width{120} srchttps://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png / Image width{120} srchttps://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg / /Image.PreviewGroup ); export default App;.customize-mask { font-size: 20px; opacity: 1; } .customize-mask .anticon { font-size: 32px; }六、注意事项与常见问题遮罩与预览入口的关系遮罩覆盖在缩略图上cursor: pointer由默认样式提供见genImageMaskStyle点击任意位置即可打开全屏预览若希望关闭预览能力应设置preview{false}测试见 components/image/tests/index.test.tsx 中 Image preview props set false而非移除maskmask渲染位置自定义mask直接作为遮罩内容渲染在缩略图容器内Flex 居中布局已由默认样式保证无需额外text-align处理如需改变布局方式可通过maskClassName覆写display、align-items等属性图标选择器Ant Design 图标统一使用.anticon类名覆写图标大小时应使用.customize-mask .anticon这一级联选择器避免影响页面其他图标demo 标注preview-mask在组件文档索引中标记为debug演示见 components/image/index.zh-CN.md 中code src./demo/preview-mask.tsx debug表示其属于进阶定制类示例不影响常规 API 的稳定性。七、进一步探索想了解其他预览定制能力工具栏、预览内容、受控预览等可继续阅读 components/image/index.zh-CN.md 中的PreviewType/PreviewGroupType完整 API 表想深入遮罩以外的预览浮层样式操作栏、关闭按钮、切换箭头可阅读 components/image/style/index.ts 中的genImagePreviewStyle、genPreviewOperationsStyle想了解 Image 组件在 RTL、挂载容器getPopupContainer、z-index 等方面的行为可查看 components/image/tests/index.test.tsx 的测试用例。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ant Design Image 组件预览遮罩（Preview Mask）自定义指南：mask 与 maskClassName 完全解析
Ant Design Image 组件预览遮罩Preview Mask自定义指南mask 与 maskClassName 完全解析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本文围绕 Ant DesignantdImage组件在 components/image/demo/preview-mask.md 演示中展示的自定义预览文本能力展开深入讲解通过preview.mask与preview.maskClassName两个属性定制缩略图遮罩的完整方案。读完本文你将掌握默认遮罩的内部渲染机制、如何在 hover 时展示自定义提示文本与图标、如何通过 className 精确覆写遮罩样式以及在Image.PreviewGroup多图场景下的等价用法。一、什么是 Image 的预览遮罩Preview MaskAnt Design 的Image组件可预览的图片默认在缩略图上覆盖一层遮罩mask当鼠标悬停hover时淡入显示提示用户点击可预览大图。从组件实现 components/image/index.tsx 可以看到Ant Design 在preview未显式传入mask时会自动注入一套默认遮罩const mergedPreview React.useMemoImageProps[preview](() { if (preview false) { return preview; } const _preview typeof preview object ? preview : {}; const { getContainer, closeIcon, ...restPreviewProps } _preview; return { mask: ( div className{${prefixCls}-mask-info} EyeOutlined / {imageLocale?.preview} /div ), icons, ...restPreviewProps, // ... }; }, [preview, imageLocale, image?.preview?.closeIcon]);也就是说默认遮罩由眼睛图标EyeOutlined 当前 locale 的preview文案如中文环境下的预览两部分组成文案来自ConfigProvider提供的 locale参见 components/locale/zh_CN.ts。preview-mask这个 demo 的作用就是演示如何用自定义的 ReactNode 替换这套默认遮罩并配合maskClassName调整其样式。二、最小实现通过preview.mask自定义预览文本preview-mask演示的完整源码位于 components/image/demo/preview-mask.tsx其核心代码如下import React from react; import { ZoomInOutlined } from ant-design/icons; import { Image, Space } from antd; const App: React.FC () ( Image width{96} srchttps://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png preview{{ maskClassName: customize-mask, mask: ( Space directionvertical aligncenter ZoomInOutlined / 示例 /Space ), }} / ); export default App;要点拆解preview.mask接收任意ReactNode直接替换默认的眼睛图标 预览文案。此处使用了Space组件将放大镜图标ZoomInOutlined与文字示例纵向排列并居中preview.maskClassName将自定义类名customize-mask追加到遮罩根元素上供后续 CSS 覆写width{96}控制缩略图显示宽度与遮罩的绝对定位inset: 0无关遮罩始终铺满整个缩略图区域。在 components/image/index.zh-CN.md 的PreviewTypeAPI 表中这两个属性的定义分别为参数说明类型默认值版本mask缩略图遮罩ReactNode-4.9.0maskClassName缩略图遮罩类名string-4.11.0三、配套样式maskClassName与覆写规则preview-mask.md文档中给出了配套的 CSS.customize-mask { font-size: 20px; opacity: 1; } .customize-mask .anticon { font-size: 32px; }这里两条规则分别解决两个核心诉求文字字号与常显控制font-size: 20px放大提示文字opacity: 1让遮罩始终可见不再只出现在 hover 时。其中opacity: 1之所以有效是因为默认遮罩样式通过opacity控制显隐——默认opacity: 0、hover 时才变为1具体见下文源码分析图标尺寸联动Ant Design 图标统一挂载在.anticon类下因此mask中的ZoomInOutlined也适用.customize-mask .anticon这一选择器将图标放大到32px形成图标大、文字小的层级对比。默认遮罩样式源码依据默认遮罩的样式由 components/image/style/index.ts 中的genImageMaskStyle生成export const genImageMaskStyle (token: ImageToken): CSSObject { const { iconCls, motionDurationSlow, paddingXXS, marginXXS, prefixCls, colorTextLightSolid } token; return { position: absolute, inset: 0, display: flex, alignItems: center, justifyContent: center, color: colorTextLightSolid, background: new TinyColor(#000).setAlpha(0.5).toRgbString(), cursor: pointer, opacity: 0, transition: opacity ${motionDurationSlow}, // ... }; };关键事实遮罩是绝对定位铺满缩略图position: absolute; inset: 0并采用 Flex 居中布局align-items: center; justify-content: center因此传入的maskReactNode 天然居中背景为半透明黑rgba(0, 0, 0, 0.5)文字颜色取colorTextLightSolid亮色文字保证在深色背景上清晰可读默认opacity: 0通过opacity过渡动画淡入hover 时由 components/image/style/index.ts 的规则置为1。这就是 demo 中.customize-mask { opacity: 1 }能实现常显的底层原因。四、在 PreviewGroup 多图场景中使用mask与maskClassName同样适用于Image.PreviewGroup。根据 components/image/index.zh-CN.md 的PreviewGroupTypeAPI 表PreviewGroup的preview配置中也包含完全一致的mask4.9.0 起与maskClassName4.11.0 起属性因此多图相册模式下每一张缩略图都可复用同一套自定义遮罩import { Image } from antd; const App () ( Image.PreviewGroup preview{{ maskClassName: customize-mask, mask: div点击查看大图/div, }} Image srchttps://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png / Image srchttps://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg / /Image.PreviewGroup ); export default App;在 components/image/PreviewGroup.tsx 的实现中PreviewGroup会把preview配置原样透传给底层的RcImage.PreviewGroup因此缩略图遮罩的渲染逻辑与单图Image完全一致。测试用例 components/image/tests/index.test.tsx 中 Customize Group preview props 一节也验证了组级预览参数含遮罩过渡动画等可被正确透传。五、完整可运行示例组合用法将上述内容整合为一个可直接粘贴运行的完整示例同时覆盖自定义内容、自定义样式与多图场景import React from react; import { EyeOutlined } from ant-design/icons; import { Image, Space } from antd; const mask ( Space directionvertical aligncenter EyeOutlined / 查看大图 /Space ); const App: React.FC () ( Image.PreviewGroup preview{{ maskClassName: customize-mask, mask, }} Image width{120} srchttps://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png / Image width{120} srchttps://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg / /Image.PreviewGroup ); export default App;.customize-mask { font-size: 20px; opacity: 1; } .customize-mask .anticon { font-size: 32px; }六、注意事项与常见问题遮罩与预览入口的关系遮罩覆盖在缩略图上cursor: pointer由默认样式提供见genImageMaskStyle点击任意位置即可打开全屏预览若希望关闭预览能力应设置preview{false}测试见 components/image/tests/index.test.tsx 中 Image preview props set false而非移除maskmask渲染位置自定义mask直接作为遮罩内容渲染在缩略图容器内Flex 居中布局已由默认样式保证无需额外text-align处理如需改变布局方式可通过maskClassName覆写display、align-items等属性图标选择器Ant Design 图标统一使用.anticon类名覆写图标大小时应使用.customize-mask .anticon这一级联选择器避免影响页面其他图标demo 标注preview-mask在组件文档索引中标记为debug演示见 components/image/index.zh-CN.md 中code src./demo/preview-mask.tsx debug表示其属于进阶定制类示例不影响常规 API 的稳定性。七、进一步探索想了解其他预览定制能力工具栏、预览内容、受控预览等可继续阅读 components/image/index.zh-CN.md 中的PreviewType/PreviewGroupType完整 API 表想深入遮罩以外的预览浮层样式操作栏、关闭按钮、切换箭头可阅读 components/image/style/index.ts 中的genImagePreviewStyle、genPreviewOperationsStyle想了解 Image 组件在 RTL、挂载容器getPopupContainer、z-index 等方面的行为可查看 components/image/tests/index.test.tsx 的测试用例。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 空间优化)
