FastUI快速上手指南：30分钟搭建你的第一个FastAPI+React应用

你是否还在为前后端分离开发中频繁切换Python和JavaScript而烦恼？是否想快速构建美观且功能完整的Web应用界面？本文将带你在30分钟内完成FastUI环境搭建，掌握核心组件使用，并构建一个包含用户列表和详情页的完整应用。读完本文后，你将能够独立使用FastUI开发基础Web界面，理解声明式UI开发的核心思想，并通过FastAPI后端无缝驱动React前端。

环境准备与安装

FastUI由Python后端组件和React前端组件构成，推荐使用Python 3.8+环境。通过以下命令完成基础依赖安装：

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或在Windows上执行: venv\Scripts\activate

# 安装核心依赖
pip install fastapi uvicorn fastui

项目完整结构可参考项目教程：README.md，核心组件分布在以下路径：

• Python模型定义：src/python-fastui/fastui/
• 演示应用代码：demo/
• 官方文档：docs/guide.md

第一个FastUI应用：用户管理系统

项目初始化

创建main.py文件，导入必要模块并初始化FastAPI应用：

from fastapi import FastAPI, HTTPException
from fastapi.responses import HTMLResponse
from fastui import FastUI, AnyComponent, prebuilt_html
from fastui.components import Page, Heading, Table, DisplayLookup
from fastui.events import GoToEvent, BackEvent
from pydantic import BaseModel, Field
from datetime import date

app = FastAPI(title="FastUI Demo")

数据模型定义

定义用户数据模型，使用Pydantic实现数据验证：

class User(BaseModel):
    id: int
    name: str
    dob: date = Field(title='Date of Birth')

# 模拟数据库数据
users = [
    User(id=1, name='John', dob=date(1990, 1, 1)),
    User(id=2, name='Jack', dob=date(1991, 1, 1)),
    User(id=3, name='Jill', dob=date(1992, 1, 1)),
    User(id=4, name='Jane', dob=date(1993, 1, 1)),
]

实现用户列表页面

创建API端点返回UI组件定义，FastUI会自动转换为React组件：

@app.get("/api/", response_model=FastUI, response_model_exclude_none=True)
def users_table() -> list[AnyComponent]:
    return [
        Page(
            components=[
                Heading(text='用户列表', level=2),
                Table(
                    data=users,
                    columns=[
                        DisplayLookup(
                            field='name',
                            on_click=GoToEvent(url='/user/{id}/'),
                            title='姓名'
                        ),
                        DisplayLookup(
                            field='dob',
                            mode='date',
                            title='出生日期'
                        ),
                    ],
                ),
            ]
        ),
    ]

用户详情页面实现

添加用户详情页路由，通过ID参数查询用户信息：

@app.get("/api/user/{user_id}/", response_model=FastUI, response_model_exclude_none=True)
def user_profile(user_id: int) -> list[AnyComponent]:
    try:
        user = next(u for u in users if u.id == user_id)
    except StopIteration:
        raise HTTPException(status_code=404, detail="用户不存在")
    return [
        Page(
            components=[
                Heading(text=user.name, level=2),
                BackEvent.as_link(components=[Text(text='返回列表')]),
                Details(data=user),
            ]
        ),
    ]

配置前端页面服务

使用预构建的React组件提供前端界面，无需手动编写JavaScript：

@app.get('/{path:path}')
async def html_landing() -> HTMLResponse:
    """提供预构建的React前端页面"""
    return HTMLResponse(prebuilt_html(title='FastUI用户管理系统'))

完整代码可参考演示应用demo/main.py，该文件实现了更丰富的组件交互示例。

运行与预览

启动应用并访问http://localhost:8000查看效果：

uvicorn main:app --reload

应用启动后将展示响应式用户列表页面，支持以下功能：

• 表格排序与分页
• 点击用户名查看详情
• 日期格式自动转换
• 响应式布局适配

核心组件解析

FastUI提供丰富的预定义组件，以下是项目中常用的组件及其源码位置：

布局组件

• Page：基础容器组件，提供页面级布局
• Heading：标题组件，支持1-6级标题
• Navbar/Footer：导航栏与页脚组件，源码位于src/python-fastui/fastui/components/navbar.py

数据展示组件

• Table：高性能数据表格，支持自定义列渲染
• Details：键值对详情展示
• DisplayLookup：数据格式化组件，支持多种展示模式

交互组件

• Link：页面内导航
• Button：触发事件的按钮组件
• Modal：模态对话框，示例见demo/components_list.py

高级功能与扩展

动态组件加载

通过ServerLoad组件实现动态内容加载，示例代码：

from fastui.components import ServerLoad

ServerLoad(path='/api/dynamic-content/', components=[Spinner(text='加载中...')])

表单处理

使用Form组件处理用户输入，完整示例见demo/forms.py：

from fastui.components.forms import Form, FormField

Form(
    action='/api/submit/',
    method='POST',
    components=[
        FormField(field='name', label='姓名'),
        FormField(field='email', label='邮箱', type='email'),
    ]
)

事件系统

FastUI事件系统支持页面导航、模态框控制等交互，核心事件定义在src/python-fastui/fastui/events.py：

• GoToEvent：页面跳转
• BackEvent：返回上一页
• ModalEvent：控制模态框显示
• ToastEvent：显示提示消息

总结与进阶

通过本文你已掌握FastUI的基础使用，能够快速构建数据驱动的Web界面。FastUI的核心优势在于：

1. 类型安全：Python模型与TypeScript接口严格匹配
2. 开发效率：纯Python代码构建完整React应用
3. 组件丰富：内置20+常用UI组件，源码位于src/python-fastui/fastui/components/

进阶学习建议：

• 探索服务端事件(SSE)集成：demo/sse.py
• 实现认证功能：demo/auth.py
• 自定义React组件：src/npm-fastui/src/components/

收藏本文并关注项目更新，下一篇将深入探讨FastUI状态管理与复杂表单处理。