共享组件

相关源文件

• apps/portal/src/components/global/AppShell.tsx
• apps/portal/src/components/global/GlobalNavigation.ts
• apps/portal/src/components/global/GoogleAnalytics.tsx
• apps/portal/src/components/global/HomeNavigation.ts
• apps/portal/src/components/global/MobileNavigation.tsx
• apps/portal/src/components/global/ProductNavigation.tsx
• apps/portal/src/components/offers/OffersNavigation.tsx
• apps/portal/src/components/offers/forms/FormJobTitlesTypeahead.tsx
• apps/portal/src/components/questions/typeahead/CompanyTypeahead.tsx
• apps/portal/src/components/questions/typeahead/LocationTypeahead.tsx
• apps/portal/src/components/questions/typeahead/RoleTypeahead.tsx
• apps/portal/src/components/shared/CitiesTypeahead.tsx
• apps/portal/src/components/shared/CompaniesTypeahead.tsx
• apps/portal/src/components/shared/CountriesTypeahead.tsx
• apps/portal/src/components/shared/JobTitles.ts
• apps/portal/src/components/shared/JobTitlesTypeahead.tsx
• apps/portal/src/pages/test__.tsx
• apps/portal/src/types/index.d.ts
• apps/portal/src/utils/questions/relabelQuestionAggregates.ts

目的与范围

本文档提供了 Tech Interview Handbook 门户应用程序中使用的可重用共享组件的技术文档。这些组件是简历审查系统、优惠系统和问题库系统的构建块，可确保一致性并减少代码重复。有关系统特定组件的信息，请参阅简历审查系统、优惠系统和问题库系统的文档。

概述

此代码库中的共享组件分为几个类别：

1. 导航组件：负责应用程序布局和导航结构。
2. 类型ahead 组件：用于各种实体（公司、国家、城市、职位名称）的可重用搜索组件。
3. 分析组件：用于集成 Google Analytics 的组件。

下图显示了这些共享组件与门户应用程序中主要系统的关系。

来源：apps/portal/src/components/global/AppShell.tsx apps/portal/src/components/shared/CompaniesTypeahead.tsx apps/portal/src/components/shared/CountriesTypeahead.tsx apps/portal/src/components/shared/CitiesTypeahead.tsx apps/portal/src/components/shared/JobTitlesTypeahead.tsx apps/portal/src/components/global/GoogleAnalytics.tsx

导航组件

AppShell

AppShell 组件是整个门户应用程序的主布局包装器。它提供了：

1. 全局导航侧边栏
2. 移动响应式导航
3. 带有产品特定导航的标题
4. 用户个人资料下拉菜单
5. 与 Google Analytics 的集成

来源：apps/portal/src/components/global/AppShell.tsx133-250 apps/portal/src/components/global/ProductNavigation.tsx apps/portal/src/components/global/MobileNavigation.tsx apps/portal/src/components/global/GlobalNavigation.ts

AppShell 根据当前路由路径确定显示哪个产品导航，加载简历、优惠、问题或主页的相应导航项。对于优惠部分已登录用户，它还会检查用户是否具有管理员权限，并显示管理员特定的导航项。

ProductNavigation

ProductNavigation 组件在标题中渲染特定于产品的导航项。它同时处理简单的导航链接和带有子项的导航项的下拉菜单。

主要功能

• 渲染产品标题和徽标
• 支持嵌套导航和下拉菜单
• 突出显示活动导航项
• 支持带有适当图标的外部链接

来源：apps/portal/src/components/global/ProductNavigation.tsx25-117 apps/portal/src/components/global/MobileNavigation.tsx apps/portal/src/components/global/GlobalNavigation.ts

MobileNavigation

MobileNavigation 组件为移动设备提供响应式导航抽屉。它包含全局导航项和特定于产品的导航项。

来源：apps/portal/src/components/global/MobileNavigation.tsx20-136

导航配置

每个产品区域（简历、优惠、问题）都定义了自己的导航配置对象，该对象指定：

• 导航项（链接）
• 产品标题
• 产品徽标
• 是否显示全局导航侧边栏

例如，优惠导航配置

来源：apps/portal/src/components/offers/OffersNavigation.tsx1-48 apps/portal/src/components/global/HomeNavigation.ts

Typeahead 组件

门户应用程序包含多个可重用的类型ahead 组件，用于选择公司、国家、城市和职位名称等实体。这些组件遵循一致的实现模式，并在简历、优惠和问题系统中使用。

组件架构

来源：apps/portal/src/components/shared/CompaniesTypeahead.tsx apps/portal/src/components/shared/CountriesTypeahead.tsx apps/portal/src/components/shared/CitiesTypeahead.tsx apps/portal/src/components/shared/JobTitlesTypeahead.tsx

CompaniesTypeahead

CompaniesTypeahead 组件允许用户搜索和选择公司。它利用 useCompanyOptions hook 来根据用户输入获取公司数据。

主要功能

• 公司搜索及自动完成
• 允许选择一家公司或清除选择
• 正确格式化公司名称显示

使用示例

来源：apps/portal/src/components/shared/CompaniesTypeahead.tsx24-46 apps/portal/src/pages/test__.tsx42-45

CountriesTypeahead

CountriesTypeahead 组件允许用户搜索和选择国家。它使用 useCountryOptions hook 来获取国家数据。

主要功能

• 国家搜索及自动完成
• 支持排除特定国家
• 可选的自定义标签
• 可空的选项

使用示例

来源：apps/portal/src/components/shared/CountriesTypeahead.tsx26-51 apps/portal/src/pages/test__.tsx52-55

CitiesTypeahead

CitiesTypeahead 组件允许用户搜索和选择城市。它使用 useCityOptions 函数，该函数利用 tRPC API 来获取城市数据。

主要功能

• 城市搜索及自动完成
• 最小查询长度要求（3 个字符）
• 显示城市及其州和国家信息
• 可自定义标签

使用示例

来源：apps/portal/src/components/shared/CitiesTypeahead.tsx44-68 apps/portal/src/pages/test__.tsx57-58

JobTitlesTypeahead

JobTitlesTypeahead 组件允许用户从预定义列表中搜索和选择职位名称。它使用 useJobTitleOptions hook 根据用户输入过滤职位名称。

主要功能

• 职位名称搜索及自动完成
• 支持排除特定职位名称
• 可自定义标签和无结果消息
• 可空的选项

使用示例

该组件也用于特定场景，例如问题系统中的 RoleTypeahead 和优惠系统中的 FormJobTitlesTypeahead。

来源: apps/portal/src/components/shared/JobTitlesTypeahead.tsx27-53 apps/portal/src/components/shared/JobTitles.ts9-82 apps/portal/src/pages/test__.tsx47-50 apps/portal/src/components/questions/typeahead/RoleTypeahead.tsx apps/portal/src/components/offers/forms/FormJobTitlesTypeahead.tsx

专用 Typeahead 组件

除了通用的 Typeahead 组件外，在“问题”和“职位”系统中还有针对特定用例的专用版本

问题系统 Typeaheads

• RoleTypeahead：JobTitlesTypeahead 的专用版本，用于问题系统
• LocationTypeahead：用于问题系统中位置的专用 Typeahead
• CompanyTypeahead：CompanyTypeahead 的特定于问题的包装器

来源: apps/portal/src/components/questions/typeahead/RoleTypeahead.tsx apps/portal/src/components/questions/typeahead/LocationTypeahead.tsx apps/portal/src/components/questions/typeahead/CompanyTypeahead.tsx

职位系统 Typeaheads

• FormJobTitlesTypeahead：与 React Hook Form 集成的 JobTitlesTypeahead 版本

来源: apps/portal/src/components/offers/forms/FormJobTitlesTypeahead.tsx

Analytics 组件

GoogleAnalytics

GoogleAnalytics 组件为门户应用程序提供了 Google Analytics 集成。它

1. 设置 Google Analytics 跟踪脚本
2. 使用 Next.js 路由事件跟踪页面浏览量
3. 提供一个上下文，用于跟踪应用程序中任何位置的自定义事件

用途

• 该组件在 AppShell 中包装了整个应用程序
• 可以使用 `useGoogleAnalytics` hook 来跟踪自定义事件

该组件配置为仅在生产模式下发送分析数据，而在开发环境中不发送。

来源: apps/portal/src/components/global/GoogleAnalytics.tsx59-99 apps/portal/src/components/global/AppShell.tsx170

使用指南

与主要系统集成

在“简历”、“职位”或“问题”系统内构建新功能时，请利用这些共享组件来保持一致性

1. 选择实体时，请始终使用适当的 Typeahead 组件
2. 添加新页面时，请扩展您系统的导航配置
3. 使用 GoogleAnalytics 上下文来跟踪重要的用户操作

组件模式

此代码库中的共享组件遵循一致的模式

1. Typeahead 组件:

   • 接受 `value` 属性以显示当前选择
   • 提供 `onSelect` 回调以处理选择更改
   • 支持 `disabled`、`errorMessage` 等通用属性

2. 导航组件:

   • 使用 `href`、`name` 和可选的 `children` 定义导航项
   • 支持自定义徽标和标题
   • 自动处理响应式行为

遵循这些模式可确保整个应用程序的一致性，并使其更易于维护和扩展代码库。

来源: apps/portal/src/pages/test__.tsx35-95