本文目录导读：
Reflex 是一个基于 Python 的全栈 Web 框架，允许你仅用纯 Python 构建动态的 Web 界面，它的核心思想是使用组件（Components）来构建 UI。
以下是关于 Reflex 页面组件的使用指南,涵盖从基础到进阶的内容。
核心概念：State 和 Component
在 Reflex 中：
- State：定义应用的变量和逻辑（相当于后端的“大脑”）。
- Component：定义 UI 的布局和交互元素（相当于前端的“皮肤”）。
- Event Handler：State 中的方法，用于响应用户操作（如点击按钮）。
基础组件使用
Reflex 提供了大量内置组件，如 rx.text、rx.button、rx.input 等。
示例：一个简单的计数器页面
import reflex as rx
# 1. 定义 State
class State(rx.State):
count: int = 0 # 状态变量
def increment(self):
self.count += 1 # 事件处理器：增加计数
def decrement(self):
self.count -= 1 # 事件处理器：减少计数
# 2. 定义页面组件（一个函数）
def index() -> rx.Component:
return rx.container(
rx.heading("计数器", size="3"), # 使用 heading 组件
rx.hstack( # 使用水平堆叠组件
rx.button(
"减 1",
on_click=State.decrement, # 绑定事件
color_scheme="red"
),
rx.text(State.count, size="5"), # 显示状态变量，自动响应变化
rx.button(
"加 1",
on_click=State.increment,
color_scheme="green"
),
spacing="3"
),
padding_y="2em",
)
# 3. 创建应用并添加页面
app = rx.App()
app.add_page(index, route="/") # 将 index 组件添加到根路径
# 4. 运行（终端执行： reflex run）
关键点：
State.count：在 UI 中直接引用状态变量，Reflex 会自动保持 UI 同步。on_click：事件绑定，参数是 State 中的方法（注意不要加括号）。
常用内置组件分类
| 类别 | 组件示例 | 用途 |
|---|---|---|
| 布局 | rx.box, rx.container, rx.hstack, rx.vstack, rx.grid, rx.center |
组织页面结构，控制元素位置。 |
| 文本 | rx.text, rx.heading, rx.markdown, rx.code |
显示文字内容。 |
| 表单 | rx.input, rx.button, rx.select, rx.checkbox, rx.slider, rx.text_area |
接收用户输入。 |
| 媒体 | rx.image, rx.video, rx.icon |
显示图片、视频、图标。 |
| 数据 | rx.table, rx.list, rx.plotly (需安装) |
展示表格、列表、图表。 |
| 反馈 | rx.alert, rx.progress, rx.badge, rx.toast |
显示加载中、提示、状态标记。 |
处理用户输入（Form 组件示例）
时，需要使用 事件绑定 和 状态变量 来捕获。
import reflex as rx
class FormState(rx.State):
name: str = ""
submitted_name: str = ""
def handle_submit(self, form_data: dict):
# form_data 是一个字典，key 是 input 的 name 属性
self.submitted_name = form_data.get("name")
def set_name(self, value):
# 或者使用 on_change 实时绑定
self.name = value
def form_example() -> rx.Component:
return rx.container(
rx.vstack(
rx.form(
rx.input(
name="name", # 必须设置 name 用于 form_data 识别
placeholder="输入你的名字",
on_change=FormState.set_name, # 实时更新状态
),
rx.button("提交", type_="submit"), # 必须 type_="submit"
on_submit=FormState.handle_submit, # 表单提交处理器
reset_on_submit=True,
),
rx.text(f"你输入的名字是：{FormState.name}"), # 实时显示
rx.text(f"最后提交的是：{FormState.submitted_name}"), # 提交后显示
),
padding="2em",
)
# 添加到 app
# app.add_page(form_example)
状态组件和条件渲染
使用 rx.cond 根据状态条件决定显示哪个组件。
import reflex as rx
class ToggleState(rx.State):
show: bool = True
def toggle(self):
self.show = not self.show
def conditional_example() -> rx.Component:
return rx.vstack(
rx.button("切换显示", on_click=ToggleState.toggle),
# show 为 True，显示 "可见"，否则显示 "隐藏"
rx.cond(
ToggleState.show,
rx.text("可见", color="green"),
rx.text("隐藏", color="red"),
),
)
列表和循环渲染
使用 rx.foreach 渲染列表数据。
import reflex as rx
class ListState(rx.State):
items: list[str] = ["苹果", "香蕉", "樱桃", "日期"]
def list_example() -> rx.Component:
# rx.foreach 接受一个状态列表和一个渲染函数
def render_item(item: str) -> rx.Component:
return rx.list_item(rx.text(item)) # 为每个 item 创建一个列表项
return rx.vstack(
rx.heading("水果列表"),
rx.list(
rx.foreach(ListState.items, render_item)
),
)
属性设置技巧
- 动态属性：属性值可以是状态变量。
<rx.text color=State.text_color>。 - 自定义样式：使用
style字典或直接传入 CSS 属性。rx.button("Styled", background_color="red", border_radius="lg") - 响应式设计：Reflex 使用
rx.breakpoints或 Tailwind CSS (v0.6.0+) 实现。
自定义组件（组件化）
将 UI 逻辑封装成函数,便于复用。
def user_card(name: str, email: str) -> rx.Component:
return rx.card(
rx.vstack(
rx.avatar(name=name),
rx.text(name, weight="bold"),
rx.text(email),
),
width="200px",
)
def profile_page() -> rx.Component:
return rx.hstack(
user_card("Alice", "alice@example.com"),
user_card("Bob", "bob@example.com"),
spacing="4",
)
使用 Reflex 页面组件的步骤：
- 定义 State：用
rx.State管理变量和行为。 - 组合组件：像搭积木一样使用
rx.___构建 UI，组件是 Python 函数调用，children参数作为子元素。 - 绑定事件：将
on_click、on_change等事件关联到 State 的方法。 - 响应数据：直接在 UI 中引用
State.变量名。 - 渲染列表：使用
rx.foreach遍历状态中的列表。
推荐实践： 先从 rx.container、rx.vstack、rx.hstack 三个布局组件开始，配合 rx.text、rx.button 和 rx.input 搭建基础交互页面,很快就能上手。
