GraphicAttractionBlock (图文吸引模块)

用于展示产品核心卖点，由大图 Banner + 特性卡片网格组成，适合产品详情页和营销页面。【✅ 已发布】

场景:

视口:

加载中...

当前视口: 1920px × 600px场景: 四特性展示

打开链接

功能特性

✅ 英雄图 Banner - 支持 PC/Mobile 独立图片，响应式切换
✅ 文字叠加 - 标题和描述文字覆盖在图片上
✅ 特性卡片网格 - 2×2 移动端，4 列桌面端
✅ 图标展示 - 卡片右上角显示图标
✅ 富文本支持 - 标题和描述支持 HTML 格式
✅ 形状变体 - square(方形)和 rounded(圆角)两种样式
✅ 可选章节标题 - 使用 Title 组件
✅ 响应式宽高比 - 移动端 358:480，桌面端 1664:560
✅ 语义化 HTML - 使用 <section> 标签

Props 参数

GraphicAttractionBlockProps

Prop	类型	默认值	必需	说明
`data`	`GraphicAttractionBlockData`	-	✅	组件数据配置对象
`className`	`string`	`''`	-	自定义根容器类名
`ref`	`React.Ref<HTMLDivElement>`	-	-	根容器 ref

GraphicAttractionBlockData 配置

参数	类型	默认值	必需	说明
`shape`	`'square' \| 'rounded'`	`'square'`	-	卡片形状样式
`sectionTitle`	`string`	-	-	章节标题（可选）
`imageUrlPc`	`Media`	-	✅	PC 端主图
`imageUrlMob`	`Media`	-	-	移动端主图（可选，不提供则使用 PC 图）
`imageTitle`	`string`	-	✅	主图标题（支持 HTML）
`imageDescription`	`string`	-	✅	主图描述（支持 HTML）
`attractionItems`	`AttractionItem[]`	-	✅	特性卡片列表

AttractionItem 配置

参数	类型	必需	说明
`icon`	`Img`	-	卡片图标
`title`	`string`	✅	卡片标题（支持 HTML）
`description`	`string`	✅	卡片描述（支持 HTML）

Media 类型

参数	类型	必需	说明
`url`	`string`	✅	图片 URL
`alt`	`string`	✅	替代文本
`thumbnailURL`	`string`	-	缩略图 URL
`mimeType`	`string`	-	MIME 类型（如 ‘image/jpeg’）

使用示例

最简示例


import { GraphicAttractionBlock } from '@anker-in/headless-ui/biz'
import scenarios from './scenarios.json'
 
<GraphicAttractionBlock
  data={{
    imageUrlPc: {
      url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
      alt: 'Product hero image',
    },
    imageTitle: 'Whole-Home Backup Power',
    imageDescription: 'Keep your home running during blackouts',
    attractionItems: [
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1614292247047-a966dd17c2e3',
          alt: 'Power icon',
        },
        title: 'Instant Power',
        description: 'Seamless switch in under 10 seconds',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1609091839311-d5365f9ff1c5',
          alt: 'Battery icon',
        },
        title: 'Long-Lasting',
        description: 'Up to 48 hours of backup power',
      },
    ],
  }}
/>

基础图文区块


<GraphicAttractionBlock
  data={{
    imageUrlPc: {
      url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
      alt: 'Backup power system',
    },
    imageUrlMob: {
      url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64?w=400',
      alt: 'Backup power system mobile',
    },
    imageTitle: 'Whole-Home Backup Power',
    imageDescription: 'Maintain a high quality of life during blackouts by powering all kinds of home appliances.',
    attractionItems: [
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1614292247047-a966dd17c2e3',
          alt: 'Energy storage',
        },
        title: 'Storing Energy',
        description: 'Maintain a high quality of life during blackouts',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1509391366360-2e959784a276',
          alt: 'Solar power',
        },
        title: 'Solar Power',
        description: 'Store solar power for nighttime use with the solar bank',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
          alt: 'Plug and play',
        },
        title: 'Plug & Play',
        description: 'Connect the Schuko plug to a power socket',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1614292247047-a966dd17c2e3',
          alt: 'Safe',
        },
        title: 'Safe & Reliable',
        description: 'Multi-layer protection ensures your safety',
      },
    ],
  }}
/>

带章节标题


<GraphicAttractionBlock
  data={{
    sectionTitle: 'Install and Save Electricity Costs',
    imageUrlPc: {
      url: 'https://images.unsplash.com/photo-1581092160562-40aa08e78837',
      alt: 'Easy installation',
    },
    imageTitle: 'DIY-Friendly Installation',
    imageDescription: 'Set up in minutes with our step-by-step guide',
    attractionItems: [
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1530124566582-a618bc2615dc',
          alt: 'Tools',
        },
        title: 'No Special Tools',
        description: 'Everything you need is included in the box',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1501139083538-0139583c060f',
          alt: 'Time',
        },
        title: '30-Minute Setup',
        description: 'Average installation time for most homes',
      },
    ],
  }}
/>

圆角样式


<GraphicAttractionBlock
  data={{
    shape: 'rounded',
    imageUrlPc: {
      url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
      alt: 'Product showcase',
    },
    imageTitle: 'Award-Winning Design',
    imageDescription: 'Recognized for innovation and quality',
    attractionItems: [
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1565688534245-05d6b5be184a',
          alt: 'Award',
        },
        title: 'CES Innovation Award',
        description: '2025 Winner',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1600783245777-2e60b4a4d2c5',
          alt: 'Design',
        },
        title: 'Red Dot Award',
        description: 'Best Product Design',
      },
    ],
  }}
/>

富文本格式


<GraphicAttractionBlock
  data={{
    imageUrlPc: {
      url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
      alt: 'Product features',
    },
    imageTitle: '<b>Ultra-Fast</b> Charging',
    imageDescription: 'Get <b>50%</b> charge in just <b>30 minutes</b>',
    attractionItems: [
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1614292247047-a966dd17c2e3',
          alt: 'Speed',
        },
        title: '<b>250W</b> Max Output',
        description: 'Charge laptops, phones, and tablets simultaneously',
      },
      {
        icon: {
          url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
          alt: 'Devices',
        },
        title: '<b>6</b> Ports',
        description: 'Power <b>all</b> your devices at once',
      },
    ],
  }}
/>

响应式行为

主图宽高比

组件在不同设备上使用不同的宽高比：

屏幕尺寸	宽高比	实际尺寸参考	说明
Mobile	< 768px	358:480	约 3:4，竖屏比例，适合移动设备
Tablet+	≥ 768px	1664:560	约 3:1，宽屏比例，充分利用桌面空间

卡片网格布局

屏幕尺寸	列数	gap	说明
Mobile	< 768px	2 列	12px
Tablet+	≥ 768px	4 列	16px

卡片内边距

屏幕尺寸	内边距
Mobile	< 1440px
Desktop	1440px - 1920px
LG Desktop	≥ 1920px

图标尺寸

屏幕尺寸	尺寸
Mobile/Desktop	< 1920px
LG Desktop	≥ 1920px

文本尺寸

主图标题 (imageTitle):

使用 <Heading size={3}> 组件
颜色: 白色 text-white

主图描述 (imageDescription):

使用 <Text size={2}> 组件
颜色: 白色 text-white

卡片标题 (item.title):

Mobile: 14px
LG Desktop: 18px
字重: font-semibold

卡片描述 (item.description):

Mobile: 20px
LG Desktop: 24px
行高: leading-tight

设计规范

主图文字叠加

主图上的文字采用绝对定位覆盖：


<div className="lg-desktop:p-8 absolute inset-0 z-[1] flex flex-col justify-end p-4">
  <Heading as="h3" className="text-white" size={3} html={imageTitle} />
  <Text as="p" className="text-white" size={2} html={imageDescription} />
</div>

关键点:

绝对定位: absolute inset-0 覆盖整个图片
底部对齐: justify-end 文字位于图片底部
内边距: 移动端 16px，大屏 32px
层级: z-[1] 确保文字在图片上方
颜色: 白色文字 text-white

形状变体

square (方形 - 默认):

无圆角，直角边框
适合正式、商务场景

rounded (圆角):

应用 rounded-box 类
具体圆角大小取决于 Tailwind 配置的 border-radius.box 值
适合友好、亲和场景

应用位置: 主图容器和所有卡片

图片源码配置


<Picture
  source={`${imageUrlPc?.url}, ${imageUrlMob?.url} 767`}
  className="inset-0"
  imgClassName="h-full object-cover"
  alt={imageUrlPc?.alt || ''}
/>

语法说明:

imageUrlPc?.url: 默认源（桌面端）
${imageUrlMob?.url} 767: 宽度 ≤ 767px 时使用移动端图片
object-cover: 图片填充容器，保持宽高比，裁剪溢出部分

注意: 如果只提供 imageUrlPc，移动端也会使用该图片。

卡片间距配置

主图与卡片的间距:

Mobile: 16px (mt-4)
Tablet+: 10px (tablet:mt-[10px])

卡片内部间距:

标题和描述之间: 48px (gap-12)
Desktop: 64px (desktop:gap-16)

无障碍性

语义化标签

✅ 使用 <section> 语义化标签
✅ 标题使用 <h3> 标签（通过 Heading 组件）
✅ 描述使用 <p> 标签（通过 Text 组件）
✅ 组件有唯一 ID: data-ui-component-id="GraphicAttractionBlock"

图片替代文本

✅ 所有图片必须提供 alt 属性（通过 Media 和 Img 类型强制）
✅ 主图 alt 应描述图片内容
✅ 图标 alt 应描述图标含义

建议改进

⚠️ 为 section 添加 aria-labelledby 关联章节标题
⚠️ 为主图文字容器添加 role="region"
⚠️ 确保文字颜色对比度符合 WCAG AA 标准（白色文字需要深色背景）

性能优化

✅ Ref 转发 - 使用 React.forwardRef() 支持 ref 转发
✅ 响应式图片 - Picture 组件自动实现响应式图片加载
✅ 图片优化 - 使用 object-cover 优化图片显示
✅ 条件渲染 - 减少不必要的 DOM 节点
✅ HOC 优化 - 使用 withLayout HOC 统一布局逻辑

常见问题

为什么主图在移动端和桌面端宽高比不同？

这是设计决策：

移动端 (358:480 ≈ 3:4): 竖屏比例，适合移动设备
桌面端 (1664:560 ≈ 3:1): 宽屏比例，充分利用桌面空间

如何只提供一张图片，在所有设备上使用？

只提供 imageUrlPc，不提供 imageUrlMob：


data={{
  imageUrlPc: {
    url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
    alt: 'Hero image',
  },
  // 不提供 imageUrlMob
}}

Picture 组件会自动将 PC 图片作为 fallback。

如何调整主图文字位置？

默认文字位于底部（justify-end）。如需修改，可以：

居中对齐: 修改为 justify-center
顶部对齐: 修改为 justify-start

注意: 需要修改组件源码。

卡片数量有限制吗？

如何自定义卡片背景色？

当前卡片背景色硬编码为 bg-white。如需自定义，可以通过 CSS 覆盖：


[data-ui-component-id="GraphicAttractionBlock"] > div > div > div {
  background-color: #f5f5f5 !important;
}

或直接修改组件源码。

章节标题使用 Title 组件，支持哪些功能？

章节标题通过 Title 组件渲染，支持：

滚动动画（GSAP SplitText）
倒计时功能
链接按钮

参考 Title 组件文档了解详细配置。

如何隐藏章节标题？

不传 sectionTitle 或设置为空字符串：


data={{
  sectionTitle: '',  // 或不传
  // ... 其他配置
}}

主图文字如何确保在深色/浅色背景上都清晰可见？

方案 1: 使用半透明遮罩（修改组件源码）


<div className="absolute inset-0 bg-black/50" />

方案 2: 使用文字阴影


.image-title {
  text-shadow: 0 2px 4px rgba(0, 0, 0, 0.5);
}

方案 3: 确保图片底部区域为深色

在设计图片时，保证底部区域为深色背景。