django-appsearch 1.1.5

django应用程序搜索

用于在单个页面上进行跨模型搜索的框架和通用应用程序

主要章节：

• 用法
• api

作者

• 蒂姆·瓦伦塔
• 高拉夫·卡普尔
• 史蒂文·克拉斯

用法

AppSearch集成由几个单独的部分组成。在最简单的默认设置中，您必须至少执行以下操作：

• 向AppSearch注册模型
• callappsearch.autodiscover（）（可能在项目的url中的某个位置，比如类似的管理函数）
• 在搜索页面出现的地方创建主视图
• 创建一个可以呈现搜索表单的简单模板

有多种方法可以自定义模板、修改搜索查询集等，基本介绍后将介绍这些方法。

型号注册

在django.contrib.admin接口之后，appsearch包含一个registry子模块，该子模块包含一个modelsearch类（沿着admin的modelsadmin行），以及一个名为search的默认注册表对象

modelsearch有几个基本选项，其中最重要的是搜索字段和显示字段

我们将使用这个示例基本模型进行注册，为了演示，它会接触到其他一些伪模型：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

搜索字段

若要注册此模型，请在应用程序的目录中放置一个search.py子模块，并至少包含此基本注册代码。为了清楚起见，我们将省略大部分car字段：

# car/search.pyfromappsearch.registryimportModelSearch,searchfromproject.car.modelsimportCarclassCarSearch(ModelSearch):search_fields=('year','nickname','adoption_story',)search.register(Car,CarSearch)

搜索字段是一个iterable，其项描述可搜索字段。此处列出字段的顺序将在AppSearch UI中得到遵守。如果列表中的项直接描述模型字段名，则该项可以是字符串。将查找该字段，并将其详细名称存储在ui中使用。要显式声明"详细名称"以便在AppSearch UI中使用，可以将字符串设为详细名称和字段名称的2元组：

search_fields=('year',("Name",'nickname'),'adoption_story',)

若要将相关字段拉入组合，项可以改为单个条目字典，将属性映射到遵循相同格式的嵌套结构：

search_fields=('year',("Name",'nickname'),'adoption_story',{'make':('name',)},{'model':('name',)},{'owners':('username','first_name','last_name',)},)

此语法减少了潜在的重复查询语言，例如"owners庘u username"、"owners庘u first庘u name"、以及"owners庘u last庘u name"。

任何在搜索配置中不提供自己详细名称的相关字段都将显示在其前面，并显示相关模型的详细名称。换言之，为了防止搜索用户界面显示车主的"名字"字段，就好像它是汽车的名字一样，用户界面将在该字段的名称前面加上用户的详细名称。在本例中，名字将显示为"用户名"。

为了防止自动前缀，您可以提供自己的详细名称，如前所示：

search_fields=(# ...{'owners':(("Username",'username'),# would have been "User username"("User's First name","first_name"),# would have been "User first name"("User's Last name","last_name"),# would have been "User last name")},)

相关字段可以嵌套：

search_fields=(# ...{'owners':('username',# displayed as "User username"{'groups':('name',# displayed as "Group name")},)},)

另一种指定相关字段的方法是使用相关模型类本身作为字典键。使用此方法，将通过检查两个模型之间的关系自动检索字段名：

search_fields=(# ...{User:(# validated to the string "owner", as in the previous example'username',# displayed as "User username"{'groups':('name',# displayed as "Group name")},)})

最终，此语法将成为访问泛型外键的受支持方法，尽管此类关系尚未实现。

注意：由ageneric relation字段引用的通用模型（例如，包含一个名为"comments"的genericrelation字段的car对象到一个generic comment模型）。红色有效，由AppSearch框架摘要：

search_fields=(# ...{'comments':(# Car.comments as a GenericRelation field to Comment model'title','content',)},)

显示字段

默认情况下，appsearch显示的结果表将包含模型上的所有本地字段。要显式声明字段列表，您的配置可以包含另一个属性display_fields，其格式类似于search_fields：

classCarSearch(ModelSearch):display_fields=('nickname','year',("Make",'make__name'),("Model",'model__name'),("Owners",'get_owners_list'),# attribute on the Car model)search_fields=(# ...)

display_fields是一个iterable项，可以是字符串，也可以是（verbosename，fieldname）的2元组。与search_fields一样，除非在配置中显式提供，否则将自动检索字段的详细名称。

字段不一定是数据库字段；在上面的示例中，我们在表头中放置了一个"owners"列，该字段实际上是一个方法名。这很方便，但请注意不要在appsearch的控制范围之外生成太多查询！

此列表中的第一个项将转换为链接，并用一段简单的html代码片段包装该值：<；a href="{object.get_absolute_url}">；{{value}}<；/a>；

AppSearch将检查显示字段以了解如何最好地发出对搜索结果queryset的调用，这有助于降低自动查询计数。

appsearch.autodiscover（）

与内置管理一样，AppSearch可以对应用程序进行爬网，以在每个应用程序中发现search.py模块。autodiscover（）只会导入这些配置并使其执行，因此如果使用自定义或多个注册表，此函数将允许这些注册表自行设置。

与管理员一样，一个很好的调用autodiscover（）的地方是在您的url模块中，或者是在项目的根目录中，或者是在一个本地"搜索"应用程序中，您无论如何都要在其中设置视图。请参阅下一节中的示例。

主视图

您需要声明自己的起点，以便客户最初访问并配置搜索。

basesearchview是一个简单的templateview子类，它也继承自appsearch.views.searchmixin。对于完全普通的行为，可以直接包含basesearchview：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

默认值：配置的多个"verbose"名称（如果可用），或者模型类的多个"verbose"名称（如果可用）。

显示字段

列描述项的Iterable。

每个"项目"可以是一个字符串：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

或显式提供详细名称的2元组：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

在这两种情况下，字段名都可以引用本地字段（包括方法名）或查询集样式的查找路径。在后一种情况下，应提供显式的详细名称：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

将自动检测任何跨模型查找，并发出相应的。select_related（）语句。

默认值：所有本地字段

搜索字段

一组字段描述项。

每个"item"都可以是一个描述本地数据库字段的字符串：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

或显式提供详细名称的2元组：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

或者一个单项目字典，将一个相关访问器映射到一个新的相关字段描述项的iterable，遵循相同的格式规则：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

搜索表单用户界面将遵循搜索字段的声明顺序。

对于字典项中的相关字段，详细名称的前缀将是字段模型的详细名称：

# car/models.pyclassCar(models.Model):year=models.PositiveIntegerField()make=models.ForeignKey(CarMake)model=models.ForeignKey(CarModel)owners=models.ManyToManyField(User)nickname=models.CharField(max_length=50)adoption_story=models.TextField()

如果字段已显式声明详细名称，则不会添加前缀：

# car/search.pyfromappsearch.registryimportModelSearch,searchfromproject.car.modelsimportCarclassCarSearch(ModelSearch):search_fields=('year','nickname','adoption_story',)search.register(Car,CarSearch)

获取查询集（用户）

返回在此模型上搜索将用于应用生成的查询的基queryset。默认情况下，模型的默认管理器用于返回未筛选的queryset。使用此钩子的适当方法是使用不同的管理器，或基于权限机制限制queryset。

用户是发出请求的用户。

获取对象数据（obj）

给定搜索结果对象obj，返回前端表的数据字段列表。列表的长度应与显示列的数目相匹配。

默认实现将自动读取配置的显示字段中指定的属性并生成此列表。如果一个值是可调用的，则调用该值时将不带参数，并使用返回值代替它，从而允许显示字段指定实例属性和方法，以及具体的数据库支持字段。

在对每个结果对象调用此方法之前，默认搜索机制所做的工作将尝试在源QuerySet上调用select_related（），但请注意不要为每个对象生成过多的查询。如果需要选择其他相关字段以避免高查询计数，则可以提供自己的子类searcher和：

1. 重写searcher.build_queryset（）方法，调用super（）并对返回值执行额外的select_related（）调用。
2. 直接覆盖并添加到列表中。

搜索注册表

appsearch.registry.searchregistry

存储配置以便在搜索表单中使用的注册表容器。

默认注册表在名为search的模块变量中可用。

\uu iter\uuu（）

生成注册表项，它们是"applabel.modelname"格式的字符串

获取项目（k）