Skip to Content
@anker-in/headless-ui 2.0 is released 🎉

Faq (问答FAQ)

用于展示常见问题,支持折叠展开交互和平滑动画。【✅ 已发布】

加载中...
当前视口: 1920px × 600px场景: 三问题 FAQ
打开链接

功能特性

  • 折叠面板 - 问题默认折叠,点击展开查看答案
  • 平滑动画 - 展开/折叠具有流畅的高度和透明度过渡效果
  • 富文本支持 - 标题和描述均支持 HTML 富文本
  • 图标动画 - 展开/折叠时图标自动旋转180度
  • 响应式设计 - 不同屏幕尺寸下自动调整布局和字体大小
  • 分隔线 - 每个问题之间自动添加分隔线
  • 无障碍友好 - 支持键盘操作,具有明确的交互反馈

Props 参数

FaqProps

Prop类型默认值必需说明
dataFaqData-FAQ 数据配置对象
classNamestring''-自定义根容器类名

FaqData 配置

参数类型必需说明
productDataFaqItem[]FAQ 问题列表

FaqItem 配置

参数类型必需说明
titlestring问题标题(支持 HTML)
descstring答案描述(支持 HTML)
imgImg关联图片(当前实现中未使用)

使用示例

最简示例

import { Faq } from '@anker-in/headless-ui/biz' import scenarios from './scenarios.json' <Faq data={{ productData: [ { title: 'What is your return policy?', desc: 'You can return any product within 30 days of purchase for a full refund.', img: { url: 'https://images.unsplash.com/photo-...', alt: 'Return Policy', }, }, { title: 'How long does shipping take?', desc: 'Standard shipping takes 5-7 business days. Express shipping is available for 2-3 days.', img: { url: 'https://images.unsplash.com/photo-...', alt: 'Shipping', }, }, ], }} />

基础 FAQ 展示

<Faq data={{ productData: [ { title: 'What is your return policy?', desc: 'You can return any product within 30 days of purchase for a full refund.', img: { url: 'https://images.unsplash.com/photo-...', alt: 'Return Policy', }, }, { title: 'How long does shipping take?', desc: 'Standard shipping takes 5-7 business days. Express shipping is available for 2-3 days.', img: { url: 'https://images.unsplash.com/photo-...', alt: 'Shipping', }, }, { title: 'Do you offer international shipping?', desc: 'Yes, we ship to over 50 countries worldwide. Shipping costs and times vary by destination.', img: { url: 'https://images.unsplash.com/photo-...', alt: 'International Shipping', }, }, ], }} />

带富文本的 FAQ

<Faq data={{ productData: [ { title: '<strong>How do I track my order?</strong>', desc: ` <p>You can track your order by:</p> <ol> <li>Visiting the <a href="/orders">Order Tracking page</a></li> <li>Entering your order number and email</li> <li>Click "Track Order"</li> </ol> `, img: { url: 'https://images.unsplash.com/photo-...', alt: 'Order Tracking', }, }, ], }} />

自定义样式

<Faq data={{ productData: faqList, }} className="max-w-4xl mx-auto py-12 px-4" />

响应式行为

断点说明

组件在不同设备上的样式调整:

断点屏幕宽度标题字体描述字体垂直间距标题与图标间距
Mobile< 768px14px14px16px16px
Tablet768px - 1440px14px14px24px128px
Desktop1440px - 1920px16px16px24px128px
LG Desktop≥ 1920px18px18px24px128px

动画时长

  • 展开/折叠动画: 300ms
  • 图标旋转动画: 300ms
  • 透明度过渡: 300ms

所有动画均使用 CSS transition 实现,确保流畅性。

设计规范

视觉样式

  • 分隔线: 每个问题之间有 1px 的灰色分隔线 (#E4E5E6)
  • 标题颜色: 主要文本色 (text-info-primary)
  • 描述颜色: 次要文本色 (text-info-secondary)
  • 图标颜色: 深色 (#1D1D1F)

交互反馈

  • 悬停效果: 鼠标悬停时显示手型光标
  • 展开状态: 图标旋转180度,内容平滑展开
  • 折叠状态: 图标复位,内容平滑收起

内容要求

问题标题:

  • 简洁明了,建议10-50个字符
  • 使用疑问句形式 (What, How, Why 等)
  • 可使用 HTML 格式化 (如加粗、斜体)

答案描述:

  • 清晰准确,建议50-300个字符
  • 可包含列表、链接等 HTML 元素
  • 避免过长内容 (建议最多500px高度)

无障碍性

键盘支持

  • ✅ 使用语义化标签和明确的层级结构
  • ✅ 支持键盘操作 (Tab 键切换焦点,Enter 键展开/折叠)
  • ✅ 图标动画提供明确的状态反馈
  • ✅ 支持富文本中的链接导航

颜色对比度

  • ✅ 文字颜色对比度符合 WCAG AA 标准
  • ✅ 分隔线颜色 (#E4E5E6) 符合可访问性标准
  • ✅ 图标颜色 (#1D1D1F) 对比度足够

建议改进

  • 添加 aria-expanded 属性标识展开状态
  • 添加 aria-controls 关联问题和答案
  • 添加 role="button" 明确可交互区域

性能优化

  • Ref 转发 - 使用 React.forwardRef() 支持 ref 转发
  • Ref 优化 - 使用 useImperativeHandle() 优化 ref 暴露
  • 状态管理 - 使用 useState 管理局部状态,避免全局重渲染
  • CSS 动画 - CSS 动画优于 JavaScript 动画,性能更优
  • 独立状态 - 单个组件状态独立,一个问题的展开不影响其他问题

常见问题

为什么 img 字段是必需的但没有显示?

当前实现中 img 字段虽然在类型定义中是必需的,但在视觉上并未渲染。这可能是为未来功能预留的字段 (如显示问题相关图标或缩略图)。建议填写占位图片数据。

可以同时展开多个问题吗?

可以。每个问题的展开/折叠状态是独立管理的,用户可以同时打开多个问题查看答案。

如何设置默认展开某个问题?

当前组件不支持默认展开状态配置。所有问题默认都是折叠状态。如需此功能,可以修改 FaqItem 组件,添加 defaultOpen 属性。

答案内容高度有限制吗?

为了动画流畅,展开状态的最大高度被限制为 500px (max-h-[500px])。如果答案内容超过此高度,会出现截断。建议将超长内容拆分为多个问题。

支持嵌套的富文本样式吗?

支持。组件使用 Text 组件渲染 HTML,支持常见的富文本元素 (如 &lt;strong&gt;, &lt;em&gt;, &lt;a&gt;, &lt;ul&gt;, &lt;ol&gt; 等)。

如何自定义分隔线样式?

可以通过 className 传入自定义样式,或使用 CSS 覆盖 .border-[#E4E5E6] 类。

相关资源

Last updated on