为admin.py添加详细注释（文章、标签等模型的后台配置）

djangoblog/src/DjangoBlog-master/DjangoBlog-master/blog/admin.py

@@ -1,38 +1,60 @@
+# 导入Django表单模块，用于创建自定义表单
 from django import forms
+# 导入Django admin模块，用于注册模型到后台管理系统
 from django.contrib import admin
+# 导入获取用户模型的函数，用于处理作者关联
 from django.contrib.auth import get_user_model
+# 导入reverse函数，用于生成URL
 from django.urls import reverse
+# 导入format_html，用于在admin中生成HTML代码
 from django.utils.html import format_html
+# 导入国际化工具，用于翻译后台显示文本
 from django.utils.translation import gettext_lazy as _
 
-# Register your models here.
+# 导入当前应用的Article模型
 from .models import Article
 
 
 class ArticleForm(forms.ModelForm):
-    # body = forms.CharField(widget=AdminPagedownWidget())
+    """
+    自定义文章表单，用于在admin中自定义文章的编辑界面
+
+    可以在这里添加自定义字段验证、 widgets 或修改表单行为
+    目前注释掉了pagedown编辑器的配置，如需使用可取消注释
+    """
+
+    # body = forms.CharField(widget=AdminPagedownWidget())  # 富文本编辑器配置
 
     class Meta:
-        model = Article
-        fields = '__all__'
+        model = Article  # 关联的模型
+        fields = '__all__'  # 包含模型的所有字段
 
 
+# 自定义批量操作：发布选中的文章
 def makr_article_publish(modeladmin, request, queryset):
+    # 将选中文章的状态更新为'p'(published)
     queryset.update(status='p')
 
 
+# 自定义批量操作：将选中的文章设为草稿
 def draft_article(modeladmin, request, queryset):
+    # 将选中文章的状态更新为'd'(draft)
     queryset.update(status='d')
 
 
+# 自定义批量操作：关闭选中文章的评论
 def close_article_commentstatus(modeladmin, request, queryset):
+    # 将选中文章的评论状态更新为'c'(closed)
     queryset.update(comment_status='c')
 
 
+# 自定义批量操作：开启选中文章的评论
 def open_article_commentstatus(modeladmin, request, queryset):
+    # 将选中文章的评论状态更新为'o'(open)
     queryset.update(comment_status='o')
 
 
+# 为批量操作设置显示名称（支持国际化）
 makr_article_publish.short_description = _('Publish selected articles')
 draft_article.short_description = _('Draft selected articles')
 close_article_commentstatus.short_description = _('Close article comments')
@@ -40,73 +62,128 @@ open_article_commentstatus.short_description = _('Open article comments')
 
 
 class ArticlelAdmin(admin.ModelAdmin):
-    list_per_page = 20
-    search_fields = ('body', 'title')
-    form = ArticleForm
+    """
+    文章模型的Admin配置类，自定义文章在后台的显示和操作方式
+    """
+    list_per_page = 20  # 每页显示20条记录
+    search_fields = ('body', 'title')  # 可搜索的字段
+    form = ArticleForm  # 使用自定义的表单
+    # 列表页显示的字段
     list_display = (
-        'id',
-        'title',
-        'author',
-        'link_to_category',
-        'creation_time',
-        'views',
-        'status',
-        'type',
-        'article_order')
+        'id',  # 文章ID
+        'title',  # 标题
+        'author',  # 作者
+        'link_to_category',  # 分类（带链接）
+        'creation_time',  # 创建时间
+        'views',  # 浏览量
+        'status',  # 状态
+        'type',  # 类型（文章/页面）
+        'article_order'  # 排序序号
+    )
+    # 列表页可点击跳转编辑的字段
     list_display_links = ('id', 'title')
+    # 可筛选的字段（右侧过滤器）
     list_filter = ('status', 'type', 'category')
+    # 多对多字段的水平选择器
     filter_horizontal = ('tags',)
+    # 编辑页排除的字段（这些字段通常自动生成，不需要手动编辑）
     exclude = ('creation_time', 'last_modify_time')
+    # 启用"在站点上查看"功能
     view_on_site = True
+    # 注册批量操作
     actions = [
         makr_article_publish,
         draft_article,
         close_article_commentstatus,
-        open_article_commentstatus]
+        open_article_commentstatus
+    ]
 
     def link_to_category(self, obj):
+        """
+        自定义列表字段：显示分类并添加跳转链接到分类编辑页
+
+        Args:
+            obj: 当前文章对象
+
+        Returns:
+            HTML代码：带链接的分类名称
+        """
+        # 获取分类模型的元数据，用于生成URL
         info = (obj.category._meta.app_label, obj.category._meta.model_name)
+        # 生成分类编辑页的URL
         link = reverse('admin:%s_%s_change' % info, args=(obj.category.id,))
+        # 返回带链接的HTML
         return format_html(u'<a href="%s">%s</a>' % (link, obj.category.name))
 
+    # 自定义字段的显示名称
     link_to_category.short_description = _('category')
 
     def get_form(self, request, obj=None, **kwargs):
+        """
+        重写表单获取方法，自定义表单字段
+
+        这里限制了作者只能选择超级用户
+        """
         form = super(ArticlelAdmin, self).get_form(request, obj, **kwargs)
-        form.base_fields['author'].queryset = get_user_model(
-        ).objects.filter(is_superuser=True)
+        # 作者字段只显示超级用户
+        form.base_fields['author'].queryset = get_user_model().objects.filter(is_superuser=True)
         return form
 
     def save_model(self, request, obj, form, change):
+        """
+        重写保存模型的方法
+
+        可以在这里添加额外的保存逻辑，如自动填充某些字段
+        目前使用默认实现
+        """
         super(ArticlelAdmin, self).save_model(request, obj, form, change)
 
     def get_view_on_site_url(self, obj=None):
+        """
+        自定义"在站点上查看"的链接
+
+        Args:
+            obj: 文章对象
+
+        Returns:
+            文章的前台访问URL或网站首页
+        """
         if obj:
+            # 如果有文章对象，返回文章的完整URL
             url = obj.get_full_url()
             return url
         else:
+            # 如果没有对象（如在列表页），返回网站首页
             from djangoblog.utils import get_current_site
             site = get_current_site().domain
             return site
 
 
 class TagAdmin(admin.ModelAdmin):
+    """标签模型的Admin配置"""
+    # 编辑页排除的字段（自动生成）
     exclude = ('slug', 'last_mod_time', 'creation_time')
 
 
 class CategoryAdmin(admin.ModelAdmin):
+    """分类模型的Admin配置"""
+    # 列表页显示的字段
     list_display = ('name', 'parent_category', 'index')
+    # 编辑页排除的字段
     exclude = ('slug', 'last_mod_time', 'creation_time')
 
 
 class LinksAdmin(admin.ModelAdmin):
+    """链接模型的Admin配置"""
     exclude = ('last_mod_time', 'creation_time')
 
 
 class SideBarAdmin(admin.ModelAdmin):
+    """侧边栏模型的Admin配置"""
     list_display = ('name', 'content', 'is_enable', 'sequence')
     exclude = ('last_mod_time', 'creation_time')
 
 
 class BlogSettingsAdmin(admin.ModelAdmin):
-    pass
+    """博客设置模型的Admin配置"""
+    pass  # 使用默认配置