如何在django CMS图标插件中接入Font Awesome5并编写admin端assets.html

前置基础配置 #

在编写assets.html前，需要先在项目的settings.py中完成两类基础配置：

1. 按需调整图标集匹配规则，匹配你实际使用的Font Awesome5图标集：

   # 按需选择需要启用的Font Awesome5图标集项
   DJANGOCMS_ICON_SETS = [
       ('fontawesome5solid', 'fas', 'Font Awesome 5 Solid'),
       ('fontawesome5regular', 'far', 'Font Awesome 5 Regular'),
       ('fontawesome5brands', 'fab', 'Font Awesome 5 Brands'),
       # 如果使用PRO版本Light图标集，可追加下方配置
       # ('fontawesome5light', 'fal', 'Font Awesome 5 Light', '5.3.1_pro'),
   ]
   

2. 如果需要为图标插件新增自定义渲染模板，可按需补充DJANGOCMS_ICON_TEMPLATES配置，该配置和assets.html的资源加载逻辑互不影响：

   DJANGOCMS_ICON_TEMPLATES = [
       ('svg', 'SVG template'),
   ]
   

文件路径与作用说明 #

需要在项目模板目录下创建对应路径的模板文件：admin/djangocms_icon/includes/assets.html

该文件是图标插件后台模块的静态资源挂载入口，作用是加载Font Awesome5的样式资源，确保admin端的图标选择器能正确识别、渲染所有可选图标，避免出现图标错位、方块显示的问题。

可直接复用的参考样例 #

本地静态资源加载方案 #

将Font Awesome5的静态资源存放在项目的static目录下后，模板内容编写如下，该方案适合正式生产环境使用，避免依赖外部第三方资源：

{% load static %}
{# 按项目实际存放的FA5文件路径调整href值 #}
<link rel="stylesheet" href="{% static 'vendor/fontawesome5/css/all.min.css' %}">

开发调试简化方案 #

如果本地调试时不想提前导入本地静态资源，可以直接在文件中引入项目可访问的FA5样式资源路径，示例结构：

{% load static %}
{# 替换为项目实际可访问的FA5样式资源地址 #}
<link rel="stylesheet" href="项目内可访问的Font Awesome5 CSS资源路径">

常见配置校验点 #

• 引入的Font Awesome5样式资源必须和DJANGOCMS_ICON_SETS中配置的类名前缀完全对应，不能混用Font Awesome4的资源，否则图标选择器会匹配不到正确的样式类。
• 如果需要同时加载多套Font Awesome5字重（Solid/Regular/Brands/Light），只需要在同一个assets.html中追加对应样式的引入标签即可，无需拆分多个文件。
• 模板文件必须放在Django模板搜索路径的匹配层级下，不能随意修改目录名，否则插件会加载默认的内置资源，覆盖自定义配置。

内容的提问来源于stack exchange，提问作者Jefferson Tuffour Addai-Poku