Configurations

SQLAdmin 配置选项 SQLAdmin 的配置选项受到 Flask-Admin 项目的启发。

此页面将为您提供基本介绍，更多详细信息请参阅 API 参考文档。

假设您已按如下方式定义了 SQLAlchemy 模型：

from sqlalchemy import Column, Integer, String, create_engine
from sqlalchemy.orm import declarative_base

Base = declarative_base()
engine = create_engine(
    "sqlite:///example.db",
    connect_args={"check_same_thread": False},
)

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String)

Base.metadata.create_all(engine)  # 创建表

集成 SQLAdmin 到 FastAPI 应用中：

from fastapi import FastAPI
from sqladmin import Admin, ModelView

app = FastAPI()
admin = Admin(app, engine)

class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name]

admin.add_view(UserAdmin)

如您所见，UserAdmin 类继承自 ModelView 并接受一些配置。

权限

您可以为该模型配置一些通用权限，以下是可用选项：

• can_create：是否允许通过 SQLAdmin 创建新实例。默认值为 True。

• can_edit：是否允许编辑模型实例。默认值为 True。

• can_delete：是否允许删除模型实例。默认值为 True。

• can_view_details：是否允许查看模型实例详细信息。默认值为 True。

• can_export：是否允许导出模型数据。默认值为 True。

示例：

class UserAdmin(ModelView, model=User):
    can_create = True
    can_edit = True
    can_delete = False
    can_view_details = True

元数据

模型的元数据选项：

• name：模型的显示名称，默认为类名。

• name_plural：模型的复数显示名称，默认为类名 + "s"。

• icon：在管理员界面中显示的模型图标，仅支持 FontAwesome 和 Tabler 图标。

• category：分类名称，用于在下拉菜单中将 ModelView 类分组。

示例：

class UserAdmin(ModelView, model=User):
    name = "User"
    name_plural = "Users"
    icon = "fa-solid fa-user"
    category = "accounts"

列表页

这些选项用于配置列表页，在此示例中，可以查看用户记录列表。

可用选项包括：

• column_list：要显示的列或列名列表。

• column_exclude_list：要排除的列或列名列表。

• column_formatters：列格式化器的字典。

• column_searchable_list：在列表页中可搜索的列或列名列表。

• column_sortable_list：在列表页中可排序的列或列名列表。

• column_default_sort：如果没有应用排序，默认的排序方式，元组形式 (column, is_descending)，也可以是多个元组的列表。

• list_query：自定义列表查询的方法，签名为 (request) -> stmt。

• count_query：自定义计数查询的方法，签名为 (request) -> stmt。

• search_query：自定义搜索查询的方法，签名为 (stmt, term) -> stmt。

示例：

class UserAdmin(ModelView, model=User):
    column_list = [User.id, User.name, "user.address.zip_code"]
    column_searchable_list = [User.name]
    column_sortable_list = [User.id]
    column_formatters = {User.name: lambda m, a: m.name[:10]}
    column_default_sort = [(User.email, True), (User.name, False)]

提示 如果您不想手动指定所有列，可以在 column_list 或 column_details_list 中使用特殊关键字 __all__。例如：column_list = "__all__"。

详情页

这些选项用于配置详情页，在此示例中，您可以查看单个用户的详细信息。

可用选项包括：

• column_details_list：在详情页中显示的列或列名列表。

• column_details_exclude_list：在详情页中排除的列或列名列表。

• column_formatters_detail：在详情页中使用的列格式化器字典。

示例：

class UserAdmin(ModelView, model=User):
    column_details_list = [User.id, User.name, "user.address.zip_code"]
    column_formatters_detail = {User.name: lambda m, a: m.name[:10]}

提示 您可以使用字符串值显示关联模型的属性。例如，"user.address.zip_code" 将加载关联，但会为每个关系加载额外的查询。

分页选项

列表页中的分页选项可以配置。可用选项包括：

• page_size：分页的默认页面大小，默认为 10。

• page_size_options：分页选择器选项，默认为 [10, 25, 50, 100]。

示例：

class UserAdmin(ModelView, model=User):
    page_size = 50
    page_size_options = [25, 50, 100, 200]

常规选项

以下选项适用于列表页和详情页：

• column_labels：列标签的映射，用于将列名映射为新名称。

• column_type_formatters：类型键和可调用值的映射，用于在所有页面中格式化列。例如，您可以为日期添加自定义格式化器。

• save_as：启用 "另存为新对象" 选项。

• save_as_continue：控制启用 save_as 时的重定向 URL。

示例：

class UserAdmin(ModelView, model=User):
    def date_format(value):
        return value.strftime("%d.%m.%Y")

    column_labels = {User.email: "Email"}
    column_type_formatters = dict(ModelView.column_type_formatters, date=date_format)
    save_as = True

表单选项

SQLAdmin 允许自定义如何使用表单处理您的模型。表单基于 WTForms 包，并包括以下选项：

• form：用于创建或编辑模型的默认表单。默认为 None，表单将动态创建。

• form_base_class：用于创建表单的默认基类。默认为 wtforms.Form。

• form_args：WTForms 支持的表单字段参数字典。

• form_widget_args：WTForms 支持的表单小部件渲染参数字典。

• form_columns：要包括在表单中的模型列列表，默认为所有模型列。

• form_excluded_columns：要从表单中排除的模型列列表。

• form_overrides：用于覆盖表单字段的字典。

• form_include_pk：控制是否在创建/编辑表单中包括主键列，默认为 False。

• form_ajax_refs：使用 Ajax 和 Select2 加载关联模型的字段，适用于关联模型记录较多的情况。

• form_converter：允许添加自定义转换器以支持额外的列类型。

• form_edit_query：自定义编辑表单数据的方法，签名为 (request) -> stmt。

• form_rules：用于管理表单渲染和行为的表单规则列表。

• form_create_rules：用于管理创建页面表单渲染和行为的表单规则列表。

• form_edit_rules：用于管理编辑页面表单渲染和行为的表单规则列表。

示例：

class UserAdmin(ModelView, model=User):
    form_columns = [User.name]
    form_args = dict(name=dict(label="Full name"))
    form_widget_args = dict(email=dict(readonly=True))
    form_overrides = dict(email=wtforms.EmailField)
    form_include_pk = True
    form_ajax_refs = {
        "address": {
            "fields": ("zip_code", "street"),
            "order_by": ("id",),
        }
    }
    form_create_rules = ["name", "password"]
    form_edit_rules = ["name"]

导出选项

SQLAdmin 支持在列表页导出数据。目前仅支持 CSV 导出。导出选项可以为每个模型设置，包含以下选项：

• can_export：是否允许导出该模型。默认值为 True。

• column_export_list：要包括在导出数据中的列列表，默认是所有模型列。

• column_export_exclude_list：要排除的列列表。

• export_max_rows：最大导出行数。默认值为 0，表示无限制。

• export_types：启用的导出类型列表，默认值为 `["csv",

"json"]`。

模板

模板文件使用 Jinja2 构建，并且可以在配置中完全覆盖。可用的页面包括：

• list_template：用于模型列表页的模板。默认是 sqladmin/list.html。

• create_template：用于模型创建页的模板。默认是 sqladmin/create.html。

• details_template：用于模型详情页的模板。默认是 sqladmin/details.html。

• edit_template：用于模型编辑页的模板。默认是 sqladmin/edit.html。

示例：

class UserAdmin(ModelView, model=User):
    list_template = "custom_list.html"

更多关于模板的工作方式请参见 Working with Templates。

事件

在某些情况下，您可能希望在模型创建、更新或删除之前或之后执行一些操作。您可以覆盖以下四个方法：

• on_model_change：在模型创建或更新之前调用。

• after_model_change：在模型创建或更新之后调用。

• on_model_delete：在模型删除之前调用。

• after_model_delete：在模型删除之后调用。

默认情况下，这些方法不做任何操作。

示例：

class UserAdmin(ModelView, model=User):
    async def on_model_change(self, data, model, is_created, request):
        # 执行其他操作
        ...

    async def on_model_delete(self, model, request):
        # 执行其他操作
        ...

自定义操作

您可以使用 action 装饰器为模型添加自定义操作到管理员界面。

示例：

from sqladmin import BaseView, action

class UserAdmin(ModelView, model=User):
    @action(
        name="approve_users",
        label="Approve",
        confirmation_message="Are you sure?",
        add_in_detail=True,
        add_in_list=True,
    )
    async def approve_users(self, request: Request):
        pks = request.query_params.get("pks", "").split(",")
        if pks:
            for pk in pks:
                model: User = await self.get_object_for_edit(pk)
                ...

        referer = request.headers.get("Referer")
        if referer:
            return RedirectResponse(referer)
        else:
            return RedirectResponse(request.url_for("admin:list", identity=self.identity))

admin.add_view(UserAdmin)

可用的操作选项：

• name：该操作在 URL 中使用的名称。

• label：描述该操作的字符串。

• add_in_list：布尔值，指示该操作是否应在列表页中显示。

• add_in_detail：布尔值，指示该操作是否应在详情页中显示。

• confirmation_message：如果定义，将弹出一个模态窗口，询问用户确认后再调用操作方法。