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 例

媒体

Image

rx.image

官方文档

工坊订单

请在海报商品卡片的上方铺满商品照片，并能用按钮查看其他照片。

rx.image 是显示图片的 HTML <img> 元素。在 src 里填图片地址：可以是外部地址（https://…）；如果是放在应用 assets 文件夹里的文件，就用 /logo.png 这样以 / 开头的路径。alt 里写给看不到图片的人的说明。

rx.image(src="https://picsum.photos/id/1015/400/250", alt="A river between mountains", width="240px", height="auto")

试着改属性

rx.image 和 Box 一样接受样式属性。先定好尺寸，再用 object_fit 选择图片如何适应盒子。

Sample photo — 固定 height 后，比例就和原图不同了。这时 object_fit 为 cover 会裁切填满，为 contain 会缩小到完整显示，为 fill 会拉伸。

属性	取值	默认值	用途
`src`	地址、`/assets 路径`、State 值、PIL 图片	无	要显示的图片。作为第一个子元素传入也会成为 `src`
`alt`	字符串	无	图片说明（供屏幕阅读器使用，图片加载失败时显示）
`loading`	`"eager"` `"lazy"`	`"eager"`	为 `"lazy"` 时，接近可视区域才下载
`decoding`	`"async"` `"auto"` `"sync"`	`"auto"`	图片解码是否与页面渲染分开进行
`src_set` · `sizes`	字符串	无	按屏幕宽度挑选合适尺寸的图片
`cross_origin`	`"anonymous"` `"use-credentials"`	无	其他域名图片的 CORS 请求方式
`referrer_policy`	`"no-referrer"` `"origin"` …	无	请求图片时发送的 referrer
`use_map`	`"#映射名"`	无	关联图片上的点击区域（`<map>`）
样式	`width` `height` `object_fit` `border_radius` `border` …		像 Box 一样用 CSS 属性修饰

事件接受 on_click 这类基础事件。

像 Box 一样修饰

border_radius、border、box_shadow 等样式属性可以直接使用。border_radius="50%" 的正方形图片会变成圆形。在 0.10 中，像第三张图那样把地址作为第一个子元素传入，也会被当作 src。

rx.flex(
    rx.image(
        src="https://picsum.photos/id/237/300/300",
        alt="A black puppy",
        width="120px",
        height="auto",
        border_radius="15px 50px",
        border="5px solid #555",
    ),
    rx.image(
        src="https://picsum.photos/id/1025/300/300",
        alt="A pug in a blanket",
        width="120px",
        border_radius="50%",
        box_shadow="0 4px 14px rgba(0, 0, 0, 0.25)",
    ),
    rx.image("https://picsum.photos/id/1043/300/300", alt="Positional src", width="120px", border_radius="8px"),
    spacing="4",
    align="center",
    wrap="wrap",
)

适应盒子：object_fit

把 400×250 的图片放进 160×160 的盒子。cover 保持比例填满，裁掉溢出的部分；contain 保持比例缩小到完整显示，留出空白；fill 忽略比例直接拉伸。商品列表这类需要统一格子尺寸的场景，通常用 cover。

cover

contain

fill

rx.flex(
    rx.vstack(
        rx.image(src="https://picsum.photos/id/1039/400/250", alt="cover", width="160px", height="160px", object_fit="cover"),
        rx.code("cover"),
        align="center",
    ),
    rx.vstack(
        rx.image(src="https://picsum.photos/id/1039/400/250", alt="contain", width="160px", height="160px", object_fit="contain",
                 background=rx.color("gray", 4)),
        rx.code("contain"),
        align="center",
    ),
    rx.vstack(
        rx.image(src="https://picsum.photos/id/1039/400/250", alt="fill", width="160px", height="160px", object_fit="fill"),
        rx.code("fill"),
        align="center",
    ),
    spacing="4",
    wrap="wrap",
)

适配屏幕宽度的图片与延迟加载

在 src_set 里列出同一张图片的多个尺寸，再用 sizes 告诉浏览器各屏幕宽度下使用多宽，浏览器就会挑选合适的文件下载。窄屏下载小文件，速度更快。loading="lazy" 会把下载推迟到图片接近可视区域时。

rx.image(
    src="https://picsum.photos/id/1060/800/500",
    src_set="https://picsum.photos/id/1060/400/250 400w, https://picsum.photos/id/1060/800/500 800w",
    sizes="(max-width: 600px) 400px, 800px",
    alt="Coffee being poured",
    loading="lazy",
    decoding="async",
    width="100%",
    max_width="400px",
    border_radius="8px",
)

用 State 切换图片

在 src 里放 State 值，值变化时图片也会变。点击下面的小图，大图就会切换。把地址列表放进 State，只改变选中的序号。

class ImageGalleryState(rx.State):
    photos: list[str] = [
        "https://picsum.photos/id/1015/480/300",
        "https://picsum.photos/id/1025/480/300",
        "https://picsum.photos/id/1043/480/300",
        "https://picsum.photos/id/1080/480/300",
    ]
    current: int = 0

    @rx.event
    def show(self, i: int):
        self.current = i


rx.vstack(
    rx.image(
        src=ImageGalleryState.photos[ImageGalleryState.current],
        alt="Selected photo",
        width="100%",
        max_width="480px",
        aspect_ratio="16 / 10",
        object_fit="cover",
        border_radius="8px",
    ),
    rx.flex(
        rx.foreach(
            ImageGalleryState.photos,
            lambda p, i: rx.image(
                src=p,
                alt="Thumbnail",
                width="72px",
                height="45px",
                object_fit="cover",
                border_radius="4px",
                cursor="pointer",
                opacity=rx.cond(i == ImageGalleryState.current, "1", "0.45"),
                on_click=ImageGalleryState.show(i),
            ),
        ),
        spacing="2",
    ),
    spacing="3",
)

应用内的文件与 PIL 图片

应用 assets 文件夹里的文件，用以 / 开头的路径引用。另外，在 State 变量里放 Pillow（PIL）的 Image 对象并传给 src，Reflex 会把它转换成图片数据发送过去。适合在服务器上生成或修改图片后立即显示。本站没有安装 Pillow，所以只展示代码（需要 pip install pillow）。

rx.image(src="/logo.png", alt="Logo", width="80px")   # assets/logo.png

from PIL import Image
import requests

class ImagePilState(rx.State):
    url: str = "https://picsum.photos/id/1/200/300"
    image: Image.Image = Image.open(requests.get(url, stream=True).raw)

def image_pil_example():
    return rx.image(src=ImagePilState.image, alt="Dynamically generated image")

rx.image 只接受地址和 PIL 图片。OpenCV（cv2）图片要先转成 PIL 图片，或者保存为 assets 文件夹里的文件后再传入。要让用户上传图片，请参阅 Upload 页面。

完成订单

用 rx.inset 去掉卡片上方的内边距，让图片铺满。高度是固定的，所以用 object_fit="cover" 裁切适配。照片与上面的图库共用同一个 State，点击按钮时两个示例的照片会一起切换。

Mountain Trip Print

A3 poster, matte paper

rx.card(
    rx.inset(
        rx.image(
            src=ImageGalleryState.photos[ImageGalleryState.current],
            alt="Product photo",
            width="100%",
            height="180px",
            object_fit="cover",
            loading="lazy",
        ),
        side="top",
        pb="current",
    ),
    rx.text("Mountain Trip Print", weight="bold"),
    rx.text("A3 poster, matte paper", size="2", color_scheme="gray"),
    rx.button("Next photo", size="1", variant="soft", margin_top="8px",
              on_click=ImageGalleryState.show((ImageGalleryState.current + 1) % 4)),
    max_width="300px",
)

工坊笔记

rx.image(src="…", alt="…")。接受外部地址、/assets 路径、State 值和 PIL 图片。
样式和 Box 一样：width、height、border_radius、border。
固定格子尺寸时，用 object_fit="cover" 裁切填满（contain 则完整显示）。
用 src_set、sizes 提供适配屏幕宽度的文件，用 loading="lazy" 延迟加载。
一定要写 alt，为看不到图片的人，也为图片加载失败的时候。

← 上一课

动态渲染 · Auto Scroll

下一课 →

媒体 · Audio

订阅新课时和新课程通知

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

问答

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

ReflexKR

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

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

联盟链接与赞助说明

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

Built with Reflex