2 · 前端架构（Frontend Architecture）

前端架构

前端架构

本文档记录了 Paperless-ngx 基于 Angular 的前端架构。内容包括核心结构、组件组织、状态管理、路由、样式设计以及应用中使用的响应式布局模式。

关于特定 UI 子系统的信息，请参考以下子页面：

• 核心 UI 组件 —— AppFrame、全局搜索和主题系统。
• 文档列表与筛选 —— 文档列表、筛选和批量编辑。
• 仪表盘与设置 —— 仪表盘组件以及用户/系统设置。
• 文档详情视图 —— 元数据编辑和文档预览。
• 通用 UI 组件与服务 —— 可复用的输入组件、对话框和工具服务。

概述

Paperless-ngx 前端使用 Angular 21 构建为单页应用（SPA）src-ui/package.json:15-22。它提供了用于管理文档的响应式界面，功能包括文档查看、元数据编辑、搜索、筛选和管理。应用通过 REST API src-ui/src/environments/environment.prod.ts:5 与 Django 后端通信，并通过 WebSocket 获取实时状态更新 src-ui/src/environments/environment.prod.ts:10-12。

Paperless-ngx · 概述 · 图 1

来源：src-ui/src/app/components/app-frame/app-frame.component.ts:77-80，src-ui/package.json:13-41

核心结构

应用遵循标准的 Angular 架构。在最顶层，AppFrameComponent src-ui/src/app/components/app-frame/app-frame.component.ts:77 提供了主要的布局结构，包括导航栏、侧边栏和主内容区域。

AppFrame 组件

AppFrameComponent 是主要的布局容器。它包含以下部分：

1. 顶部导航栏：包含应用 Logo、GlobalSearchComponent src-ui/src/app/components/app-frame/app-frame.component.html:28、用户资料下拉菜单和 ToastsDropdownComponent src-ui/src/app/components/app-frame/app-frame.component.html:35。
2. 侧边栏导航：管理指向仪表盘、文档列表、已保存视图和管理页面的链接 src-ui/src/app/components/app-frame/app-frame.component.html:82-125。
3. 主内容区域：一个 router-outlet，用于渲染页面特定的组件 src-ui/src/app/components/app-frame/app-frame.component.html:357。

Paperless-ngx · AppFrame 组件 · 图 2

来源：src-ui/src/app/components/app-frame/app-frame.component.html:1-358，src-ui/src/app/components/app-frame/app-frame.component.ts:81-91

响应式布局

前端使用 Bootstrap 5 src-ui/package.json:27 适配不同屏幕尺寸。

• 移动端（<768px）：侧边栏折叠为可切换的菜单 src-ui/src/app/components/app-frame/app-frame.component.scss:43-64。
• 桌面端：侧边栏支持"精简"模式（仅显示图标），用户可切换该模式 src-ui/src/app/components/app-frame/app-frame.component.ts:149-172。

来源：src-ui/src/app/components/app-frame/app-frame.component.scss:87-157，src-ui/src/styles.scss:39-64

状态管理与服务

前端采用基于服务的状态管理方式：

• OpenDocumentsService：跟踪当前正在编辑的文档，防止数据丢失，并允许在文档标签页之间快速切换 src-ui/src/app/services/open-documents.service.ts:32。
• SettingsService：管理用户特定的 UI 偏好设置，例如主题、侧边栏状态和显示名称 src-ui/src/app/services/settings.service.ts:1。
• PermissionsService：使用 IfPermissionsDirective 指令实施 UI 级别的访问控制，根据用户角色隐藏或显示元素 src-ui/src/app/directives/if-permissions.directive.ts:1。
• SavedViewService：管理用户定义的筛选视图的检索和文档计数更新 src-ui/src/app/services/rest/saved-view.service.ts:1。

来源：src-ui/src/app/components/app-frame/app-frame.component.ts:81-91，src-ui/src/app/services/open-documents.service.ts:12-40

样式与主题

应用使用 Sass（SCSS）和 Bootstrap 5 进行样式设计。

主题系统

Paperless-ngx 支持浅色和深色主题，以及自定义主色调。

• CSS 变量：主题由 theme.scss 中定义的 CSS 变量驱动 src-ui/src/theme.scss:8-33。
• 深色模式：通过 @mixin dark-mode 实现，该混入会覆盖标准的 Bootstrap 变量和自定义变量，以呈现深色界面 src-ui/src/theme.scss:75-227。
• 主色调：默认使用"Paperless 绿"，但通过 HSL 变量计算得出，便于调整 src-ui/src/theme.scss:2-6。

来源：src-ui/src/theme.scss:1-352，src-ui/src/styles.scss:1-133

国际化（i18n）

应用使用 Angular 内置的国际化支持进行本地化：

• 模板：对静态文本使用 i18n 属性 src-ui/src/app/components/app-frame/app-frame.component.html:18。
• 代码：在 TypeScript 中对字符串使用 $localize 标签模板字面量 src-ui/src/app/components/app-frame/app-frame.component.ts:164。
• 构建：前端会编译为多种语言版本，后端根据用户设置提供正确的版本。

来源：src-ui/src/app/components/app-frame/app-frame.component.ts:160-168，src-ui/package.json:19

构建与部署

前端使用 Angular CLI 进行编译 src-ui/package.json:53。在生产环境中，它会被构建为静态文件，并由 Django 后端提供服务。

• Docker：Dockerfile 使用多阶段构建，其中 compile-frontend 阶段会运行 pnpm install 和 ng build 命令 Dockerfile:8-27。
• 环境：生产构建使用 environment.prod.ts，该文件配置了 API 基础 URL 和 WebSocket 设置 src-ui/src/environments/environment.prod.ts:1-13。

来源：Dockerfile:8-28，src-ui/package.json:4-11