为Django设计的简单、灵活且可扩展的导航菜单。
项目描述
django-simple-nav
django-simple-nav是一个Python/Django应用，旨在简化在Django项目中集成导航和菜单栏。它具有直观的API和可定制选项，您可以在Web应用程序中轻松添加和管理导航元素。它设计得简单易用，但足够灵活，可以处理复杂的导航结构，同时保持简单性。
需求
- Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
- Django 4.2, 5.0
安装
-
从PyPI安装包。
python -m pip install django-simple-nav
-
将
django_simple_nav添加到INSTALLED_APPS。安装后，将
django_simple_nav添加到你的 Django 设置中的INSTALLED_APPSINSTALLED_APPS = [ # ..., "django_simple_nav", # ..., ]
-
调整你的 Django 项目的设置。
如果你计划使用
django-simple-nav的权限功能根据request.user过滤你的导航项，则必须将django.contrib.auth和django.contrib.contenttypes添加到你的INSTALLED_APPS中。INSTALLED_APPS = [ # ..., "django.contrib.auth", "django.contrib.contenttypes", # ..., ]
如果你没有将
django.contrib.auth添加到INSTALLED_APPS并且为你的导航项定义了任何权限，django-simple-nav将简单地忽略权限，并渲染所有项，无论权限检查结果为True或False。
入门指南
-
创建导航定义。
在 Python 文件中定义你的导航结构。这个文件可以位于你的 Django 项目中的任何位置，只要它能被导入。你也可以根据需要将导航拆分到多个文件中。
一个很好的起点是在你的 Django 项目的主配置目录（你的
settings.py文件所在的目录）中创建一个单独的nav.py或navigation.py文件。django-simple-nav提供了三个类来帮助你定义导航结构Nav：导航结构的主体容器。它有两个必需的属性template_name：用于渲染导航结构的模板名称。items：一个代表导航结构的NavItem或NavGroup对象的列表。
NavGroup：一组NavItem或NavGroup对象的容器。它有两个必需的和三个可选的属性title：组的标题。items：一个代表组结构的NavItem或NavGroup对象的列表。url（可选）：组的 URL。如果没有提供，则该组将不是链接，而只是项目的容器。permissions（可选）：控制组可见性的权限列表。这些权限可以是User属性（例如is_authenticated、is_staff、is_superuser），Django 权限（例如myapp.django_perm）或一个接受HttpRequest并返回bool的可调用对象。extra_context（可选）：一个字典，包含在渲染导航时传递给模板的额外上下文。
NavItem：单个导航项。它有两个必需的和三个可选的属性title：项的标题。url：项的 URL。这可以是一个 URL 字符串（例如https://example.com/about/或/about/）或一个 Django URL 名称（例如about-view）。permissions（可选）：控制项可见性的权限列表。这些权限可以是User属性（例如is_authenticated、is_staff、is_superuser）、Django 权限（例如myapp.django_perm）或一个接受HttpRequest并返回bool的可调用对象。extra_context（可选）：一个字典，包含在渲染导航时传递给模板的额外上下文。
以下是一个示例配置
# config/nav.py from django.http import HttpRequest from django_simple_nav.nav import Nav from django_simple_nav.nav import NavGroup from django_simple_nav.nav import NavItem def simple_permissions_check(request: HttpRequest) -> bool: return True class MainNav(Nav): template_name = "main_nav.html" items = [ NavItem(title="Relative URL", url="/relative-url"), NavItem(title="Absolute URL", url="https://example.com/absolute-url"), NavItem(title="Internal Django URL by Name", url="fake-view"), NavGroup( title="Group", url="/group", items=[ NavItem(title="Relative URL", url="/relative-url"), NavItem(title="Absolute URL", url="https://example.com/absolute-url"), NavItem(title="Internal Django URL by Name", url="fake-view"), ], ), NavGroup( title="Container Group", items=[ NavItem(title="Item", url="#"), ], ), NavItem( title="is_authenticated Item", url="#", permissions=["is_authenticated"] ), NavItem(title="is_staff Item", url="#", permissions=["is_staff"]), NavItem(title="is_superuser Item", url="#", permissions=["is_superuser"]), NavItem( title="myapp.django_perm Item", url="#", permissions=["myapp.django_perm"] ), NavItem( title="Item with callable permission", url="#", permissions=[simple_permissions_check], ), NavGroup( title="Group with Extra Context", items=[ NavItem( title="Item with Extra Context", url="#", extra_context={"foo": "bar"}, ), ], extra_context={"baz": "qux"}, ), ]
-
创建导航模板。
创建一个模板来渲染导航结构。这是一个标准的 Django 模板，所以你可以使用任何你喜欢的 Django 模板功能。
模板将传递一个
items变量到上下文中，表示导航的结构，其中包含在导航中定义的NavItem和NavGroup对象。任何带有权限的项将在渲染模板之前自动过滤掉，基于请求用户的权限，所以你不需要在模板中担心这一点。
带有额外上下文的项将在渲染导航时将上下文传递到模板中，你可以直接访问它。
例如，给定上面的
MainNav示例，你可以创建一个main_nav.html模板<!-- main_nav.html --> <ul> {% for item in items %} <li> <a href="{{ item.url }}"{% if item.active %} class="active"{% endif %}{% if item.baz %} data-baz="{{ item.baz }}"{% endif %}> {{ item.title }} </a> {% if item.items %} <ul> {% for subitem in item.items %} <li> <a href="{{ subitem.url }}"{% if subitem.active %} class="active"{% endif %}{% if item.foo %} data-foo="{{ item.foo }}"{% endif %}> {{ subitem.title }} </a> </li> {% endfor %} </ul> {% endif %} </li> {% endfor %} </ul>
-
在模板中集成导航。:
在你的 Django 模板中需要显示导航的地方使用
django_simple_nav模板标签。例如
<!-- base.html --> {% load django_simple_nav %} {% block navigation %} <nav> {% django_simple_nav "path.to.MainNav" %} </nav> {% endblock navigation %}
模板标签可以接受一个表示您的导航定义导入路径的字符串，或者接受您的导航类的一个实例
# example_app/views.py from config.nav import MainNav def example_view(request): return render(request, "example_app/example_template.html", {"nav": MainNav()})
<!-- example_app/example_template.html --> {% extends "base.html" %} {% load django_simple_nav %} {% block navigation %} <nav> {% django_simple_nav nav %} </nav> {% endblock navigation %}
此外，模板标签还可以接受第二个参数来指定用于渲染导航的模板。如果您想在多个地方使用相同的导航结构，但以不同的方式渲染，这非常有用。
<!-- base.html --> {% load django_simple_nav %} <footer> {% django_simple_nav "path.to.MainNav" "footer_nav.html" %} </footer>
配置完您的导航后，您可以通过在模板中调用 django_simple_nav 模板标签来在您的Django项目中使用它。这个标签根据您定义的结构动态渲染导航，确保您的应用程序中有一个一致且灵活的导航体验。
示例
example 目录包含一个简单的Django项目，展示了如何使用 django-simple-nav。该示例项目包括几个不同场景的导航定义以及一些流行的CSS框架。
您可以通过以下步骤运行示例项目。这些步骤假定您系统上已安装 git 和 python，并且使用Unix-like shell。如果您使用Windows，可能需要相应调整命令。
-
克隆仓库。
git clone https://github.com/westerveltco/django-simple-nav cd django-simple-nav
-
创建一个新的虚拟环境，激活它，并安装
django-simple-nav。python -m venv venv source venv/bin/activate python -m pip install .
-
运行示例项目。
python example/demo.py -
打开浏览器到
http://localhost:8000查看示例效果。
文档
有关更多信息，请参阅文档。
许可
django-simple-nav 采用MIT许可协议。有关更多信息，请参阅LICENSE 文件。
