加载中...
当前视口: 1920px × 600px场景: 三问题 FAQ
打开链接功能特性
- ✅ 折叠面板 - 问题默认折叠,点击展开查看答案
- ✅ 平滑动画 - 展开/折叠具有流畅的高度和透明度过渡效果
- ✅ 富文本支持 - 标题和描述均支持 HTML 富文本
- ✅ 图标动画 - 展开/折叠时图标自动旋转180度
- ✅ 响应式设计 - 不同屏幕尺寸下自动调整布局和字体大小
- ✅ 分隔线 - 每个问题之间自动添加分隔线
- ✅ 无障碍友好 - 支持键盘操作,具有明确的交互反馈
Props 参数
FaqProps
| Prop | 类型 | 默认值 | 必需 | 说明 |
|---|---|---|---|---|
data | FaqData | - | ✅ | FAQ 数据配置对象 |
className | string | '' | - | 自定义根容器类名 |
FaqData 配置
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
productData | FaqItem[] | ✅ | FAQ 问题列表 |
FaqItem 配置
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
title | string | ✅ | 问题标题(支持 HTML) |
desc | string | ✅ | 答案描述(支持 HTML) |
img | Img | ✅ | 关联图片(当前实现中未使用) |
使用示例
最简示例
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 | < 768px | 14px | 14px | 16px | 16px |
| Tablet | 768px - 1440px | 14px | 14px | 24px | 128px |
| Desktop | 1440px - 1920px | 16px | 16px | 24px | 128px |
| LG Desktop | ≥ 1920px | 18px | 18px | 24px | 128px |
动画时长
- 展开/折叠动画: 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,支持常见的富文本元素 (如 <strong>, <em>, <a>, <ul>, <ol> 等)。
如何自定义分隔线样式?
可以通过 className 传入自定义样式,或使用 CSS 覆盖 .border-[#E4E5E6] 类。
相关资源
- Storybook 文档 - 查看更多交互示例
- 完整 README 文档 - 详细的 API 文档和使用指南
- Figma 设计稿 - 查看设计规范
- 源代码 - GitHub 源代码
Last updated on