3.3 · 用户接口系统（User Interface System）

用户接口系统

用户界面系统

相关源文件

本章引用的主要源码文件：

• mayan/apps/appearance/literals.py
• mayan/apps/appearance/settings.py
• mayan/apps/appearance/static/appearance/js/mayan_app.js
• mayan/apps/appearance/static/appearance/js/partial_navigation.js
• mayan/apps/appearance/templates/appearance/app/foot.html
• mayan/apps/appearance/templates/appearance/base.html
• mayan/apps/appearance/templates/appearance/base_plain.html
• mayan/apps/appearance/templates/appearance/generic_list_items_subtemplate.html
• mayan/apps/appearance/templates/appearance/generic_list_subtemplate.html
• mayan/apps/appearance/templates/appearance/partials/meta_tags.html
• mayan/apps/appearance/templates/appearance/root.html
• mayan/apps/common/menus.py
• mayan/apps/documents/templates/documents/invalid_document.html
• mayan/apps/navigation/classes.py
• mayan/apps/navigation/templatetags/navigation_tags.py
• mayan/apps/navigation/utils.py
• mayan/apps/redactions/templates/redactions/cropper.html
• mayan/apps/views/middleware/ajax_redirect.py

目的与范围

用户界面系统为 Mayan EDMS 提供基于 Web 的前端，实现了复杂的导航框架、基于 AJAX 的单页应用功能和动态内容渲染。该系统处理用户交互、菜单生成、链接解析、基于权限的导航和响应式列表视图。

关于 REST API 接口的信息，请参阅 REST API 架构。关于核心文档管理功能，请参阅 文档管理核心。

架构总览

UI 系统由多个相互连接的组件构建而成，这些组件协同工作以提供无缝的用户体验：

来源：mayan/apps/navigation/classes.py:1-979, mayan/apps/appearance/templates/appearance/base.html:1-119, mayan/apps/appearance/static/appearance/js/mayan_app.js:1-439

导航框架

核心类

导航系统围绕三个主要类构建，这些类处理链接定义、组织和解析：

来源：mayan/apps/navigation/classes.py:34-241, mayan/apps/navigation/classes.py:242-598, mayan/apps/navigation/classes.py:600-653, mayan/apps/navigation/classes.py:669-962

链接解析过程

链接经过多步解析过程，处理权限、条件和上下文：

来源：mayan/apps/navigation/classes.py:81-239

模板集成

导航菜单通过自定义模板标签集成到模板中：

来源：mayan/apps/navigation/templatetags/navigation_tags.py:8-78

AJAX 导航系统

PartialNavigation 类

PartialNavigation 类通过拦截点击和表单提交来实现单页应用行为：

来源：mayan/apps/appearance/static/appearance/js/partial_navigation.js:17-396

AJAX 请求流程

系统处理 AJAX 请求时包含限流、错误处理和重定向：

来源：mayan/apps/appearance/static/appearance/js/partial_navigation.js:87-152, mayan/apps/views/middleware/ajax_redirect.py:7-21

模板系统

基础模板结构

模板层级结构提供灵活的布局选项：

来源：mayan/apps/appearance/templates/appearance/root.html:1-71, mayan/apps/appearance/templates/appearance/base.html:1-119

模板中的菜单解析

模板使用特定的命名约定来解析菜单：

来源：mayan/apps/common/menus.py:7-24, mayan/apps/appearance/templates/appearance/base.html:35-56

JavaScript 应用层

MayanApp 类结构

主 JavaScript 应用协调 UI 行为和 AJAX 功能：

来源：mayan/apps/appearance/static/appearance/js/mayan_app.js:3-439

多项目选择系统

系统通过复选框选择支持批量操作：

来源：mayan/apps/appearance/static/appearance/js/mayan_app.js:367-420, mayan/apps/appearance/static/appearance/js/mayan_app.js:53-69

列表视图和源列

SourceColumn 系统

SourceColumn 类为列表视图提供动态列生成：

来源：mayan/apps/navigation/classes.py:669-962

列表视图模板

两个主要的列表视图模板处理不同的展示样式：

两个模板都支持：

• 多项目复选框选择
• 源列渲染
• facet 和对象操作菜单
• 使用 Bootstrap 类的响应式设计

来源：mayan/apps/appearance/templates/appearance/generic_list_subtemplate.html:1-188, mayan/apps/appearance/templates/appearance/generic_list_items_subtemplate.html:1-94

集成点

权限集成

导航系统在多个层级与 Mayan 的 ACL 系统集成：

# 链接级权限检查
AccessControlList.objects.check_access(
    obj=resolved_object,
    permissions=self.permissions,
    user=request.user
)

# 视图级权限检查
Permission.check_user_permissions(
    permissions=self.permissions,
    user=request.user
)

来源：mayan/apps/navigation/classes.py:110-125

模型集成

源列自动内省 Django 模型以获取标签和帮助文本：

# 自动标签解析
name, model = SourceColumn.get_attribute_recursive(
    attribute=self.attribute,
    model=self.source._meta.model
)
self._label = label_for_field(name=name, model=model)

来源：mayan/apps/navigation/classes.py:847-870

配置集成

系统遵循智能设置以进行行为定制：

来源：mayan/apps/appearance/settings.py:12-39, mayan/apps/appearance/templates/appearance/app/foot.html:31-63