Web 界面组件

概述

Stirling-PDF 的 Web 界面使用 Thymeleaf 模板、Bootstrap 进行样式设计以及自定义 JavaScript 实现客户端功能。UI 遵循基于组件的架构，可重用的片段被集成到不同的页面中。这些组件处理从用户导航、文件选择到主题管理和国际化的一切事务。

来源

导航栏是提供对应用程序工具和设置访问的关键组件。它实现在 navbar.html 中作为 Thymeleaf 片段，并包含在所有页面中。

来源

导航栏包含几个关键功能：

工具下拉菜单：提供对所有可用 PDF 工具的分类访问。
收藏夹菜单：快速访问用户保存的常用工具。
深色模式切换：在浅色和深色主题之间切换。
语言选择器：允许用户更改界面语言。
搜索：按名称、描述或标签查找工具。
设置：访问应用程序设置。

每个组件都使用自定义 CSS 进行样式设计，并使用 JavaScript 增强交互性。

文件选择组件

文件选择组件是用户界面的核心部分，提供增强的文件上传体验。

文件选择架构

来源

文件选择功能

文件选择组件提供诸如以下的高级功能：

拖放界面：用户可以将文件直接拖放到上传区域。
多文件支持：一次上传和处理多个文件的能力。
ZIP 文件提取：自动提取和处理 ZIP 压缩包中的文件。
PDF 密码处理：检测加密的 PDF 并提示输入密码。
文件验证：验证文件类型和大小。
视觉反馈：显示所选文件的缩略图和信息。
Google Drive 集成：Pro 版本允许直接从 Google Drive 选择文件。

文件输入通过 fileInput.js 进行自定义，该脚本会覆盖默认的浏览器文件输入行为，以提供更一致和功能更丰富的体验。

主页和工具卡片

主页（home.html）作为应用程序的主入口点，按类别显示可用的工具。

主页结构

来源

工具卡片组件

每个工具都由一个卡片组件表示，该组件提供有关工具的信息并链接到其页面。

来源

下载处理组件

下载处理组件（downloader.js）负责管理表单提交、文件处理请求和处理后的文件下载。

下载流程

来源

国际化系统

Stirling-PDF 通过广泛的国际化系统支持 39 种以上的语言。

国际化架构

来源

国际化系统使用 Thymeleaf 的消息表达式语法（#{key}）来引用翻译后的字符串。每种语言都有自己的属性文件，其中包含所有 UI 文本的键值对。该系统会检测用户的首选语言或使用存储在本地存储中的用户选择的语言。

主题系统

主题系统同时提供浅色和深色模式，并通过导航栏中的切换按钮进行控制。

主题架构

来源

主题系统使用 CSS 变量来定义颜色和样式，这些可以轻松地在浅色和深色模式之间切换。主题偏好存储在浏览器的本地存储中，并在页面加载时应用。该系统在所有 UI 组件中提供了一致的样式。

UI 组件注册表

下表列出了主要的重用 UI 组件。

组件名称	目的	位置	脚本依赖
导航栏	主导航	fragments/navbar.html	navbar.js, languageSelection.js
通用头部	通用的 HTML head 元素	fragments/common.html	fetch-utils.js, darkmode.js
文件选择器	文件选择界面	fragments/common.html:232-310	fileInput.js, DecryptFiles.js
工具卡片	工具表示	fragments/card.html	homecard.js
错误横幅	错误显示	fragments/errorBannerPerPage.html	-
设置模态框	应用程序设置	fragments/navbar.html:196-267	settings.js
功能组	工具类别容器	fragments/featureGroupHeader.html	-
语言条目	语言选择项	fragments/languageEntry.html	-

来源

工具页面结构

所有工具特定的页面都遵循一致的结构，以提供统一的用户体验。

来源

工具页面通过 GeneralWebController.java 和 OtherWebController.java 中的 Spring 控制器方法映射到特定的端点。每个控制器方法设置适当的视图名称，并在返回视图之前添加任何必要的模型属性。

与后端集成

Web 界面通过表单提交和 AJAX 请求与后端进行通信。

来源

集成通过 CSRF 令牌进行保护，这些令牌会自动添加到所有表单提交和 AJAX 请求中。downloader.js 脚本处理用于处理 PDF 文件的表单提交，而 fetch-utils.js 提供了用于向后端发送 AJAX 请求的实用程序。

企业版功能

UI 包含条件元素，这些元素仅在运行 Enterprise 或 Pro 版本时显示。

来源

Enterprise Edition 的功能通过 EEAppConfig.java 中定义的 Spring bean 来控制。这些 bean 使用 @{@beanName} 语法注入到 Thymeleaf 模板中，以根据安装的版本有条件地显示或隐藏 UI 元素。

Web 控制器结构

应用程序的 Web 控制器将 URL 映射到视图模板并提供模型数据。

来源

Web 控制器负责处理 HTTP 请求、准备模型数据并返回适当的视图模板。它们设置诸如 currentPage 等属性，该属性用于高亮活动导航项并为视图模板提供上下文。

总结

Stirling-PDF 的 Web 界面基于模块化组件架构构建，使用 Thymeleaf 模板，并在 UI 组件和后端功能之间实现强大的分离。主要 UI 组件包括：

导航栏：提供对工具和设置的访问。
文件选择：增强的文件上传，支持拖放和处理。
工具卡片：可用工具的视觉表示。
下载处理：管理文件处理和下载。
国际化：支持 39 种以上的语言。
主题系统：支持浅色和深色模式。

这些组件协同工作，为 PDF 操作任务提供了一个连贯且直观的用户体验。UI 的设计旨在响应性好、可访问且用户友好，同时提供对后端强大 PDF 处理功能的访问。