发布说明

v4.2

• 通过 admin action 导出时，现在会在 get_queryset() 上过滤查询集，而不是模型的默认查询集。这不会对现有实现产生影响。

  此更改还使 get_valid_export_item_pks() 过时，因为可以使用 ModelAdmin 的 get_export_queryset() 或 ModelAdmin 的 get_queryset 替代。get_valid_export_item_pks() 方法现已弃用。

  参见 PR 1890。

• 移除了内部方法 _get_enabled_export_fields()，改为将选中的字段列表作为新参数传递给 export_resource() 和 get_export_headers()。

• 当“Resource”表单仅有一个选项时隐藏它，以避免界面中出现可能令人困惑的文本，例如“Resource: BookResource”。要撤销此更改，请使用一个表单子类，将该字段的小部件更改为 django.forms.Select。 参见 1908

• tablib 已从 v3.5.0 升级至 3.6.1。此次升级移除了 tablib 对 MarkupPy 的依赖，转而使用 ElementTree。如果您导出为 HTML，此变更可能会影响输出格式，特别是当您已对文本中的 HTML 字符进行转义时。

  见 issue 1627。

重大变更

• 此版本修复了在v4中引入的回归问题。从v4.2开始，数字、布尔值和日期/时间控件以原生值形式写入电子表格格式（ODS、XLS、XLSX）。这是v3中的默认行为。参见:ref:文档<modify_render_return_type>。

  这意味着传递给 Widget 的 coerce_to_string 值在从 Admin 界面导出为电子表格格式时现在会被忽略。

  如果你子类化了 Widget、Field 或 Resource，那么你可能需要调整代码以包含 **kwargs 参数，如下所示：

上一个	新
Widget.render(self, value, obj=None)	Widget.render(self, value, obj=None, **kwargs)
字段.导出(self, 实例)	字段.导出(self, 实例, **kwargs)
资源.导出字段(self, 字段, 实例)	资源.导出字段(self, 字段, 实例, **kwargs)
资源.导出资源(self, 实例, selected_fields=None)	资源.导出资源(self, 实例, selected_fields=None, **kwargs)

v4.1

Resource.get_fields() 方法不再在包内调用，已被弃用。如果您已覆盖此方法，则应将其移除。

v4.0

v4 对导入-导出功能进行了重大更新。我们借此机会引入了一些破坏性变更，以修复一些长期存在的问题。

参考 更新日志 获取更多信息。请确保在将 v4 部署到生产环境之前进行全面测试。

本指南描述了主要变更以及如何升级。

安装

我们修改了安装方法以支持可选依赖项。这意味着在安装import-export时您必须显式声明依赖项。

如果不确定，或希望保留v4之前的行为，请确保按以下方式安装import-export（无论是在requirements文件中还是安装过程中）:

django-import-export[all]

功能变更

CharWidget

构造函数参数在实例化过程中根据底层Django db CharField的属性动态设置。如果db字段的`blank <https://docs.djangoproject.com/en/stable/ref/models/fields/#blank>`_设置为True，则传入的空字符串或null值将存储为空字符串。参见 CharWidget。

clean() 现在默认返回字符串类型。v3 版本引入的 coerce_to_string 选项在此方法中不再使用。

验证错误消息

以下小部件已更新验证错误消息：

• DateWidget

• TimeWidget

• DateTimeWidget

• DurationWidget

导出格式

我们标准化了从:meth:`~import_export.widgets.Widget.render`返回的导出输出。

在v4之前，从``render()``返回的导出格式因Widget实现而异。在v4中，返回值默认渲染为字符串（适用时），``None``值返回为空字符串。Widget参数可以修改此行为。

这会导致导出到Excel时发生变化。在v3中，某些字段（如数值）以其原生类型呈现。在v4中，所有字段现在都以字符串形式呈现。要在导出到Excel时保留v3的行为，请将``coerce_to_string``参数设置为``False``。参见:ref:documentation<modify_render_return_type>。

Widget API 文档。

导出字段顺序

导出字段的排序规则已标准化。参见 文档。

错误输出

如果 import_data() 的 raise_errors 参数为 True，则会抛出一个 ImportError 实例。该异常封装了底层异常。

查看 此PR。

检查 import_id_fields

在v4版本之前，我们遇到许多问题，用户因数据集中未声明``import_id_fields``导致导入失败而感到困惑。我们在v4中添加了功能来检查这一点，并抛出更清晰的错误信息。

在某些用例中，要求 import_id_fields 不在数据集中，而是动态生成。如果这影响了您的实现，请从文档 这里 开始。

弃用

• 传递给 render() 的 obj 参数已被弃用。render() 方法不应需要引用模型实例。从 export() 调用 render() 的操作已被移除。

• 使用 ExportViewFormMixin 已被弃用。参见 此问题。

• 参见 重命名的方法。

• 在Admin UI中，``resource_class``的声明被``resource_classes``取代:

  class BookAdmin(ImportExportModelAdmin):
    # remove this line
    # resource_class = BookResource
    # replace with this
    resource_classes = [BookResource]
  

管理界面

日志条目

LogEntry 实例在导入过程中为创建、更新和删除操作而创建。存储 LogEntry 的功能在 v4 中已更改，以解决 Django 5 中的弃用问题。为了正确实现此功能，删除的实例现在始终被复制并保留在每个 RowResult 中，以便它们可以在每个 LogEntry 中被记录。

这仅发生在从Admin UI发起的删除操作中。

导出操作

导出操作已更新以包含导出工作流。在v4之前，可以选择使用导出管理员操作来导出所选项目。然而这意味着跳过了导出工作流，并且无法选择导出资源。此问题已在v4中修复，因此现在通过Admin UI操作导出时会显示导出工作流。更多信息请参阅 导出文档。

导出选定字段

导出 '确认' 页面 现在包含可选择的导出字段。如果您希望恢复到之前（v3版本）的导出确认界面，请在您的 Admin 类子类中添加 export_form_class 声明，例如:

class BookAdmin(ImportExportModelAdmin):
  export_form_class = ExportForm

成功消息

成功导入时显示的成功消息已更新，包含“deleted”和“skipped”行的数量。参见 this PR。

导入错误消息

导入错误的默认错误消息已修改以简化格式。错误消息现在默认仅包含错误消息。行数和回溯信息不再显示。

可以通过在Admin类定义上设置`:attr:`~import_export.admin.ImportMixin.import_error_display`来恢复原始格式。例如:

class BookAdmin(ImportExportModelAdmin):
  import_error_display = ("message", "row", "traceback")

查看 此问题。

API变更

import-export 的 v4 版本包含对 API 的多项更改。这些更改在下表中进行了总结。详细信息请参考 此 PR。

如果您通过重写方法自定义了导入-导出功能，那么在使用v4之前可能需要修改您的安装。

如果您没有重写任何方法，那么您不应受到这些更改的影响，也不需要更改您的代码。

API 变更包括对方法参数的更改，尽管某些方法名称已更改。

处理行数据的方法已更新，以使方法参数标准化。这样做是为了解决因方法调用间参数不同而导致的不一致问题，并允许更轻松的扩展性。

import_export.resources.Resource

重命名的方法

上一个	新	摘要
import_obj(self, obj, data, dry_run, **kwargs)	导入实例(self, instance, row, **kwargs)	obj 参数重命名为 instance data 参数重命名为 row dry_run 参数现在在 kwargs 中
after_import_instance(self, instance, new, row_number=None, **kwargs)	after_init_instance(self, instance, new, row, **kwargs)	row 添加为必填参数 row_number 现在在 kwargs 中

参数更改

本节描述参数已更改的方法。

上一个	新	摘要
before_import(self, dataset, using_transactions, dry_run, **kwargs)	before_import(self, dataset, **kwargs)	using_transactions 参数现在位于 kwargs 中 dry_run 参数现在在 kwargs 中
after_import（self，dataset，result，using_transactions，dry_run，**kwargs）	after_import(self, dataset, result, **kwargs)	using_transactions 参数现在位于 kwargs 中 dry_run 参数现在在 kwargs 中
before_import_row(self, row, row_number=None, **kwargs)	before_import_row(self, row, **kwargs)	row_number 现在在 kwargs 中
after_import_row(self, row, row_result, row_number=None, **kwargs)	after_import_row(self, row, row_result, **kwargs)	row_number 现在在 kwargs 中
导入行(self, 行, 实例加载器, 使用事务=True, 模拟运行=False, **kwargs)	导入行(self, 行, 实例加载器, **kwargs)	dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
save_instance(self, instance, is_create, using_transactions=True, dry_run=False)	save_instance(self, instance, is_create, row, **kwargs)	dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中 row 添加为必填参数
save_m2m(self, obj, data, using_transactions, dry_run)	save_m2m(self, instance, row, **kwargs)	row 添加为必填参数 obj 重命名为 instance data 重命名为 row dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
before_save_instance(self, instance, using_transactions, dry_run)	before_save_instance(self, instance, row, **kwargs)	row 添加为必填参数 dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
after_save_instance（self, instance, using_transactions, dry_run）	after_save_instance(self, instance, row, **kwargs)	row 添加为必填参数 dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
delete_instance(self, instance, using_transactions=True, dry_run=False)	delete_instance(self, instance, row, **kwargs)	row 添加为必填参数 dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
before_delete_instance(self, instance, dry_run)	before_delete_instance(self, instance, row, **kwargs)	row 添加为必填参数 dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
after_delete_instance(self, instance, dry_run)	after_delete_instance(self, instance, row, **kwargs)	row 添加为必填参数 dry_run 参数现在在 kwargs 中 using_transactions 参数现在位于 kwargs 中
导入字段(self, field, obj, data, is_m2m=False, **kwargs)	导入字段(self, field, instance, row, is_m2m=False, **kwargs):	obj 重命名为 instance data 重命名为 row
before_export(self, queryset, *args, **kwargs)	before_export(self, queryset, **kwargs)	未使用的 *args 列表已移除
after_export(self, queryset, data, *args, **kwargs)	after_export(self, queryset, dataset, **kwargs)	未使用的 *args 列表已移除 data 重命名为 dataset
filter_export（self，queryset，*args，**kwargs）	filter_export（self，queryset，**kwargs）	未使用的 *args 列表已移除
导出字段(self, 字段, obj)	导出字段(self, 字段, 实例)	obj 重命名为 instance
导出资源(self, obj)	导出资源（self，实例，字段=None）	obj 重命名为 instance 作为kwarg传递的``fields``
导出(self, *args, queryset=None, **kwargs)	导出(self, queryset=None, **kwargs)	未使用的 *args 列表已移除
get_export_headers(self)	get_export_headers(self, fields=None)	作为kwarg传递的``fields``

import_export.mixins.BaseImportExportMixin

参数更改

上一个	新	摘要
get_resource_classes(self)	get_resource_classes(self, request)	添加了 request 参数
get_resource_kwargs(self, request, *args, **kwargs)	get_resource_kwargs(self, request, **kwargs)	未使用的 *args 列表已移除

import_export.mixins.BaseImportMixin

参数更改

上一个	新	摘要
get_import_resource_kwargs(self, request, *args, **kwargs)	get_import_resource_kwargs(self, request, **kwargs)	未使用的 *args 列表已移除
get_import_resource_classes(self)	get_import_resource_classes(self, request)	添加了 request 参数
选择导入资源类(self, form)	选择导入资源类(self, form, request)	添加了 request 参数

import_export.mixins.BaseExportMixin

参数更改

上一个	新	摘要
get_export_resource_classes(self)	get_export_resource_classes（self，request）	添加了 request 参数
get_export_resource_kwargs(self, request, *args, **kwargs)	get_export_resource_kwargs(self, request, **kwargs)	未使用的 *args 列表已移除
获取导出数据(self, request, queryset, *args, **kwargs)	获取导出数据(self, request, queryset, **kwargs)	未使用的 *args 列表已移除
选择_导出_资源_类(self, form)	选择_导出_资源_类(self, form, request)	添加了 request 参数

import_export.fields.Field

参数更改

上一个	新	摘要
clean(self, data, **kwargs)	clean(self, row, **kwargs)	data 重命名为 row
get_value(self, instance)	get_value(self, obj)	obj 重命名为 instance
保存(self, obj, data, is_m2m=False, **kwargs)	保存（self, instance, row, is_m2m=False, **kwargs）	obj 重命名为 instance data 重命名为 row
导出(self, obj)	导出(self, instance)	obj 重命名为 instance

import_export.forms.ImportExportFormBase

如果你已经子类化了 forms 中的一个类，那么你可能需要修改传递给构造函数的参数。

input_format 字段已从 ImportForm 移至父类 (ImportExportFormBase) 并重命名为 format。

ExportForm 的 file_format 字段已被移除，现替换为 format。

参数更改

上一个	新	摘要
__init__(self, *args, resources=None, **kwargs)	__init__(self, 格式, 资源, **kwargs)	formats 被添加为必选参数 resources 被添加为必选参数 未使用的 *args 列表已移除