ReflexKR

Reflex 官方文档

组件工坊：Reflex 组件库 100 例

课程概览

布局

Box

Flex

Stack

Grid

Container

Section

Center

Spacer

Separator

Card

Inset

Aspect Ratio

Fragment

排版

Text

Heading

Link

Code

Markdown

Blockquote

Quote

Strong

Kbd

表单

Button

Input

Text Area

Checkbox

Switch

Radio Group

Select

Slider

Form

Upload

数据展示

Badge

Avatar

Icon

Callout

List

Data List

Code Block

Progress

Spinner

Scroll Area

Moment

展开与切换

Tabs

Accordion

Segmented Control

浮层

Tooltip

Popover

Hover Card

Dialog

Alert Dialog

Drawer

Dropdown Menu

Context Menu

Toast

动态渲染

Cond

Match

Foreach

Auto Scroll

媒体

Image

Audio

Video

表格与数据网格

Table

Data Table

Data Editor

图表

Area Chart

Bar Chart

Line Chart

Composed Chart

Pie Chart

Radar Chart

Radial Bar Chart

Scatter Chart

Funnel Chart

Treemap

Sankey Chart

Error Bar

图表部件

Axis

Cartesian Grid

Chart Tooltip

Legend

Label

Reference

Brush

其他图表库

Plotly

Pyplot

HTML 元素

HTML

HTML Text

HTML Layout

HTML Forms

HTML Media

HTML Tables

SVG

其他工具

Theme

Skeleton

Clipboard

Html Embed

Script

Memo

组件工坊：Reflex 组件库 100 例

浮层

Drawer

rx.drawer.rootrx.drawer.triggerrx.drawer.overlayrx.drawer.portalrx.drawer.contentrx.drawer.close

官方文档

工坊订单

在手机购物页面上点击「筛选」按钮时，从底部滑出一块面板，让用户选择排序方式和库存条件。

rx.drawer 是从屏幕边缘滑入的面板。适合临时展开较多内容，比如从侧边滑出的菜单、从底部升起的选择面板。也可以用手指或鼠标拖动来关闭它。Reflex 用 Vaul 库实现这个组件。

drawer.root：包裹所有部件。方向（direction）和打开状态设置在这里。
drawer.trigger：包裹点击后打开抽屉的元素。
drawer.overlay：打开期间覆盖背后页面的半透明遮罩。
drawer.portal：把内容渲染到页面最外层，避免被其他元素遮挡。
drawer.content：滑入的面板本身。
drawer.close：包裹点击后关闭抽屉的元素。

drawer.content 默认铺满整个屏幕（position: fixed，四边为 0）。因此面板的大小要这样定：把对侧的边设为 "auto"，再直接设定宽度或高度。如果是从左侧滑出的面板，就设置 right="auto" 和 width。

rx.drawer.root(
    rx.drawer.trigger(rx.button("Open Drawer")),
    rx.drawer.overlay(z_index="5"),
    rx.drawer.portal(
        rx.drawer.content(
            rx.flex(
                rx.drawer.close(rx.box(rx.button("Close"))),
                align_items="start",
                direction="column",
            ),
            top="auto",
            right="auto",
            height="100%",
            width="20em",
            padding="2em",
            background_color=rx.color("gray", 2),
        )
    ),
    direction="left",
)

试着改属性

试着改变从右侧滑出的面板（direction="right"、left="auto"）的宽度和颜色。关闭 modal 后，抽屉打开时仍可以点击和滚动背后的页面。

试着改属性

title

width

color

modal

rx.drawer.root(
    rx.drawer.trigger(rx.button("Open panel")),
    rx.drawer.overlay(),
    rx.drawer.portal(
        rx.drawer.content(
            rx.flex(
                rx.drawer.title("Settings"),
                rx.drawer.description("Drag it to the right or press Esc to close."),
                rx.drawer.close(rx.button("Close", size="1")),
                direction="column",
                align_items="start",
                spacing="3",
            ),
            left="auto",
            height="100%",
            width="20em",
            padding="2em",
            background_color=rx.color("gray", 3),
        ),
    ),
    direction="right",
    modal=True,
)

面板的大小和颜色由 drawer.content 的样式属性决定。modal 设置在 drawer.root 上。

属性（root）	取值	默认值	用途
`direction`	`"top"` `"bottom"` `"left"` `"right"`	`"bottom"`	滑入的方向，也决定拖动关闭的方向
`open` · `default_open`	`True` / `False`	-	由 State 决定是否打开（受控）· 一开始就打开
`modal`	`True` / `False`	`True`	为 `False` 时，打开状态下仍可点击和滚动外部
`dismissible`	`True` / `False`	-	为 `False` 时，拖动、点击外部和 Esc 都不会关闭（与 `open` 搭配使用）
`handle_only`	`True` / `False`	-	为 `True` 时只能通过 `drawer.handle` 拖动
`snap_points`	0~1 之间的数字或 `"px"` 列表	-	可停靠的高度（只能用 Python 值，不能用 State 值）
`fade_from_index`	整数	最后一个停靠点	从第几个停靠点开始让背景变暗
`close_threshold`	0~1	-	拖动多远会关闭
`scroll_lock_timeout`	毫秒	`500`	在面板内滚动后禁止拖动的时长
`should_scale_background`	`True` / `False`	-	让背后页面略微缩小的效果（需要 `vaul-drawer-wrapper`）
`prevent_scroll_restoration`	`True` / `False`	`True`	关闭后不恢复滚动位置
`on_open_change`	事件	-	打开或关闭时触发，传入新的打开状态（bool）
`on_animation_end`	事件	-	打开/关闭动画结束时触发，传入当时的打开状态

drawer.content 有 on_open_auto_focus、on_close_auto_focus、on_escape_key_down、on_pointer_down_outside、on_interact_outside 事件。其他部件基本只接受 as_child。

四个方向

每种 direction 贴靠的边不同，所以要把对侧的边设为 "auto"。从上方或下方滑出的面板，设定的是高度而不是宽度。四个抽屉的做法相同，所以封装成了一个小函数。

def drawer_edge_demo(side: str, **position):
    return rx.drawer.root(
        rx.drawer.trigger(rx.button(side, variant="soft")),
        rx.drawer.overlay(),
        rx.drawer.portal(
            rx.drawer.content(
                rx.flex(
                    rx.drawer.title(f"From the {side}"),
                    rx.drawer.close(rx.button("Close", size="1")),
                    direction="column",
                    align_items="start",
                    spacing="3",
                ),
                padding="2em",
                background_color=rx.color("gray", 2),
                **position,
            ),
        ),
        direction=side,
    )


rx.flex(
    drawer_edge_demo("left", right="auto", width="16em"),
    drawer_edge_demo("right", left="auto", width="16em"),
    drawer_edge_demo("top", bottom="auto", height="30%"),
    drawer_edge_demo("bottom", top="auto", height="30%"),
    spacing="3",
    wrap="wrap",
)

标题、说明与把手

官方文档的部件列表里没有列出，但 0.10 中也有 drawer.title、drawer.description 和 drawer.handle。标题和说明会被屏幕阅读器读出，把手则在面板顶部画一根可拖动的横条。设置 handle_only=True 后只能用把手拖动，可以减少点击面板内按钮时误关面板的情况。

rx.drawer.root(
    rx.drawer.trigger(rx.button("Open sheet")),
    rx.drawer.overlay(),
    rx.drawer.portal(
        rx.drawer.content(
            rx.flex(
                rx.drawer.handle(),
                rx.drawer.title("Share this page"),
                rx.drawer.description("Drag the handle down to close the sheet."),
                rx.flex(
                    rx.button(rx.icon("link"), "Copy link", variant="soft"),
                    rx.button(rx.icon("mail"), "Email", variant="soft"),
                    spacing="3",
                ),
                direction="column",
                spacing="3",
                width="100%",
            ),
            top="auto",
            height="auto",
            padding="1.5em",
            background_color=rx.color("gray", 2),
            border_radius="12px 12px 0 0",
        ),
    ),
    handle_only=True,
)

用 State 控制开关：侧边菜单

把 State 值绑定到 open，点击链接时就能用代码关闭抽屉。同时绑定 on_open_change，让触发按钮、Close 按钮和 Esc 键改变的打开状态也回写到 State。因为 modal=False，抽屉打开时页面仍可滚动；点击链接后，抽屉关闭并跳转到对应章节。

Section 1

Section 2

class DrawerSidebarState(rx.State):
    is_open: bool = False

    @rx.event
    def set_is_open(self, value: bool):
        self.is_open = value

    @rx.event
    def close_drawer(self):
        self.is_open = False


rx.vstack(
    rx.drawer.root(
        rx.drawer.trigger(rx.button("Open Drawer")),
        rx.drawer.overlay(),
        rx.drawer.portal(
            rx.drawer.content(
                rx.flex(
                    rx.drawer.close(rx.button("Close")),
                    rx.link("Section 1", href="#drawer-section-1", on_click=DrawerSidebarState.close_drawer),
                    rx.link("Section 2", href="#drawer-section-2", on_click=DrawerSidebarState.close_drawer),
                    align_items="start",
                    direction="column",
                    spacing="3",
                ),
                right="auto",
                height="100%",
                width="16em",
                padding="2em",
                background_color=rx.color("grass", 4),
            ),
        ),
        open=DrawerSidebarState.is_open,
        on_open_change=DrawerSidebarState.set_is_open,
        direction="left",
        modal=False,
    ),
    rx.section(rx.heading("Section 1", size="5"), id="drawer-section-1", height="160px", padding="1em 0"),
    rx.section(rx.heading("Section 2", size="5"), id="drawer-section-2", height="160px", padding="1em 0"),
)

完成订单

这是从底部升起的筛选面板。用开关和单选按钮选中的值会立即写入 State，点击「Show results」后，事件处理器用 self.open = False 收起面板。把面板拖下来关闭，选中的值也同样会保留。

Sort: Newest

class DrawerFilterState(rx.State):
    open: bool = False
    in_stock: bool = False
    sort: str = "Newest"

    @rx.event
    def set_open(self, value: bool):
        self.open = value

    @rx.event
    def set_in_stock(self, value: bool):
        self.in_stock = value

    @rx.event
    def set_sort(self, value: str):
        self.sort = value

    @rx.event
    def apply(self):
        self.open = False


rx.flex(
    rx.text("Sort: ", DrawerFilterState.sort, rx.cond(DrawerFilterState.in_stock, " · in stock only", ""), size="2"),
    rx.drawer.root(
        rx.drawer.trigger(rx.button(rx.icon("sliders-horizontal"), "Filters", variant="outline")),
        rx.drawer.overlay(),
        rx.drawer.portal(
            rx.drawer.content(
                rx.flex(
                    rx.drawer.handle(),
                    rx.drawer.title("Filters"),
                    rx.flex(rx.switch(checked=DrawerFilterState.in_stock, on_change=DrawerFilterState.set_in_stock),
                            rx.text("In stock only", size="2"), spacing="2", align="center"),
                    rx.radio(["Newest", "Price: low", "Price: high"], value=DrawerFilterState.sort,
                             on_change=DrawerFilterState.set_sort, direction="row"),
                    rx.button("Show results", on_click=DrawerFilterState.apply, width="100%"),
                    direction="column",
                    spacing="4",
                    width="100%",
                    max_width="480px",
                    margin="0 auto",
                ),
                top="auto",
                height="auto",
                padding="1.5em",
                background_color=rx.color("gray", 2),
                border_radius="12px 12px 0 0",
            ),
        ),
        open=DrawerFilterState.open,
        on_open_change=DrawerFilterState.set_open,
        direction="bottom",
    ),
    spacing="3",
    align="center",
    wrap="wrap",
)

工坊笔记

root(direction) > trigger · overlay · portal > content > close。方向默认是 bottom。
content 会铺满整个屏幕，所以要把对侧的边设为 "auto"，再设定 width 或 height。
用 open + on_open_change 控制时，可以在链接或按钮的事件处理器里关闭抽屉。
modal=False 让抽屉打开时仍能使用背后的页面，handle_only=True 让面板只能用把手拖动。
snap_points 是编译时确定的值，不能传入 State 值。

← 上一课

浮层 · Alert Dialog

下一课 →

浮层 · Dropdown Menu

订阅新课时和新课程通知

本课程新增课时或推出后续课程时，我们会发邮件通知你。

问答

关于本课有任何疑问都可以在这里留言。所有语言版本页面的提问会汇集在一起。

ReflexKR

动手学 Python 和 Reflex。所有示例均已在 Reflex 0.10.0 上实际运行验证。

ReflexKR 免费，没有横幅广告。如果对你有帮助，欢迎请我们喝杯咖啡。 ☕ 请我们喝杯咖啡

联盟链接与赞助说明

한국어 English 日本語简体中文 Español Deutsch

Built with Reflex