Python Reflex 使用手册
以下是一份详细的 Python Reflex 使用手册，包含核心概念、组件使用和代码示例：
Python Reflex 全栈开发手册
目录
框架简介
Reflex 是一个基于 React 的纯 Python 全栈框架，特点：
- 实时前端更新
- 自动处理客户端-服务器通信
- 支持响应式布局
- 内置组件库
- 基于 FastAPI 的后端
环境配置
安装要求
- Python 3.7+
- Node.js 16+
# 创建虚拟环境
python -m venv reflex_env
source reflex_env/bin/activate # Linux/Mac
reflex_env\Scripts\activate # Windows
# 安装框架
pip install reflex项目结构
my_app/
├── my_app/ # 主包
│ ├── __init__.py # 项目初始化
│ └── my_app.py # 主应用文件
├── assets/ # 静态资源
├── .env # 环境变量
└── requirements.txt # 依赖列表核心概念
基本应用结构
import reflex as rx
class State(rx.State):
"""应用状态定义"""
def index():
"""页面组件定义"""
return rx.container(
rx.heading("欢迎使用Reflex"),
rx.text("当前状态：", State.text_var)
)
app = rx.App()
app.add_page(index, route="/") # 注册页面
app.compile() # 编译应用组件系统
基础组件使用
def form_example():
return rx.vstack(
rx.input(
placeholder="输入姓名",
on_change=State.set_name, # 绑定状态变更
width="300px"
),
rx.button(
"提交",
on_click=State.handle_submit,
color_scheme="blue"
),
rx.divider(),
rx.text("您输入的是：", State.name)
)布局组件
def responsive_layout():
return rx.responsive_grid(
rx.box("左侧内容", bg="blue.100", p=4, col_span=2),
rx.box("右侧内容", bg="green.100", p=4),
columns=[1, 2, 3], # 响应式列数
spacing="4"
)状态管理
基础状态类
class CounterState(rx.State):
count: int = 0 # 自动响应式变量
def increment(self):
self.count += 1
def decrement(self):
self.count -= 1
def counter():
return rx.hstack(
rx.button("-", on_click=CounterState.decrement),
rx.text(CounterState.count),
rx.button("+", on_click=CounterState.increment),
align="center"
)复杂状态管理
class FormState(rx.State):
username: str = ""
password: str = ""
submitted: bool = False
def handle_submit(self):
self.submitted = True
yield [rx.set_value("password", "")] # 清除密码字段
@rx.var
def form_valid(self) -> bool:
return len(self.username) > 3 and len(self.password) > 6路由系统
多页面配置
def about_page():
return rx.box(rx.heading("关于我们"), rx.link("返回首页", href="/"))
app = rx.App()
app.add_page(index, route="/")
app.add_page(about_page, route="/about")动态路由
class PostState(rx.State):
@rx.var
def post_id(self) -> str:
return self.router.page.params.get("id", "0")
def post_detail():
return rx.vstack(
rx.heading(f"文章ID：{PostState.post_id}"),
rx.text("动态路由参数示例")
)
app.add_page(
post_detail,
route="/posts/[id]",
on_load=PostState.load_post # 页面加载时触发
)样式处理
Tailwind CSS 集成
rx.box(
"样式示例",
class_name="p-4 bg-blue-500 rounded-lg shadow-lg",
_hover={"transform": "scale(1.05)"}
)全局样式配置
app = rx.App(
style={
"font_family": "Inter",
"theme": rx.theme(
appearance="dark", # 暗黑模式
has_backdrop=True
)
}
)API 集成
后端路由定义
import requests
class APICallState(rx.State):
data: dict = {}
loading: bool = False
async def fetch_data(self):
self.loading = True
yield
response = requests.get("https://api.example.com/data")
self.data = response.json()
self.loading = False
def api_example():
return rx.cond(
APICallState.loading,
rx.spinner(),
rx.json(data=APICallState.data)
)部署指南
生产环境配置
# 安装生产依赖
pip install gunicorn uvicorn
# 设置环境变量
export REFLEX_ENV=productionDocker 部署
FROM python:3.9-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["reflex", "run", "--host", "0.0.0.0", "--port", "80"]完整示例：待办事项应用
class TodoState(rx.State):
items: list[str] = ["学习Reflex"]
new_item: str = ""
def add_item(self):
if self.new_item.strip():
self.items.append(self.new_item)
self.new_item = ""
def delete_item(self, item: str):
self.items.remove(item)
def todo_list():
return rx.container(
rx.heading("待办事项"),
rx.input(
value=TodoState.new_item,
on_change=TodoState.set_new_item,
placeholder="添加新事项"
),
rx.button("添加", on_click=TodoState.add_item),
rx.vstack(
rx.foreach(
TodoState.items,
lambda item: rx.hstack(
rx.text(item),
rx.button(
"删除",
on_click=lambda: TodoState.delete_item(item)
)
)
),
spacing="2"
),
max_width="600px",
padding="2rem"
)最佳实践
- 使用小型状态类管理不同功能模块
- 优先使用内置组件保持一致性
- 合理使用
rx.foreach处理列表数据 - 通过
@rx.var创建计算属性 - 使用
rx.cond处理条件渲染 - 为复杂组件创建自定义组件
- 定期运行
reflex db migrate管理数据库变更
常见问题
Q: 如何调试状态变更？
A: 在开发模式下运行时，访问 /state 查看当前状态
Q: 如何自定义404页面？
A: 添加 app.add_page(not_found, route="/404")
Q: 如何集成第三方React组件？
A: 使用 rx.chakra 命名空间或创建自定义组件
本手册覆盖了Reflex的核心功能，建议通过官方文档和示例项目深入学习更高级的用法。