创建并运行您的第一个 Django 项目

启用 Django 插件

此功能依赖 Django 插件，该插件在 PyCharm 中默认已捆绑并启用。如果相关功能不可用，请确保您没有禁用该插件。

按 Ctrl+Alt+S 打开设置，然后选择插件。
打开已安装选项卡，找到 Django 插件，并选中插件名称旁的复选框。

在本教程中，我们将创建一个基础的待办应用。

开始之前

请确保满足以下先决条件：

您使用的是 PyCharm 2022.2 或更高版本。如果您尚未安装 PyCharm，请从此页面下载。要安装 PyCharm，请根据您的平台按照说明进行操作。

本教程基于以下假设：

Python 3.11
Django 4.2。

创建新项目

转到文件 | 新建项目，或在欢迎屏幕中点击新建项目按钮。将打开新建项目对话框。
在新建项目对话框中，执行以下操作：
- 指定项目类型 Django。
- 如有需要，更改默认项目位置。
- 保留默认的项目venv 解释器类型。
点击更多设置，然后在应用程序名称(A) 字段中指定 todo。
点击创建。

探索项目结构

新创建的项目包含特定于 Django 的文件和目录。

项目结构可在项目工具窗口（Alt+1 ）中查看：

myDjangoProject 目录是您项目的容器。以粗体显示。
内部目录 myDjangoProject 是您项目的实际 Python 包。
myDjangoProject/__init__.py ：这个空文件告诉 Python 此目录应被视为一个 Python 包。
myDjangoProject/settings.py ：此文件包含您的 Django 项目的配置。
myDjangoProject/urls.py ：此文件包含您的 Django 项目的 URL 声明。
myDjangoProject/wsgi.py ：此文件为兼容 WSGI 的 Web 服务器定义入口点，以便为您的项目提供服务。有关详细信息，请参阅如何使用 WSGI 部署。
templates 目录目前为空。它将包含 Django 模板。
内部目录 todo 包含开发 Django 应用所需的全部文件：
- 同样， todo/_init_.py 告诉 Python 此目录应被视为一个 Python 包。
- todo/models.py ：在此文件中，我们将创建模型。
- todo/views.py ：在此文件中，我们将创建视图。
内部目录 migrations 目前仅包含包文件 _init_.py ，但将来会用于将您对模型所做的更改（添加字段、删除模型等）传播到数据库架构中。在此处阅读迁移的说明。
manage.py 是一个命令行实用程序，可用于与您的 Django 项目交互。有关详细信息，请参阅 Django 文档。

启动 Django 服务器

Django 服务器运行/调试配置会自动创建。如有需要，您可以在主工具栏的运行/调试配置列表中选择编辑配置(E) 命令进行编辑：

例如，您可以选择在启动该配置时自动打开浏览器窗口：

点击运行 myDjangoProject 配置。如果未自动打开浏览器窗口，请在运行工具窗口中点击该链接。

将打开以下页面：

创建模型

Django 模型定义数据的字段和行为。它们由 Python 类表示，这些类是 django.db.models.Model 类的子类。

让我们为待办应用创建一个 ToDoItem 模型。为此，打开 todo/models.py ，并填入以下代码：

            from django.db import models
            from django.utils import timezone

            class ToDoItem(models.Model):
                text = models.CharField(max_length=100)
                due_date = models.DateField(default=timezone.now)

该模型具有两个由字段类实例表示的类变量：

text： CharField 类的一个实例，我们将用其存储需要完成事项的描述。
due_date： DateField 类的一个实例，我们将用其存储待办的截止日期。

有关模型字段的更多信息，请参阅 Django 文档。

运行迁移

默认情况下，PyCharm 会自动为 Django 项目创建一个 SQLite 数据库。我们需要在数据库中为 todo 应用和 ToDoItem 模型创建表。在 Django 中，这是通过使用迁移完成的。迁移是可人工编辑的文件，用于存储对数据模型的更改。

执行以下操作之一：
- 在主菜单中，转到工具 | 运行 manage.py 任务
- 按 Ctrl+Alt+R
- 打开终端（Alt+F12 ），在终端工具窗口的工具栏中点击 New Predefined Session ，然后选择 manage.py。
manage.py 实用程序会在一个终端选项卡中启动。
键入 makemigrations ，然后键入 Enter。
您应在控制台输出中看到 Process finished with exit code 0。现在， todo/migrations 目录包含迁移文件 0001_initial.py ：
键入 migrate 并按 Enter 以应用更改，并在数据库中为两个新模型创建表：

编写视图

Django 视图是用于指定如何处理 Web 请求以及返回哪些 Web 响应的函数或类。按照约定，视图定义在 <app_dir>/views.py 中，其中 <app_dir> 是 Django 应用目录。

打开 todo/views.py ，并填入以下代码：

            from django.views.generic import ListView
            from .models import ToDoItem

            class AllToDos(ListView):
                model = ToDoItem
                template_name = "todo/index.html"

这里我们定义了 AllToDos 类，它继承自 Django 的基础视图类 ListView。我们将使用此视图显示所有可用的待办。

创建模板

Django 模板本质上是一个包含 Django 模板语言元素的 HTML 文件。模板用于根据视图提供的上下文生成 HTML 页面。

您可以看到， views.py 中的 todo/index.html 被高亮为未解析的引用：

PyCharm 提供了一个快速修复：将鼠标悬停在 index.html 上或按 Alt+Enter ，您可以选择在 templates 文件夹中创建相应的模板文件：

PyCharm 还会创建此模板所在的目录 todo 。确认此操作：

PyCharm 会创建并打开 todo/index.html 。要填入一些基本的 HTML 代码，请键入 html:5 ，然后键入 Tab：

让我们向模板添加包含 Django 模板语言元素的内容。将以下代码粘贴到 body 标签之间：

                
                <h1>Things to do:</h1>
                <table>
                    {% for item in object_list %}
                    <tr>
                        <td>{{ item.text }}</td>
                        <td>{{ item.due_date }}</td>
                    </tr>
                    {% endfor %}
                </table>
                
            
  

这里有一个 h1 标题和一个表格。我们使用 for 循环遍历 object_list 的各项，这些项目将由 AllToDos 视图传入。对于每个项目，Django 会在表格中渲染一行，其中包含 text 和 due_date 的值。

配置 URL

现在需要配置如何在浏览器中访问 AllToDos 视图。

在 todo 目录中，创建文件 urls.py 并填入以下代码：
from django.urls import path from . import views urlpatterns = [ path("", views.AllToDos.as_view(), name="index") ]
接下来，打开文件 myDjangoProject/urls.py （PyCharm 已为您创建），并将其配置为包含来自 todo/urls.py 的路径。最终应得到以下代码：
from django.contrib import admin from django.urls import path, include urlpatterns = [ path("todo/", include("todo.urls")), path("admin/", admin.site.urls), ]
别忘了导入 django.urls.include！
在浏览器中打开页面 http://127.0.0.1:8000/todo/。您应看到以下文本：

有一个标题，但尚无待办。让我们使用 Django 管理站点界面添加任务。

使用 Django 管理站点

管理站点允许添加、编辑及以其他方式管理内容。默认情况下，PyCharm 会为新的 Django 项目自动启用 Django 管理站点界面。

设置管理站点

首先，我们需要创建一个超级用户。为此，请在 manage.py 控制台（Ctrl+Alt+R ）中键入 createsuperuser ，并指定您的电子邮件地址和密码。
现在转到您 Django 服务器上的 /admin/ ，例如 http://127.0.0.1:8000/admin/。您应看到以下登录页面：

登录后，将显示管理页面。其中有身份验证和授权（组和用户）部分，但还无法添加待办。为此，我们必须在管理站点界面中注册 ToDoItem 模型。

添加内容

打开文件 todo/admin.py ，并输入以下代码：
from django.contrib import admin from .models import ToDoItem admin.site.register(ToDoItem)
在浏览器中刷新页面。应出现包含待办事项的 TODO 部分：
点击添加创建一个待办：
准备就绪后，点击保存。

新创建的待办在列表中显示为 ToDoItem object (1)。这种命名会使内容管理变得复杂，因为您必须打开每个任务才能查看其描述。

我们通过在 ToDoItem 模型中添加一个 __str__() 方法来修复这一问题。打开 todo/models.py ，并添加以下内容：

                def __str__(self):
                    return f"{self.text}: due {self.due_date}"

最终应得到如下内容：

                from django.db import models
                from django.utils import timezone

                class ToDoItem(models.Model):
                    text = models.CharField(max_length=100)
                    due_date = models.DateField(default=timezone.now)

                    def __str__(self):
                        return f"{self.text}: due {self.due_date}"

现在，待办列表提供了所有必要信息：

提供功能

现在，既然您已经添加了一些待办，请再次转到 http://127.0.0.1:8000/todo/。此处应显示任务列表：

我们是否可以筛选，仅显示今天需要完成的任务？让我们为应用添加此功能。

转到 views.py ，添加 TodayToDos 类，并使用以下代码：

            class TodayToDos(ListView):
                model = ToDoItem
                template_name = "todo/today.html"

                def get_queryset(self):
                    return ToDoItem.objects.filter(due_date=date.today())
        
  

此类与 AllToDos 非常相似，不同之处在于它使用另一个模板（稍后我们会创建），并实现 get_queryset 方法，仅返回其 due_date 为今天的 ToDoItem 对象。

date 应以红色波浪线高亮显示。将鼠标悬停其上，点击导入此名称，并选择 datetime.date ，以在文件开头添加相应的 import 语句。

我们需要创建 today.html 模板。为避免从 index.html 复制粘贴并在项目中产生重复代码，我们将使用 Django 模板继承。

在 myDjangoProject/templates 中创建 base.html ：在项目工具窗口中右键点击 templates ，然后在上下文菜单中选择新建 | HTML 文件。
将 index.html 中的代码复制到 base.html ，然后将 <body> 标签之间的所有内容替换为以下内容：
{% block content %}{% endblock %}
myDjangoProject/templates/base.html 应如下所示：
<!doctype html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"> <meta http-equiv="X-UA-Compatible" content="ie=edge"> <title>Document</title> </head> <body> {% block content %}{% endblock %} </body> </html>
转到 index.html ，删除除 <h1> 和 <table> 标签内容之外的所有内容，然后按如下方式将其包裹在 Django 模板语言元素中：
{% extends "base.html" %} {% block content %} <h1>Things to do:</h1> <table> {% for item in object_list %} <tr> <td>{{ item.text }}</td> <td>{{ item.due_date }}</td> </tr> {% endfor %} </table> {% endblock %}
创建 myDjangoProject/templates/todo/today.html ，并填入以下代码：
{% extends "base.html" %} {% block content %} <h1>Things to do today:</h1> <table> {% for item in object_list %} <tr> <td>{{ item.text }}</td> </tr> {% endfor %} </table> {% endblock %}
请注意，此处不需要截止日期，因为此页面仅显示今天到期的待办。

我们已创建基础模板 base.html ，其中包含所有通用的 HTML 标签。 index.html 和 today.html 是子模板，它们继承公共元素，但具有特定内容。

我们还需要配置如何在浏览器中访问今日任务。转到 myDjangoProject/todo/urls.py ，将 path("today/", views.TodayToDos.as_view(), name="today") 添加到 urlpatterns 中，以获得以下结果：

            from django.urls import path
            from . import views

            urlpatterns = [
                path("", views.AllToDos.as_view(), name="index"),
                path("today/", views.TodayToDos.as_view(), name="today")
            ]
        
  

让我们确认一切按预期工作。转到 http://127.0.0.1:8000/admin/ ，添加几个待办，并将截止日期设为今天。然后转到 http://127.0.0.1:8000/todo/today/ ，确认您能看到新添加的待办：

改进体验

此时，我们的待办应用已经实现了其预期功能：

显示所有待办列表
显示今天需要完成的待办
允许通过 Django 管理站点界面添加新任务

但其外观不够美观，使用起来也不够便捷。让我们来改进它！

改进 HTML 页面外观的最简单方式是应用 CSS。例如，我们可以使用 Simple CSS。打开 base.html ，并在 <head> 标签之间的任意位置加入以下行：

在浏览器中转到 http://127.0.0.1:8000/todo/ ，查看我们应用的新外观：

由于我们使用的是基础模板， http://127.0.0.1:8000/todo/today/ 的外观也会随之改变：

现在，让我们添加一些导航元素，以免在浏览器地址栏中手动输入地址。在 base.html 中，将以下代码粘贴到起始 <body> 标签之后：

            
            <div>
                <a class="button" href='{% url "index" %}'>All tasks</a>
                <a class="button" href='{% url "today" %}'>Today</a>
            </div>

结果如下：

测试应用

您可能已经注意到，应用的 "全部任务" 页面上有一些待办的到期日是 5 月 12 日。这些任务实际上已过期，我们无需显示它们。在开发应用时引入测试可以避免此类疏漏。

在 myDjangoProject/todo 目录中，有 tests.py 文件。它用于 Django 测试。让我们编写一个测试，用于检查待办是否会根据其到期日在我们应用的主页上正确渲染：

            from datetime import date, timedelta

            from django.test import TestCase
            from django.urls import reverse
            from .models import ToDoItem


            def create_todo(todo_text, days):
                return ToDoItem.objects.create(text=todo_text, due_date=date.today() + timedelta(days=days))


            class AllToDosViewTest(TestCase):

                def test_today(self):
                    todo = create_todo("To be done today", 0)
                    response = self.client.get(reverse("index"))
                    self.assertQuerySetEqual(
                        response.context["todoitem_list"],
                        [todo]
                    )

                def test_last_week(self):
                    todo = create_todo("This task is past due", -7)
                    response = self.client.get(reverse("index"))
                    self.assertQuerySetEqual(
                        response.context["todoitem_list"],
                        []
                    )

                def test_next_week(self):
                    todo = create_todo("Still have some time", 7)
                    response = self.client.get(reverse("index"))
                    self.assertQuerySetEqual(
                        response.context["todoitem_list"],
                        [todo]
                    )

        
  

此处， create_todo 是用于创建待办的便捷函数， AllToDosViewTest 是一个包含 3 个方法的测试类： test_today、 test_last_week、 test_next_week。每个方法都会创建一个具有相应到期日的任务，然后检查该任务是否会在应用的主页上渲染。到期日早于当前日期 7 天的任务不应显示。

要运行此测试，在编辑器中右键点击文件 tests.py 的空白处，选择运行选项，或直接按 Ctrl+Shift+F10。

测试结果会显示在运行工具窗口的 Test Runner 选项卡中：

您可以看到， test_last_week 已失败，因为创建的待办尽管已过期，仍被添加到将在主页上显示的项目列表中。

让我们通过在 AllToDos 类中添加 get_queryset 方法来修复它：

            def get_queryset(self):
                return ToDoItem.objects.filter(due_date__gte=date.today())

该方法将筛选对象，使视图仅返回到期日大于或等于今天日期的任务（这就是 __gte 所表示的含义）。

在运行工具窗口的工具栏上点击以重新运行测试。现在所有测试均已成功通过：

总结

本教程到此结束。您已成功创建、启动并测试了一个简单的 Django 应用。让我们总结一下在 PyCharm 的帮助下您完成的内容：

创建了一个包含应用的 Django 项目
启动了 Django 服务器
创建了模型、视图和模板
配置了 URL
启动了应用
创建并执行了测试

最后修改日期： 2025年 12月 2日