批量操作
批量操作
相关源文件
本章引用的主要源码文件：
src-ui/e2e/document-list/document-list.spec.tssrc-ui/src/app/components/common/filterable-dropdown/filterable-dropdown.component.htmlsrc-ui/src/app/components/common/filterable-dropdown/filterable-dropdown.component.spec.tssrc-ui/src/app/components/common/filterable-dropdown/filterable-dropdown.component.tssrc-ui/src/app/components/common/filterable-dropdown/toggleable-dropdown-button/toggleable-dropdown-button.component.htmlsrc-ui/src/app/components/common/filterable-dropdown/toggleable-dropdown-button/toggleable-dropdown-button.component.scsssrc-ui/src/app/components/common/filterable-dropdown/toggleable-dropdown-button/toggleable-dropdown-button.component.spec.tssrc-ui/src/app/components/common/filterable-dropdown/toggleable-dropdown-button/toggleable-dropdown-button.component.tssrc-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.htmlsrc-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.spec.tssrc-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.tssrc-ui/src/app/components/document-list/filter-editor/filter-editor.component.htmlsrc-ui/src/app/components/document-list/filter-editor/filter-editor.component.scsssrc-ui/src/app/components/document-list/filter-editor/filter-editor.component.spec.tssrc-ui/src/app/components/document-list/filter-editor/filter-editor.component.tssrc-ui/src/app/data/filter-rule-type.tssrc-ui/src/app/pipes/filter.pipe.spec.tssrc-ui/src/app/pipes/filter.pipe.tssrc/documents/barcodes.pysrc/documents/bulk_edit.pysrc/documents/data_models.pysrc/documents/filters.pysrc/documents/serialisers.pysrc/documents/tests/test_api_bulk_edit.pysrc/documents/tests/test_api_custom_fields.pysrc/documents/tests/test_api_documents.pysrc/documents/tests/test_api_filter_by_custom_fields.pysrc/documents/tests/test_barcodes.pysrc/documents/tests/test_bulk_edit.pysrc/documents/tests/utils.pysrc/documents/views.pysrc/paperless/urls.py
本文档介绍了 Paperless-ngx 中的批量操作系统，该系统允许用户同时对多个文档执行各种操作。该功能可通过用户界面和 REST API 两种方式使用。
概述
Paperless-ngx 提供了一套全面的批量操作功能，可以高效管理文档集合。这些操作包括元数据编辑、标签管理、文档处理、PDF 操作和权限管理。
来源：src/documents/views.py:108-108, src/documents/bulk_edit.py:1-40, src-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.ts:80-83
支持的操作
批量操作在 src/documents/bulk_edit.py 中实现为专用函数，可以高效处理多个文档。
元数据操作
| 操作 | 描述 | 参数 | 实现 |
|---|---|---|---|
set_correspondent | 为多个文档设置通信方 | correspondent：ID 或 null | src/documents/bulk_edit.py:111-131 |
set_document_type | 为多个文档设置文档类型 | document_type：ID 或 null | src/documents/bulk_edit.py:156-173 |
set_storage_path | 为多个文档设置存储路径 | storage_path：ID 或 null | src/documents/bulk_edit.py:134-153 |
元数据更新使用 Django 的 .update() 方法以提高效率，然后触发 bulk_update_documents.apply_async 来刷新搜索索引和元数据缓存 src/documents/bulk_edit.py:126-129。
标签操作
| 操作 | 描述 | 参数 | 实现 |
|---|---|---|---|
add_tag | 为多个文档添加标签 | tag：标签 ID | src/documents/bulk_edit.py:176-202 |
remove_tag | 从多个文档中移除标签 | tag：标签 ID | src/documents/bulk_edit.py:205-221 |
modify_tags | 在一次操作中添加和移除标签 | add_tags：列表，remove_tags：列表 | src/documents/bulk_edit.py:224-239 |
add_tag 操作具有层级性；它会自动将所选标签的所有祖先标签添加到目标文档中 src/documents/bulk_edit.py:178-178。
自定义字段和权限操作
| 操作 | 描述 | 参数 | 实现 |
|---|---|---|---|
modify_custom_fields | 添加/更新和移除自定义字段 | add_custom_fields，remove_custom_fields | src/documents/bulk_edit.py:242-307 |
set_permissions | 设置所有者和对象级权限 | set_permissions，owner，merge | src/documents/bulk_edit.py:382-411 |
自定义字段操作会处理文档链接字段的对称性，确保如果文档 A 链接到文档 B，则文档 B 也会更新以链接回文档 A src/documents/bulk_edit.py:292-302。
PDF 操作
系统提供了多个强大的 PDF 操作功能，使用 pikepdf 库实现：
| 操作 | 描述 | 参数 | 实现 |
|---|---|---|---|
rotate | 以 90 度为增量旋转 PDF 文档 | degrees：(90, 180, 270) | src/documents/bulk_edit.py:414-444 |
merge | 将多个 PDF 合并为一个新文档 | metadata_document_id，delete_originals | src/documents/bulk_edit.py:447-508 |
split | 根据页面范围将 PDF 拆分为多个文档 | pages：范围列表 | src/documents/bulk_edit.py:511-576 |
delete_pages | 从 PDF 文档中删除特定页面 | pages：整数列表 | src/documents/bulk_edit.py:579-605 |
来源：src/documents/bulk_edit.py:414-605
接口
批量操作通过 BulkEditView 进行管理。
端点：POST /api/文档/bulk_edit/
此端点期望一个 JSON 载荷，包含文档 ID、方法名称以及方法特定的参数。
示例：合并文档
{
"documents": [10, 11, 12],
"method": "merge",
"parameters": {
"metadata_document_id": 10,
"delete_originals": true
}
}批量下载
BulkDownloadView 负责为多个文档生成 ZIP 归档文件。它支持不同的策略：
OriginalsOnlyStrategy：仅包含原始上传文件。ArchiveOnlyStrategy：仅包含 OCR 处理后的归档 PDF 版本。OriginalAndArchiveStrategy：ZIP 中包含两个版本。
来源：src/documents/views.py:109-111, src/paperless/urls.py:151-154
前端实现
批量操作的前端逻辑集中在 BulkEditorComponent 中。
BulkEditorComponent
该组件管理 DocumentListComponent 中文档的选择状态，并提供触发操作的界面。
- 权限检查：它会检查
userCanEditAll和userOwnsAll以启用或禁用特定的批量操作src-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.ts:129-151。 - 选择模型：它使用
FilterableDropdownSelectionModel来处理标签、通信方和文档类型，以便在批量编辑时支持多选过滤src-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.ts:99-103。
FilterableDropdownComponent
一个可复用的组件，批量编辑器使用它来显示元数据列表（标签等），并支持搜索和选择功能。
- 逻辑：它支持"包含"和"排除"交集用于过滤
src-ui/src/app/components/common/filterable-dropdown/filterable-dropdown.component.ts:52-55。 - 虚拟滚动：使用
cdk-virtual-scroll-viewport来高效处理大量标签或通信方src-ui/src/app/components/common/filterable-dropdown/filterable-dropdown.component.html:36-36。
来源：src-ui/src/app/components/document-list/bulk-editor/bulk-editor.component.ts:1-110, src-ui/src/app/components/common/filterable-dropdown/filterable-dropdown.component.ts:1-60
条码驱动的批量操作
Paperless-ngx 通过 BarcodePlugin 支持在消费阶段进行批量操作。这允许根据物理条码自动拆分文档或添加标签。
文档拆分
如果启用了 CONSUMER_ENABLE_BARCODE_SPLIT，BarcodePlugin 会检测"分隔符"条码。当检测到时，它会为原始文件的每个结果片段触发 tasks.consume_file 任务 src/documents/barcodes.py:183-210。
ASN 和标签分配
- ASN：检测与配置的 ASN 前缀匹配的条码，并将其分配给
archive_serial_number字段src/documents/barcodes.py:60-65。 - 标签：将条码值与
BARCODE_TAG_MAPPING进行匹配，以自动为文档应用标签src/documents/barcodes.py:68-80。
来源：src/documents/barcodes.py:41-80, src/documents/barcodes.py:183-215