Django Positions 技术文档

1. 安装指南

在开始使用 Django Positions 前，请确保您的环境中已经安装了 Django。以下是安装 Django Positions 的步骤：

pip install django-positions

确保在您的 Django 项目的 settings.py 文件中包含了 positions 应用。

INSTALLED_APPS = [
    # ...
    'positions',
    # ...
]

2. 项目的使用说明

Django Positions 提供了 PositionField，这是一个 Django 模型字段，允许模型的实例按照用户指定的位置排序。概念上，这个字段的工作原理类似于列表索引：当一个项目位置改变时，集合中其他项目位置会相应更新。

要在您的模型中使用 PositionField，只需将其添加到您的模型中即可。

如果您想将模型的所有实例作为一个单一的集合来处理，不需要做其他任何操作。若要根据模型上的一个或多个字段创建基于集合，请使用 collection 参数指定字段名称。

positions.examples 应用演示了 PositionField API 的使用。

3. 项目API使用文档

• PositionField: 在模型中添加此字段以启用排序功能。
• PositionManager: 自定义管理器，通过 PositionQuerySet 提供了 reposition 方法，用于更新查询集中所有对象的位置以匹配当前排序。
• ManyToManyField 作为 collection 使用是不支持的，相反，应该使用一个带有 PositionField 的中间模型。

例如：

class Product(models.Model):
    name = models.CharField(max_length=50)

class Category(models.Model):
    name = models.CharField(max_length=50)
    products = models.ManyToManyField(Product, through='ProductCategory', related_name='categories')

class ProductCategory(models.Model):
    product = models.ForeignKey(Product)
    category = models.ForeignKey(Category)
    position = PositionField(collection='category')

    class Meta:
        unique_together = ('product', 'category')

• Multi-table model inheritance：默认情况下，如果父模型有声明 collection 的位置字段，子模型实例将独立排序。可以通过指定 parent_link 参数来改变这种行为，它标识了链接子模型到父模型的一对一字段名称。

4. 项目安装方式

如安装指南所述，使用 pip 命令安装 Django Positions：

pip install django-positions

确保在您的 Django 项目的 settings.py 文件中包含了 positions 应用。

以上是 Django Positions 的技术文档，希望对您使用和了解此项目有所帮助。