django-dynamic-raw-id 技术文档

1. 安装指南

1.1 安装步骤

首先，使用 pip 安装 django-dynamic-raw-id 包：

$ pip install django-dynamic-raw-id

1.2 配置 INSTALLED_APPS

在 Django 项目的 settings.py 文件中，将 dynamic_raw_id 添加到 INSTALLED_APPS 列表中：

INSTALLED_APPS = (
  # ... 其他应用
  'dynamic_raw_id',
)

1.3 配置 URL

在 urls.py 文件中，确保 dynamic_raw_id 的 URL 配置在 admin.site.urls 之前：

urlpatterns = [
  # ...
  path('admin/dynamic_raw_id/', include('dynamic_raw_id.urls')),
  path("admin/", admin.site.urls),
]

1.4 收集静态文件

django-dynamic-raw-id 包含一些静态文件，因此需要运行以下命令来收集静态文件：

$ python manage.py collectstatic

2. 项目的使用说明

2.1 在 ModelAdmin 中使用 DynamicRawIDMixin

要在 Django 管理后台中使用 django-dynamic-raw-id，首先需要在 ModelAdmin 类中继承 DynamicRawIDMixin，并将需要使用的字段添加到 dynamic_raw_id_fields 列表中：

from dynamic_raw_id.admin import DynamicRawIDMixin

class UserProfileAdmin(DynamicRawIDMixin, admin.ModelAdmin):
  dynamic_raw_id_fields = ('user',)

2.2 在过滤器中使用 DynamicRawIDFilter

你也可以在管理后台的过滤器中使用 DynamicRawIDFilter：

from dynamic_raw_id.admin import DynamicRawIDMixin
from dynamic_raw_id.filters import DynamicRawIDFilter


class UserProfileAdmin(DynamicRawIDMixin, admin.ModelAdmin):
  list_filter = (
    ('dynamic_raw_id_fk', DynamicRawIDFilter),
  )

3. 项目 API 使用文档

3.1 自定义动态小部件的显示值

django-dynamic-raw-id 允许你自定义动态小部件中显示的值。默认情况下，它会显示对象的 __unicode__ 值。要自定义显示的值，你需要实现相应的模板。

django-dynamic-raw-id 会查找以下模板结构：

• dynamic_raw_id/<app>/<model>.html（单值查找）
• dynamic_raw_id/<app>/multi_<model>.html（多值查找）

例如，如果你有一个博客文章模型，其中有一个 User 动态字段，并且你希望显示为 Firstname Lastname，你可以创建模板 dynamic_raw_id/auth/user.html，内容如下：

<span>{{ object.0.first_name }} {{ object.0.last_name }}</span>

3.2 自定义管理后台 URL 前缀

如果你的管理后台和 dynamic_raw_id 脚本位于不同的前缀路径下，你需要调整 DYNAMIC_RAW_ID_MOUNT_URL JavaScript 变量。

例如，如果应用设置在 /foobar/dynamic_raw_id/，你需要在 admin/base_site.html 模板中添加以下代码：

{% extends "admin/base_site.html" %} {% block extrahead %} {{ block.super }}
<script>
  window.DYNAMIC_RAW_ID_MOUNT_URL = "{% url 'admin:index' %}";
</script>
{% endblock %}

4. 项目安装方式

4.1 使用 pip 安装

通过 pip 安装 django-dynamic-raw-id 是最简单的方式：

$ pip install django-dynamic-raw-id

4.2 使用 Poetry 安装

如果你使用 Poetry 管理依赖，可以通过以下命令安装：

$ poetry add django-dynamic-raw-id

4.3 使用 tox 进行多版本测试

django-dynamic-raw-id 支持使用 tox 进行多版本测试。首先安装 tox：

$ pip install tox

然后运行 tox 来测试多个 Python 和 Django 版本：

$ tox

4.4 本地开发和测试

你可以使用 Poetry 创建一个虚拟环境并运行测试：

$ poetry install
$ poetry run pytest

你还可以使用 django-admin 工具来运行内部测试应用，以预览 django-dynamic-raw-id 的功能：

$ poetry shell

$ django-admin migrate
$ django-admin createsuperuser
$ django-admin runserver

通过以上步骤，你可以成功安装、配置并使用 django-dynamic-raw-id，并在 Django 管理后台中提升用户体验。