Birdor 工具页通用组件规格：输入区、输出区、按钮、错误提示、FAQ 与相关工具

本系列导航

• 上一篇：Birdor JWT Decoder 实现规格
• 下一篇：产品开发落地文档已完成，建议进入 JSON Formatter 和 JWT Decoder 代码实现。
• 返回目录：Birdor 商业计划书目录

本章关键词

工具页组件、输入区、输出区、操作按钮、错误提示、隐私提示、FAQ、相关工具、响应式布局、事件埋点。

适合阅读的人

• 准备实现 Birdor 工具页模板的工程师。
• 需要统一 JSON、JWT、Regex、Log 等工具体验的人。
• 想避免每个工具页重复造组件的人。

本章摘要

Birdor 如果要从几个工具扩展到 100+ 工具，就不能每个页面单独设计输入区、输出区、按钮、错误提示和 FAQ。通用组件规格的目标是让每个工具既保持一致体验，又允许根据任务类型扩展。

本文定义 Birdor 工具页通用组件，包括页面骨架、输入组件、输出组件、操作按钮、错误提示、隐私提示、FAQ、相关工具、指标和响应式布局。JSON Formatter 和 JWT Decoder 应优先使用这套规格，AI Regex 和 AI Log 在此基础上增加 AI 表单、成本提示和结构化报告。

页面骨架

通用工具页结构：

Workbench 是页面核心，必须在首屏可见。Content 是补充，不能干扰任务完成。

ToolHeader

字段：

规则：

• title 直接包含工具词。
• description 说明用户能完成什么。
• privacyNote 必须靠近工具区。
• 不要把营销口号放在首屏核心位置。

ToolInput

输入组件支持：

• textarea。
• code editor。
• key/value form。
• file input。
• structured form。

通用属性：

规则：

• 输入失败不能清空。
• 大输入要提示。
• 敏感工具要前置隐私提示。
• 移动端输入区要有足够高度。

ToolActions

按钮类型：

按钮状态：

• default。
• disabled。
• loading。
• success。
• error。

规则：

• primary action 只能有一个。
• 常用 secondary action 不要藏太深。
• Copy/Download 只有有输出时可用。
• loading 状态必须防止重复提交。
• AI action 要显示成本或额度边界。

ToolOutput

输出类型：

• code block。
• JSON viewer。
• table。
• report。
• split panels。
• claim cards。

通用属性：

规则：

• 输出为空时显示明确空状态。
• 输出要可复制。
• AI 报告要结构化，不展示不可控长文。
• 安全相关输出要显示提示。

ToolError

错误对象：

错误组件规则：

• 说明发生了什么。
• 给出下一步。
• 不暴露内部堆栈。
• 不清空输入。
• 可关联到输入位置时尽量高亮。

错误类型建议统一：

• empty_input。
• invalid_format。
• parse_error。
• too_large。
• unsupported。
• ai_failed。
• quota_exceeded。
• network_error。
• copy_failed。

PrivacyNote

隐私提示分三类：

规则：

• 本地工具要明确“不上传输入”。
• AI 工具要明确“会发送到服务器或模型”。
• 敏感工具要提示不要粘贴生产 secret。
• 隐私提示应靠近输入区，而不是只放 FAQ。

FAQ

FAQ 用于 SEO 和用户教育。每个工具至少包含：

• 这个工具做什么。
• 输入是否会上传。
• 常见错误原因。
• 和相关工具的区别。
• 是否有 API。
• 是否支持 Pro 或批量处理。

FAQ 不应写成泛泛概念。每个问题都要对应真实搜索意图或用户困惑。

RelatedTools

相关工具分三类：

规则：

• 每页 3-6 个高价值相关工具。
• 相关工具要说明下一步用途。
• 不要把所有工具都堆进去。
• 点击事件要记录。

响应式布局

桌面：

• 输入输出可双栏。
• 操作栏靠近输入区。
• 错误提示在输入和输出之间或下方。

移动端：

• 输入输出上下排列。
• 操作按钮可换行。
• 复制和清空按钮不遮挡输入。
• 长输出可滚动。

所有固定格式元素要有稳定尺寸，避免按钮状态、错误文案或动态输出导致布局跳动。

事件规范

通用事件：

• tool_input_start
• tool_primary_action
• tool_success
• tool_error
• tool_copy
• tool_download
• tool_sample
• tool_clear
• tool_related_click
• tool_pro_trigger

事件属性：

• tool_id。
• action。
• success。
• error_type。
• input_size_bucket。
• output_size_bucket。
• user_tier。

禁止记录：

• 原始输入。
• token。
• secret。
• payload 内容。
• AI prompt 原文中包含的敏感数据。

组件复用策略

第一阶段复用：

• JSON Formatter。
• JWT Decoder。
• Base64 Decoder。
• Timestamp Converter。

第二阶段扩展：

• AI Regex Generator。
• AI Log Analyzer。
• AI Config Generator。

AI 工具可以复用 ToolHeader、ToolInput、ToolActions、ToolError、RelatedTools、FAQ，但输出区需要扩展为结构化报告或测试结果。

验收标准

• JSON 和 JWT 能使用同一套基础组件。
• 工具页首屏可完成核心任务。
• 输入失败不清空。
• Copy、Sample、Clear 状态一致。
• 错误提示对象结构统一。
• 隐私提示位置一致。
• 相关工具可配置。
• 通用事件可复用。
• 移动端不出现遮挡和布局跳动。

延伸阅读

• Birdor JSON Formatter 实现规格
• Birdor JWT Decoder 实现规格
• 第三十二章：前端工具页架构
• Birdor 首批工程 Issue
• JSON Formatter PRD
• JWT Decoder PRD
• Birdor SEO 体系与关键词地图

AI 工具组件扩展

AI 增强工具在通用组件基础上需要以下扩展：

AI 工具的输出必须是结构化的。如果一个 AI 工具输出一段无法验证的长文，用户就不知道哪些部分可信。

组件版本管理

随着 Birdor 扩展，组件会演进。建议的版本策略：

工具配置中应声明组件版本要求，避免新工具使用旧组件的缺失功能。

国际化预留

虽然 Birdor 第一版以英文为主，但组件应预留国际化：

组件内部不硬编码中文或英文文案，而是通过 props 或 context 接收。这样新增语言时，只需要翻译文案文件，不需要修改组件代码。

工具页灰度发布

新工具或组件变更应支持灰度：

灰度期间应监控：工具完成率、错误率、Pro 触发率、用户反馈。

组件文档规范

每个组件应该有最小文档：

组件名: ToolInput
职责: 工具页输入区封装
Props: value, placeholder, maxLength, language, disabled, onChange, onPaste
状态: 支持 default, disabled, error, warning
事件: tool_input_start
示例: <ToolInput language="json" placeholder="粘贴 JSON..." />

组件文档的好处：新人可以快速理解组件边界；代码审查时有客观标准；测试用例可以直接从文档推导。

FAQ 补充

Q: 通用组件是否需要支持所有可能的工具类型？
不需要，也不可能。通用组件支持 80% 的工具类型即可。对于特殊工具（如图像处理、图表生成），允许使用自定义组件。关键是：自定义组件的数量应该 < 20%，如果超过这个比例，说明通用组件设计有缺陷。

Q: 组件级别的 A/B 测试怎么实现？
在工具配置中增加 variant 字段，前端根据 variant 渲染不同版本的组件。例如：

{ component: "ActionBar", variant: "v2_compact", experiment: "action_bar_redesign_2026" }

A/B 测试框架负责分流和指标收集，组件本身只负责根据 props 渲染。

Q: 移动端和桌面端是否可以共用同一套组件？
可以，但布局层需要响应式处理。建议：逻辑层（状态、事件、验证）完全共用；布局层（排列、尺寸、触摸目标）使用响应式策略；交互层（手势、长按、滑动）只在移动端启用。不要为移动端单独维护一套组件。

Q: 组件规范如何保证所有工具页都遵守？
三层保障：代码审查时检查是否符合规范；自动化测试验证组件使用是否合规（如"不允许直接操作 DOM"）；定期审计（每季度抽查 10% 的工具页）。最核心的是：组件库本身要足够好用，让工程师主动选择复用而不是重写。

Q: 未来如果引入设计系统（如 Figma 到代码），组件规格需要调整吗？
需要增加 Figma 组件和代码组件的映射关系。建议现在就在组件文档中标注对应的 Figma 组件名和变体（variant）。这样设计系统成熟时，可以直接对接。

组件性能优化策略

通用组件本身可能成为性能瓶颈。以下是优化建议：

SSR/SSG 适配要点

通用组件必须同时支持客户端和服务端渲染：

微前端拆分策略（远期）

当 Birdor 有 100+ 工具时，可以考虑微前端拆分：

微前端不是必选项。在 20-30 个工具阶段，单仓库 + monorepo 更高效。

组件复用率度量

建立组件复用率的度量机制：

如果新增一个工具需要超过 2 天开发时间，说明通用组件设计需要优化。

FAQ 补充（续）

Q: 组件库是否需要 Monorepo 管理？
建议先用 monorepo。20个工具以内，monorepo 的代码共享和一致性维护远优于多仓库。当团队超过 3 人且各子团队独立发版时，再考虑拆分为多仓库 + 内部 npm registry。

Q: 如何处理组件的向后兼容性？
使用语义化版本（SemVer）。破坏性变更升级主版本号（如 ToolInput v1 到 v2），新增功能升级次版本号。工具配置中声明所需组件版本，运行时检查兼容性。

Q: 组件是否需要支持无头模式（Headless）？
中期建议引入。无头组件（如 Radix UI 的模式）分离了逻辑和样式，允许不同工具有不同视觉风格，同时共享交互逻辑。但这要求先有稳定的设计系统，否则会增加复杂度。

Q: 如何确保组件在多语言环境下正常工作？
测试中增加 RTL（从右到左）布局验证。虽然 Birdor 初期可能不需要阿拉伯语/希伯来语支持，但 RTL 兼容的代码结构更健壮。关键是：不使用绝对定位依赖文字方向，不假设 label 在 input 的左侧。