django admin site search

django-admin-站点搜索

Django 管理员的全局/站点搜索模式。

特征

• ？开箱即用，配置最少。
• ？搜索执行于：
  • 应用程序标签。
  • 模型标签和字段属性。
  • 模型实例，有两种搜索方法选项：
    1. model_char_fields （默认）：所有CharField （和子类）值，带有__icontains 。
    2. admin_search_fields ：调用每个 ModelAdmin 的 get_search_results(...) 方法。
• 内置授权：用户只能搜索自己有权限查看的应用和模型。
• ⚡ 结果按类型显示，并通过节流/去抖动来避免过多的请求。
• ？键盘导航（cmd+k、向上/向下、输入）。
• 响应式，支持暗/亮模式。
  • Django 的内置 CSS 变量用于匹配您的管理主题。

要求

• Python 3.7 - 3.12。
• 姜戈 3.2 - 5.1。

设置

1. 安装

1. 使用包管理器安装，例如pip install django-admin-site-search 。
2. 将admin_site_search添加到您的INSTALLED_APPS设置中。

2. 添加视图

1. 如果您还没有这样做，请覆盖/扩展默认的 AdminSite。
2. 将AdminSiteSearchView添加到您的 AdminSite：

 from django . contrib import admin
from admin_site_search . views import AdminSiteSearchView

class MyAdminSite ( AdminSiteSearchView , admin . AdminSite ):
    ...

3. 添加模板

1. 如果尚未创建，请在templates/目录中创建admin/base_site.html 。
   • 注意：如果您的templates/目录位于应用程序内部，则该应用程序必须出现在INSTALLED_APPS中，位于您的自定义管理应用程序之前。
2. 包含admin_site_search模板：

{% extends "admin/base_site.html" %}

{% block extrahead %}
    {% include 'admin_site_search/head.html' %}
    {{ block.super }}
{% endblock %}

{% block footer %}
    {{ block.super }}
    {% include 'admin_site_search/modal.html' %}
{% endblock %}

{% block usertools %}
    {% include 'admin_site_search/button.html' %}
    {{ block.super }}
{% endblock %}

笔记

• 除了样式之外， admin_site_search/head.html还加载 Alpine JS。
  • 这被捆绑到/static/中，以避免外部依赖。
• modal.html和button.html的放置并不严格，尽管前者最好位于顶级位置。
  • Django 4.x 公开了{% block header %} - 这比footer更好。

定制化

类属性

 class MyAdminSite ( AdminSiteSearchView , admin . AdminSite ):
    
    # Sets the last part of the search route (`<admin_path>/search/`).
    site_search_path : str = "search/"
    # Set the search method/behaviour.
    site_search_method : Literal [ "model_char_fields" , "admin_search_fields" ] = "model_char_fields" 

方法

 def match_app (
    self , request , query : str , name : str
) -> bool :
    """DEFAULT: case-insensitive match the app name"""

def match_model (
    self , request , query : str , name : str , object_name : str , fields : List [ Field ]
) -> bool :
    """DEFAULT: case-insensitive match the model and field attributes"""

def match_objects (
    self , request , query : str , model_class : Model , model_fields : List [ Field ]
) -> QuerySet :
    """DEFAULT: Returns the QuerySet after performing an OR filter across all Char fields in the model."""

def filter_field (
    self , request , query : str , field : Field
) -> Optional [ Q ]:
    """DEFAULT: Returns a Q 'icontains' filter for Char fields, otherwise None
    
    Note: this method is only invoked if model_char_fields is the site_search_method."""

def get_model_queryset (
    self , request , model_class : Model , model_admin : Optional [ ModelAdmin ]
) -> QuerySet :
    """DEFAULT: Returns the model class' .objects.all() queryset."""

def get_model_class (
    self , request , app_label : str , model_dict : dict
) -> Optional [ Model ]:
    """DEFAULT: Retrieve the model class from the dict created by admin.AdminSite""" 

例子

将TextField结果添加到搜索中。

 from django . contrib import admin
from django . db . models import Q , Field , TextField
from admin_site_search . views import AdminSiteSearchView


class MyAdminSite ( AdminSiteSearchView , admin . AdminSite ):
    
    site_search_method : "model_char_fields"  
  
    def filter_field ( self , request , query : str , field : Field ) -> Optional [ Q ]:
        """Extends super() to add TextField support to site search"""
        if isinstance ( field , TextField ):
            return Q ( ** { f" { field . name } __icontains" : query })
        return super (). filter_field ( query , field )

请注意，出于性能原因，默认情况下不会这样做：大量文本条目上的__icontains不是最佳选择。

截图