django-spreadsheet

在导入之前验证您的XLSX电子表格文件。将您的数据导出为已设置数据验证的格式化XLSX电子表格。

需求

• Python 3.8+
• Django 2.0+

安装

• 运行 pip install django_spreadsheets
• 将 django_spreadsheets.apps.SpreadsheetAppConfig 添加到您的 INSTALLED_APPS
• 将 path("admin/spreadsheets/", include("django_spreadsheets.urls", namespace="spreadsheets")) 添加到您的根 urls.py
• 运行 python manage.py migrate django_spreadsheets

使用

在您的应用程序中创建一个名为 spreadsheets.py 的文件。在此文件中，描述您的电子表格配置，如下例所示

from django_spreadsheets.base_config import SpreadsheetConfig, SheetConfig
from django_spreadsheets.registry import register
from libs.bananas.models import Banana


class BananaSheetConfig(SheetConfig):
    """Describes each columns of this sheet."""

    ID = {
        "name": "Identifier",
        "required": True,
    }
    COLOR = {
        "name": "Color",
        "validation": {
            "type": "list",
            "formula1": ["yellow", "green", "brown"],
        },
        "required": True,
    }
    SIZE = {
      "name": "Size",
      "validation": {
          "type": "whole",
          "operator": "greaterThan",
          "formula1": 0,
          "error": "Please enter a positive number",
      }
    }

    def get_data_to_export(self):
        return Banana.objects.values_list("id", "color", "size")


@register
class BananaSpreadsheetConfig(SpreadsheetConfig):
    sheets_config = {
        "Banana": BananaSheetConfig()
        # the key will be used as the name of the sheet, the value is a class describing the sheet's configuration.
    }

    class Meta:
        verbose_name = "Bananas"

    def update_database(self, sheets):
        for sheet_name, rows in sheets.items():
            for row in rows:
                Banana.objects.get_or_create(
                  id=row["ID"],
                  color=row["COLOR"],
                  size=row["SIZE"],
                )

然后，您可以访问 //localhost:8000/admin/spreadsheets/export/ 来导出XSLX文件，以及 //localhost:8000/admin/spreadsheets/import/ 来将数据导入到数据库中。

SpreadsheetConfig 类

继承此类以描述您的电子表格配置。定义一个包含您的电子表格名称作为键和 SheetConfig 类作为值的 sheets_config 字典属性。

验证

在导入电子表格之前执行几个验证

配置版本验证

验证文件中存储的配置版本是否与使用的 SpreadsheetConfig.version 相同。

工作表验证

验证在此 SpreadsheetConfig 类中使用的所有工作表是否存在于导入的文件中。验证导入文件中的所有工作表是否存在于此 SpreadsheetConfig 类中使用的。

列标题验证

验证导入的文件包含与使用的 SheetConfig 中描述的相同的列标题。

所需数据验证

验证导入文件中每个 required、required_unless、required_if 列都存在值。

唯一性验证 [/!\ 未实现]

验证导入文件中一行中的多个单元格组合在一起是唯一的。

类型验证

验证导入文件中的每个列包含正确类型的数据（日期、正整数、...）。

数据匹配验证

验证我们在数据库中找到与导入文件中的值匹配的对象。如果没有，我们要求用户从可能的值列表中选择。

导入数据

如果您想从此电子表格将数据导入数据库，您需要定义一个 update_database(self, sheets) 方法。此方法在所有数据验证完成后被调用，并接收一个包含每个工作表的 python dict。键是工作表名称，值是包含每行的 python 列表。每行是一个包含每列值的列表。

def update_database(self, sheets):
    for sheet_name, rows in sheets.items():
        for row in rows:
            for value in row:
                print(value)

SheetConfig 类

继承此类来描述工作表的配置。每个属性使用如下字典描述一个列

<column_identifier> = {
  "name": str (required),  # The name of the column used in the header row
  "required": bool,  # Whether a value in the column is required when importing
  "required_unless": str,  # Whether a value in this column is required if the pointed column is empty
  "required_if": str,  # Whether a value in this column is required if the pointed column is filled
  "comment": str,  # A comment that appears in the header cell
  "admin_only": bool,  # Whether this column should be exported only when the current user is an administrator
  "validation": {  # A data validation applied to each cell of this column
    "name": str,  # A name used as header in the hidden config sheet
    "type": str (required),  # <url|date|list|range|whole...> See openpyxl documentation to get all available validation types
    ...  # Same args as openpyxl's DataValidation objects (operator, formula1, formula2, showErrorMessage, ...)
    ...  # Note that you can pass callables to `formula1` and `formula2` keys
  },
  "header_style": str,  # The name of a style that already exists in the SpreadsheetConfig to which this sheet belongs
  "style": str,  # The name of a style that already exists in the SpreadsheetConfig to which this sheet belongs
  "number_format": str # A value among FORMAT_* constants from openpyxl.styles.numbers or others values supported by XLSX spec
},

验证注意事项

要创建一个 布尔 验证，您可以使用具有 django_spreadsheets.constants.YES_NO_CHOICES 作为 formula1 值的 list 验证类型。为了确保布尔值在您的导出文件中显示，请在列配置中添加 "number_format": "BOOLEAN"。

键 formula1 和 formula2 接受可调用的值。

关于数字格式的说明

当您的导出文件中的值显示不正确或不一致时，您可以在列配置中定义 number_format 键。

openxpyxl 的格式常量不是详尽的。您可以使用其他受支持的字符串（例如："BOOLEAN"）。

导出数据

如果您想将数据导出到此工作表，您需要定义一个 get_data_to_export(self) 方法。此方法必须返回一个包含每行一个项目的 python 列表。列表中的每个项目都是一个包含每列值的列表。

def get_data_to_export(self):
  return [
    [1, "yellow", 20],
    [1, "green", 22],
  ]

设置

SPREADSHEETS_CONFIG_SHEET_TITLE

默认值：_("配置")

生成文件中（隐藏）配置工作表的名称。此特殊工作表用于存储用于验证的数据（例如：选择列表）。

SPREADSHEETS_MAX_VALIDATION_ROWS

默认值：700

当导出数据时，生成的电子表格将至少有 SPREADSHEETS_MAX_VALIDATION_ROWS 行设置了数据验证。

SPREADSHEETS_MAX_STYLED_ROWS

默认值：700

当导出数据时，生成的电子表格将至少有 SPREADSHEETS_MAX_STYLED_ROWS 行设置了样式。

SPREADSHEETS_COMMENT_AUTHOR

默认值："Django Spreadsheet"

在单元格上添加注释时使用的作者名称。

SPREADSHEETS_VALIDATION_LIST_REPLACEMENT_DELIMITER

默认值："/"

用于替换列表项中找到的 , 的分隔符，因为列表项中不允许出现 ,。

SPREADSHEETS_EXPORT_FILE_NAME

默认值："export {config_name} {date}.xlsx"

下载时导出文件的名称。令牌 config_name 和 date 分别由当前导出的配置名称和当前日期替换。

SPREADSHEETS_TEMPLATE_FILE_NAME

默认值："{config_name} template file.xlsx"

下载时模板文件的名称。令牌 config_name 将由当前导出的配置名称替换。