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 例

媒体

Audio

rx.audio

官方文档

工坊订单

请在店铺管理后台的设置里加一栏，可以试听新订单提示音并调节音量。

rx.audio 是播放音频文件的播放器。在 src 里填音频地址：可以是外部地址；如果是 assets 文件夹里的 test.mp3，就写 src="/test.mp3"。它内部基于 react-player，与 rx.video 是同一个组件，所以属性和事件完全相同。

rx.audio(
    src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
    width="100%",
    height="54px",
)

试着改属性

播放和暂停也是属性。打开 playing 就播放，关掉就停止。关掉 controls 后，浏览器的播放控制条会消失，这时要用 State 和按钮自己控制。

试着改属性

playing

loop

controls

muted

volume

0.8

rx.audio(src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3", playing=False, loop=False, controls=True, muted=False, volume=0.8, width="100%", height="54px")

playing 控制播放与停止，volume（0~1）控制音量。打开 loop 后，播放结束会从头再放。

属性	取值	默认值	用途
`src`	地址、地址列表、`{"src": …, "type": …}` 列表	无	要播放的音频
`playing`	`True` / `False`	`False`	播放 / 暂停
`controls`	`True` / `False`	`True`	显示浏览器播放控制条
`loop`	`True` / `False`	`False`	结束后从头再放
`volume`	`0` ~ `1`	`1`	音量
`muted`	`True` / `False`	`False`	静音
`config`	dict	无	按播放器类型的设置（`{"youtube": {…}}` 等）
`disable_remote_playback`	`True` / `False`	`False`	关闭投放到其他设备播放（投屏）
`light`	`True` / `False`	`False`	只显示预览而非播放器，点击后才打开播放器（见 Video 页面）
`width` · `height`	CSS 尺寸	内容尺寸	播放器尺寸

事件	传递的值	触发时机
`on_ready`	无	加载完成，可以播放
`on_start`	无	首次开始播放
`on_play` · `on_pause`	无	开始播放 · 已暂停
`on_playing` · `on_waiting`	无	真正开始出声 · 因缓冲而等待
`on_duration_change`	时长（秒，float）	得知总时长
`on_time_update`	当前位置（秒，float）	播放位置变化（每秒约 4 次）
`on_progress`	`{played, playedSeconds, loaded, loadedSeconds, duration}`	下载数据期间
`on_seeking` · `on_seeked`	无 · 位置（秒）	正在跳转 · 跳转完成
`on_rate_change`	播放速度（float）	播放速度改变
`on_ended`	无	播放到结尾（`loop` 时不触发）
`on_error`	无	播放出错
`on_click_preview`	无	点击了 `light` 预览
`on_enter_picture_in_picture` · `on_leave_picture_in_picture`	无	进入 · 退出画中画

Reflex 把 controls 的默认值设为 True（react-player 本身的默认值是 False）。旧名称 url、on_duration、on_seek 等属性在 0.10 中改成了 src、on_duration_change、on_seeked；使用旧名称时会给出警告，并自动转成新名称。

用事件跟踪播放状态

把 playing 设为 State 值，就能用按钮控制播放和停止。为了在用浏览器控制条暂停时 State 也保持一致，要在 on_play、on_pause 里更新这个值。on_time_update 每秒触发约 4 次，所以用 .throttle(500) 让它每 0.5 秒只发送一次到服务器。

0 / 0 s

Finished: 0

class AudioPlayerState(rx.State):
    playing: bool = False
    status: str = "loading"
    duration: float = 0.0
    position: float = 0.0
    finished: int = 0

    @rx.event
    def toggle(self):
        self.playing = not self.playing

    @rx.event
    def mark_ready(self):
        self.status = "ready"

    @rx.event
    def mark_play(self):
        self.playing = True
        self.status = "playing"

    @rx.event
    def mark_pause(self):
        self.playing = False
        self.status = "paused"

    @rx.event
    def mark_ended(self):
        self.playing = False
        self.status = "ended"
        self.finished += 1

    @rx.event
    def got_duration(self, seconds: float):
        self.duration = round(seconds, 1)

    @rx.event
    def got_time(self, seconds: float):
        self.position = round(seconds, 1)


rx.vstack(
    rx.audio(
        src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
        playing=AudioPlayerState.playing,
        width="100%",
        height="54px",
        on_ready=AudioPlayerState.mark_ready,
        on_play=AudioPlayerState.mark_play,
        on_pause=AudioPlayerState.mark_pause,
        on_ended=AudioPlayerState.mark_ended,
        on_duration_change=AudioPlayerState.got_duration,
        on_time_update=AudioPlayerState.got_time.throttle(500),
    ),
    rx.flex(
        rx.button(
            rx.cond(AudioPlayerState.playing, rx.icon("pause"), rx.icon("play")),
            rx.cond(AudioPlayerState.playing, "Pause", "Play"),
            on_click=AudioPlayerState.toggle,
        ),
        rx.badge(AudioPlayerState.status, variant="soft"),
        rx.text(AudioPlayerState.position, " / ", AudioPlayerState.duration, " s", size="2"),
        rx.text("Finished: ", AudioPlayerState.finished, size="2", color_scheme="gray"),
        spacing="3",
        align="center",
        wrap="wrap",
    ),
    width="100%",
    spacing="3",
)

浏览器的自动播放规则

用户还没在页面上点过任何东西时，浏览器会阻止带声音的自动播放。所以页面一打开就用 playing=True 出声，可能不会播放。比较稳妥的做法是在用户点击按钮之后再播放声音。只有 muted=True 时才允许无声开始播放。

要让用户上传音频文件，请参阅 Upload 页面。上传、用 Python 处理、播放、下载的完整流程，见官方文档里的音频工作流示例。

完成订单

隐藏播放控制条（controls=False，尺寸为 0），只显示试听按钮和音量按钮。播放结束时 on_ended 会把 playing 改回去，按钮就能再次点击了。

Order alert sound

0.5

class AudioChimeState(rx.State):
    playing: bool = False
    volume: float = 0.5

    @rx.event
    def play(self):
        self.playing = True

    @rx.event
    def stop(self):
        self.playing = False

    @rx.event
    def change_volume(self, step: float):
        self.volume = min(1.0, max(0.0, round(self.volume + step, 1)))


rx.card(
    rx.flex(
        rx.icon("bell-ring", color=rx.color("indigo", 10)),
        rx.text("Order alert sound", weight="medium"),
        rx.spacer(),
        rx.icon_button(rx.icon("volume-1"), on_click=AudioChimeState.change_volume(-0.1), variant="soft", size="1", aria_label="Quieter"),
        rx.text(AudioChimeState.volume, size="2", min_width="2em", text_align="center"),
        rx.icon_button(rx.icon("volume-2"), on_click=AudioChimeState.change_volume(0.1), variant="soft", size="1", aria_label="Louder"),
        rx.button(rx.icon("play"), "Preview", on_click=AudioChimeState.play, size="1", loading=AudioChimeState.playing),
        spacing="2",
        align="center",
    ),
    rx.audio(
        src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
        playing=AudioChimeState.playing,
        volume=AudioChimeState.volume,
        controls=False,
        on_ended=AudioChimeState.stop,
        on_pause=AudioChimeState.stop,
        width="0",
        height="0",
    ),
    max_width="420px",
)

工坊笔记

rx.audio(src="…")。外部地址或 assets 路径（/test.mp3）。与 rx.video 是同一个组件。
playing、loop、muted、volume（0~1）用 State 值控制。controls 默认为 True。
用 on_play、on_pause、on_ended 同步 State，on_time_update 用 .throttle 降频。
浏览器会阻止有声自动播放，要在用户点击之后再播放。
0.10 的名称：src、on_duration_change、on_seeked（url、on_duration、on_seek 是旧名称）。

← 上一课

媒体 · Image

下一课 →

媒体 · Video

订阅新课时和新课程通知

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

问答

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

ReflexKR

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

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

联盟链接与赞助说明

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

Built with Reflex