Ubuntu SQLAdmin界面定制方法

Ubuntu环境下SQLAdmin界面定制方法
SQLAdmin是基于SQLAlchemy（兼容异步/同步）、专为Starlette/FastAPI设计的Admin界面框架，默认采用Tabler UI（现代化响应式设计）。在Ubuntu系统中，可通过模板覆盖、CSS/JS扩展、模型视图定制等方式调整界面，以下是具体步骤：

一、基础准备：确认环境与目录结构

安装SQLAdmin：通过pip安装SQLAdmin及依赖（如fastapi、sqlalchemy），确保Ubuntu系统已安装Python 3.8+及pip：
```
pip install sqladmin fastapi sqlalchemy
```
模板目录结构：SQLAdmin会优先加载项目根目录下templates/sqladmin目录中的模板文件（覆盖内置模板）。若目录不存在，需手动创建：
```
mkdir -p your_project/templates/sqladmin
```

二、核心定制方法

1. 模板继承与block覆盖（最常用）

SQLAdmin基于Jinja2模板引擎，通过继承基础模板并覆盖特定block实现界面调整。常见block包括：

base.html：基础布局（head、body、tail）；
layout.html：管理界面框架（content_header、content）；
list.html：列表页（content、filters）；
edit.html：编辑页（form、actions）；
details.html：详情页（content、fields）。

示例：修改列表页标题与添加导出按钮

创建自定义列表页模板your_project/templates/sqladmin/list.html，继承内置list.html：

{% extends "sqladmin/list.html" %}

{% block content_header %}
  <div class="row align-items-center">
    <div class="col">
      <h2 class="page-title">自定义用户列表</h2>
      <div class="page-pretitle">高级管理视图</div>
    </div>
    <div class="col-auto ms-auto d-print-none">
      <button class="btn btn-primary" id="custom-export-btn">
        <i class="fa-solid fa-download"></i> 导出全部数据
      </button>
    </div>
  </div>
{% endblock %}

{% block tail %}
  {{ super() }}  <!-- 保留父模板内容 -->
  <script>
    document.getElementById('custom-export-btn').addEventListener('click', () => {
      alert('实现自定义导出逻辑（如调用API或生成CSV）');
    });
  </script>
{% endblock %}

在ModelView中指定自定义模板：

from sqladmin import ModelView
from your_project.models import User

class UserAdmin(ModelView, model=User):
    list_template = "list.html"  # 指向自定义模板
    column_list = [User.id, User.name, User.email]

2. CSS/JS扩展：调整样式与交互

添加自定义CSS：在模板中通过{% block extra_css %}引入自定义CSS文件（如static/css/custom.css）：

{% block extra_css %}
  <link rel="stylesheet" href="{{ url_for('static', path='/css/custom.css') }}">
{% endblock %}

示例static/css/custom.css（修改表格行 hover 效果）：

.table-hover tbody tr:hover {
  background-color: #f8f9fa !important;
}

添加自定义JS：通过{% block tail %}在页面底部插入JS代码（如上述导出按钮的点击事件），或引入外部JS文件（如static/js/custom.js）。

3. 模型视图定制：控制字段与功能

通过ModelView子类调整模型在界面中的显示与交互：

调整列表页显示字段：通过column_list指定要显示的字段（支持关联模型，需预加载避免N+1查询）：

from sqlalchemy.orm import joinedload

class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name, User.email, User.profile.avatar_url]  # 关联字段
    
    def list_query(self, request):
        return super().list_query(request).options(joinedload(User.profile))  # 预加载关联模型

自定义表单字段：通过form_columns指定表单中显示的字段，并通过form_overrides调整字段类型（如将Boolean转为开关）：

from wtforms.widgets import SwitchInput

class UserAdmin(ModelView, model=User):
    form_columns = [User.name, User.email, User.is_active]
    form_overrides = {
        'is_active': SwitchInput  # 使用开关控件
    }

添加自定义操作：通过@expose装饰器添加自定义端点（如批量删除、数据统计）：

from sqladmin import expose
from fastapi.responses import JSONResponse

class UserAdmin(ModelView, model=User):
    @expose("/batch_delete", methods=["POST"])
    async def batch_delete(self, request):
        selected_ids = request.form.getlist("selected_ids")
        # 执行批量删除逻辑
        return JSONResponse({"status": "success", "message": f"删除了{len(selected_ids)}条记录"})

4. 主题与图标调整

SQLAdmin基于Tabler UI，可通过修改Tabler的主题变量调整界面风格：

修改Tabler主题：在custom.css中覆盖Tabler的默认变量（如主色调、背景色）：

:root {
  --primary: #4dabf7;  /* 修改主色调为蓝色 */
  --secondary: #6c757d;
  --background: #f8f9fa;
}

更换图标：使用Tabler的Font Awesome图标（通过icon属性指定），如将列表页图标改为fa-solid fa-users：
```
class UserAdmin(ModelView, model=User):
    icon = "fa-solid fa-users"  # Font Awesome图标类名
```

三、常见问题排查

模板不生效：
- 确认模板目录路径正确（your_project/templates/sqladmin）；
- 清除浏览器缓存或使用无痕模式；
- 检查模板语法（如{% extends %}、{% block %}是否正确）。
自定义CSS/JS不加载：
- 确认static目录路径正确（your_project/static）；
- 检查url_for路径是否正确（如path='/css/custom.css'）。
关联字段N+1查询：
- 使用joinedload预加载关联模型（如上述list_query示例），避免性能问题。

通过以上方法，可灵活定制SQLAdmin界面，满足Ubuntu系统下的业务需求。如需更高级的定制（如权限系统、组件化），可参考SQLAdmin官方文档或源码扩展。