在 Django 应用中高效导入 Excel 数据到模型

聖光之護

发布时间：2025-11-29 12:15:01

290人浏览过

来源于php中文网

原创

在 django 应用中高效导入 excel 数据到模型

本教程详细指导如何在 Django 应用中实现 Excel 文件的数据导入功能。通过利用 `openpyxl` 库处理上传的 Excel 文件，并将其内容批量写入 Django 模型，文章将涵盖从前端表单设计到后端视图逻辑的完整实现步骤，旨在提供一个结构清晰、易于理解的专业指南，帮助开发者高效管理大量数据录入。

在企业级应用中，批量数据导入是常见的需求，尤其是在需要将现有数据从电子表格迁移到数据库时。Django 框架配合 openpyxl 这样的第三方库，可以轻松实现从 Excel 文件导入数据到数据库模型的功能。本教程将详细介绍如何构建这一功能。

1. 环境准备

首先，确保你的 Django 项目已经安装并配置好。要处理 Excel 文件，我们需要安装 openpyxl 库：

pip install openpyxl

2. 定义 Django 模型

假设我们有一个 Product 模型，用于存储计算机的相关信息。这是我们将要导入数据的目标模型：

# your_app/models.py
from django.db import models
from django.utils import timezone

class Product(models.Model):
    model = models.CharField(max_length=50, null=True)
    serial = models.CharField(max_length=50, null=True)
    hd_size = models.CharField(max_length=50, null=True)
    ram = models.CharField(max_length=50, null=True)
    processor = models.CharField(max_length=50, null=True)
    date_created = models.DateTimeField(default=timezone.now)
    date_updated = models.DateTimeField(auto_now=True)

    def __str__(self):
        return f"{self.serial} - {self.model}"

3. 创建数据导入视图

数据导入的核心逻辑将实现在一个 Django 视图函数中。这个视图负责接收上传的 Excel 文件，解析其内容，并将数据保存到 Product 模型中。

# your_app/views.py
import openpyxl
from django.shortcuts import render, redirect
from django.contrib.auth.decorators import login_required # 如果需要登录才能访问

from .models import Product

@login_required
def import_product(request):
    """
    处理 Excel 文件上传并导入产品数据。
    """
    if request.method == 'POST':
        # 确保请求中包含文件
        if 'excel_file' not in request.FILES:
            return render(request, 'your_app/import_product.html', {'error': '请选择一个文件上传。'})

        excel_file = request.FILES['excel_file']

        # 检查文件类型，这里可以进一步细化，例如检查MIME类型
        if not excel_file.name.endswith('.xlsx') and not excel_file.name.endswith('.xls'):
            return render(request, 'your_app/import_product.html', {'error': '请上传 Excel 文件 (.xlsx 或 .xls)。'})

        try:
            # 加载工作簿
            wb = openpyxl.load_workbook(excel_file)
            ws = wb.active # 获取活动工作表

            # 遍历工作表中的每一行，从第二行开始（假设第一行是标题）
            # values_only=True 可以直接获取单元格的值
            imported_count = 0
            for row in ws.iter_rows(min_row=2, values_only=True):
                # 解包行数据到对应的模型字段
                # 确保 Excel 列的顺序与这里解包的变量顺序一致
                if len(row) >= 5: # 确保行有足够的列
                    model, serial, hd_size, ram, processor = row[:5] # 取前5列

                    # 创建 Product 实例并保存
                    Product.objects.create(
                        model=model,
                        serial=serial,
                        hd_size=hd_size,
                        ram=ram,
                        processor=processor
                    )
                    imported_count += 1
                else:
                    # 可以添加日志或错误处理，记录哪些行数据不完整
                    print(f"Skipping incomplete row: {row}")

            return render(request, 'your_app/import_success.html', {'imported_count': imported_count})

        except Exception as e:
            # 捕获文件解析或数据库保存过程中的错误
            return render(request, 'your_app/import_product.html', {'error': f'文件处理失败: {e}'})

    # GET 请求时显示上传表单
    return render(request, 'your_app/import_product.html')

def import_success(request):
    """
    显示导入成功的页面。
    """
    return render(request, 'your_app/import_success.html')

注意事项：

Cardify卡片工坊

使用Markdown一键生成精美的小红书知识卡片

下载

@login_required: 如果你的导入功能只允许登录用户使用，请添加此装饰器。
request.FILES['excel_file']: 用于获取上传的文件。excel_file 对应前端表单中 input 标签的 name 属性。
openpyxl.load_workbook(excel_file): 加载上传的 Excel 文件。
ws.iter_rows(min_row=2, values_only=True): 迭代工作表中的行。min_row=2 表示从第二行开始读取，跳过表头。values_only=True 确保直接获取单元格的值。
数据解包：model, serial, hd_size, ram, processor = row 要求 Excel 文件中的列顺序与模型字段的顺序严格匹配。请确保你的 Excel 文件第一列是 model，第二列是 serial，以此类推。
错误处理：增加了基本的错误捕获，例如文件类型检查和通用异常处理。在实际应用中，你可能需要更详细的错误报告和日志记录。

4. 创建前端上传表单

用户需要一个界面来上传 Excel 文件。这通常是一个包含文件输入字段和提交按钮的 HTML 表单。

<!-- your_app/templates/your_app/import_product.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>导入产品数据</title>
    <style>
        body { font-family: sans-serif; margin: 20px; background-color: #f4f4f4; color: #333; }
        .container { max-width: 600px; margin: 0 auto; background-color: #fff; padding: 30px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); }
        h1 { color: #0056b3; text-align: center; margin-bottom: 30px; }
        form { display: flex; flex-direction: column; gap: 15px; }
        input[type="file"] { border: 1px solid #ccc; padding: 10px; border-radius: 4px; background-color: #f9f9f9; }
        button { background-color: #007bff; color: white; padding: 12px 20px; border: none; border-radius: 5px; cursor: pointer; font-size: 16px; transition: background-color 0.3s ease; }
        button:hover { background-color: #0056b3; }
        .error-message { color: red; text-align: center; margin-top: 20px; font-weight: bold; }
        .go-back-button { display: block; width: fit-content; margin: 20px auto 0; padding: 10px 15px; background-color: #6c757d; color: white; border-radius: 5px; text-decoration: none; text-align: center; transition: background-color 0.3s ease; }
        .go-back-button:hover { background-color: #5a6268; }
    </style>
</head>
<body>
    <div class="container">
        <h1>导入产品数据</h1>

        {% if error %}
            <p class="error-message">{{ error }}</p>
        {% endif %}

        <p>请选择一个包含产品数据的 Excel 文件 (.xlsx 或 .xls) 进行导入。</p>
        <form method="post" enctype="multipart/form-data">
            {% csrf_token %}
            <input type="file" name="excel_file" accept=".xlsx, .xls" required>
            <button type="submit">导入</button>
        </form>

        <a href="javascript:history.back()" class="go-back-button">返回</a>
    </div>
</body>
</html>

关键点：

enctype="multipart/form-data": 这是上传文件必不可少的属性，它告诉浏览器表单将发送二进制数据。
{% csrf_token %}: Django 的跨站请求伪造保护。
name="excel_file": 这个 name 属性的值必须与视图函数中 request.FILES['excel_file'] 的键名一致。
accept=".xlsx, .xls": 这是一个客户端提示，建议用户选择 Excel 文件。但服务器端仍需进行验证。

5. 创建导入成功页面

导入成功后，我们通常会跳转到一个页面，告知用户操作已完成。

<!-- your_app/templates/your_app/import_success.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>导入成功</title>
    <style>
        body { font-family: sans-serif; margin: 20px; background-color: #f4f4f4; color: #333; }
        .container { max-width: 600px; margin: 0 auto; background-color: #fff; padding: 30px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); text-align: center; }
        h1 { color: #28a745; margin-bottom: 20px; }
        p { font-size: 1.1em; line-height: 1.6; }
        .button-group { margin-top: 30px; }
        .button-group a { display: inline-block; padding: 10px 20px; margin: 0 10px; background-color: #007bff; color: white; text-decoration: none; border-radius: 5px; transition: background-color 0.3s ease; }
        .button-group a:hover { background-color: #0056b3; }
        .button-group .back-button { background-color: #6c757d; }
        .button-group .back-button:hover { background-color: #5a6268; }
    </style>
</head>
<body>
    <div class="container">
        <h1>数据导入成功！</h1>
        {% if imported_count %}
            <p>成功导入了 <strong>{{ imported_count }}</strong> 条产品记录。</p>
        {% else %}
            <p>产品数据已成功导入。</p>
        {% endif %}
        <div class="button-group">
            <a href="{% url 'import_product' %}" class="back-button">继续导入</a>
            <a href="{% url 'product_list' %}">查看产品列表</a> {# 假设你有一个产品列表页面 #}
        </div>
    </div>
</body>
</html>

6. 配置 URL 路由

最后，将视图函数映射到 URL。

# your_app/urls.py
from django.urls import path
from . import views

urlpatterns = [
    # ... 其他 URL 模式 ...
    path('products/import/', views.import_product, name='import_product'),
    path('products/import/success/', views.import_success, name='import_success'),
    # path('products/', views.product_mgt, name='product_list'), # 假设你有一个产品列表视图
]

7. 进阶考虑与优化

数据验证： 在 Product.objects.create() 之前，可以对从 Excel 读取的数据进行更严格的验证，例如检查数据类型、非空约束、唯一性等。可以使用 Django Forms 或自定义验证逻辑。
批量创建： 对于大量数据，使用 Product.objects.bulk_create(list_of_product_objects) 可以显著提高性能，减少数据库查询次数。你需要先收集所有要创建的对象到一个列表中，然后一次性提交。
更新现有记录： 如果 Excel 文件可能包含现有记录的更新，你需要实现“更新或创建”（UPSERT）逻辑。例如，根据 serial 字段查找现有产品，如果存在则更新，否则创建新产品。
```
# 示例：更新或创建
product, created = Product.objects.update_or_create(
    serial=serial,
    defaults={'model': model, 'hd_size': hd_size, 'ram': ram, 'processor': processor}
)
```
错误报告： 详细记录并向用户反馈导入过程中遇到的具体错误，例如哪些行数据有问题、错误原因等。
异步处理： 对于非常大的 Excel 文件（例如包含数万行），在请求-响应周期内处理可能会导致超时。可以考虑使用 Celery 等异步任务队列来在后台处理文件导入。
用户界面反馈： 在导入过程中提供加载动画或进度条，提升用户体验。
文件存储： 如果需要长期保存上传的 Excel 文件，可以将其存储到 Django 的 MEDIA_ROOT 目录下。
更通用的导入工具： 对于更复杂的导入需求（例如映射不同的列名、支持多种文件格式），可以考虑使用 django-import-export 等第三方库，它们提供了更强大的配置和管理功能。

总结

通过本教程，你已经学会了如何在 Django 应用中实现一个基本的 Excel 文件导入功能。这包括设置必要的库、定义模型、编写处理文件上传和解析的视图逻辑，以及创建用户交互的前端表单。通过对数据验证、批量操作和错误处理的进一步优化，你可以构建一个健壮且高效的数据导入系统，极大地提升数据管理的便利性。

Flutter 页面中动态显示的输入框自动化点击与文本输入教程

如何阻止表单提交导致的页面跳转（Route 变更）

Flask Fetch 响应解析错误：正确提取 JSON 数据并安全渲染到页面

如何从网页中安全提取并解析嵌入的 JavaScript JSON 数据

如何从网页脚本中安全提取并解析嵌入的 JSON 数据