ARSVINE DOCS
  • 简体中文

      • 组件架构

      Realm 的组件分布在 components/ 下 10 个子目录中，约 50 个文件。本节按目录列出每个组件的实际用途。

      layout/ — 布局骨架

      组件文件职责
      MainLayoutMainLayout.tsx全局布局根组件。组合 LeftPanel、GlobalHud，动态导入 TesseractExperience / RainMorimeEffect / CustomCursor（均 ssr: false），挂载 HomeLoadingScreen、RouteLoadingOverlay、MusicPlayer，注册 scroll anchor，处理 content hash 导航
      GlobalHudGlobalHud.tsx顶部 HUD 装饰栏（时钟等）
      LeftPanelLeftPanel.tsx左侧导航面板
      NavigationColumnsNavigationColumns.tsx首页 5 个主导航列
      RouteLoadingOverlayRouteLoadingOverlay.tsx路由过渡 loading 覆盖层
      SectionPageLayoutSectionPageLayout.tsx章节页通用布局容器

      effects/ — WebGL 与视觉效果

      组件文件职责
      TesseractTesseract.tsxSVG 回退版 tesseract（桌面端）
      TesseractExperienceTesseractExperience.tsx交互式 3D tesseract（@react-three/cannon 物理引擎，桌面端专属）
      RainMorimeEffectRainMorimeEffect.tsx大气雨粒子效果（10000+ 粒子）
      NoiseNoise.tsx噪点覆盖层

      interactive/ — 交互组件

      组件文件职责
      MusicPlayerMusicPlayer.tsx + music-player/ 子目录 + .module.scss全功能音乐播放器
      CustomCursorCustomCursor.tsx + customCursorShared.ts自定义光标，支持 contextual label（如 BACK）
      LightboxLightbox.tsx图片灯箱
      ActivationLeverActivationLever.tsx + .module.scss拉杆按钮，语义上必须是 <button>

      sections/ — 内容聚合页的各段

      组件文件
      AboutSectionsections/AboutSection.tsx
      BlogSectionsections/BlogSection.tsx
      ContactSectionsections/ContactSection.tsx
      ExperienceSectionsections/ExperienceSection.tsx
      LifeSectionsections/LifeSection.tsx
      TweetsSectionsections/TweetsSection.tsx
      WorksSectionsections/WorksSection.tsx

      detail/ — 详情页视图

      组件文件
      WorkDetailViewdetail/WorkDetailView.tsx
      ExperienceDetailViewdetail/ExperienceDetailView.tsx
      LifeDetailViewdetail/LifeDetailView.tsx
      StandalonePanelStatedetail/standalone/ 子目录

      blog/ — 博文系统

      组件文件职责
      BlogDetailScaffoldblog/BlogDetailScaffold.tsx博文详情页脚手架
      BlogStateShellblog/BlogStateShell.tsx博文状态机外壳
      ProtectedPostGateblog/ProtectedPostGate.tsx受保护博文 TOTP 门禁

      cards/ — 卡片

      组件文件
      ProjectCardcards/ProjectCard.tsx
      SimpleImageCardcards/SimpleImageCard.tsx

      mdx/ — MDX 渲染组件

      组件文件职责
      MDXComponentsmdx/MDXComponents.tsx自定义 MDX 组件映射
      Termmdx/Term.tsxruby 注释（proper noun / 缩写 / 短注）
      Explainmdx/Explain.tsxtooltip / 移动端底部 sheet，长句注

      shared/ — 共享 UI 组件

      组件文件职责
      AnimatedTitleCharsshared/AnimatedTitleChars.tsx动画标题字符（默认 uppercase，博文必须传 uppercase={false}）
      HomeLoadingScreenshared/HomeLoadingScreen.tsx首页加载序列
      LoadingScreenshared/LoadingScreen/ 子目录加载屏幕
      HreflangLinksshared/HreflangLinks.tsxSEO hreflang 标签
      LanguageSwitchershared/LanguageSwitcher.tsx语言切换器
      LazyImageshared/LazyImage.tsx懒加载图片
      LocaleFallbackBannershared/LocaleFallbackBanner.tsx缺译提示横幅
      NotFoundViewshared/NotFoundView.tsx404 视图
      ShinyTextshared/ShinyText.tsx光泽文字效果
      VerticalShinyTextshared/VerticalShinyText.tsx纵向光泽文字
      SkillTreeshared/SkillTree.tsx技能树可视化
      Timelineshared/Timeline.tsx时间线组件

      telemetry/ — 遥测

      组件文件职责
      TelemetryRoottelemetry/TelemetryRoot.tsx遥测根组件，按 env 决定是否挂载
      VercelTelemetrytelemetry/VercelTelemetry.tsx@vercel/analytics + @vercel/speed-insights 集成

      组件层次

      _app.tsx
  └─ NextIntlClientProvider
       └─ SiteAssetsProvider
            └─ AppProvider
                 └─ TransitionProvider
                      └─ MainLayout
                           ├─ LeftPanel
                           ├─ GlobalHud
                           ├─ [dynamic] TesseractExperience / RainMorimeEffect / CustomCursor
                           ├─ HomeLoadingScreen
                           ├─ RouteLoadingOverlay
                           └─ [page content]
                                ├─ NavigationColumns (home)
                                ├─ SectionPageLayout (章节页)
                                │   └─ AboutSection / BlogSection / ...
                                └─ DetailView (详情页)
                                     └─ BlogDetailScaffold
                                          ├─ BlogStateShell
                                          └─ ProtectedPostGate

      关键约束

      • Three.js 组件（TesseractExperience、RainMorimeEffect）全部动态导入 + ssr: false，一旦 webglReady 不再卸载以避免 GPU context 重建（GOTCHAS #20）
      • CustomCursor 的 hover 状态必须走 reset helper，不能直接动内部 ref（GOTCHAS #12）
      • ActivationLever 语义上必须是 <button>，不能改为 <div>（GOTCHAS #15）
      • AnimatedTitleChars 默认 uppercase，博文标题必须显式传 uppercase={false}（GOTCHAS #17）
      • navigateTo() 是唯一受支持的内部导航方式，router.push() 跳过过渡动画（GOTCHAS #6）