ex4nicegui 0.9.3 使用文档

本仓库 `pyproject.toml` 标注 requires-python >= 3.9，依赖 nicegui~=3.5（用 3.8.0 一般也可工作）

适用版本：Python 3.10.5、NiceGUI 3.8.0、ex4nicegui 0.9.3 项目元信息：本仓库

1. 安装与导入

1.1 安装

pip install ex4nicegui==0.9.3

1.2 基本导入方式

from nicegui import ui
import ex4nicegui as ex4
from ex4nicegui import rxui  # reactive UI：可响应式绑定的 UI 包装层
from ex4nicegui import bi    # BI 模块
from ex4nicegui import toolbox as tb  # VueUse/工具箱
from ex4nicegui import layout as ly   # 布局扩展（rxFlex/gridFlex）

2. 核心概念：MaybeRef / Ref / Getter

ex4nicegui 的绝大多数“可绑定参数”都支持三种输入形式（类型名在源码中叫 TMaybeRef/TGetterOrReadonlyRef）：

普通值："hello", 123, True
Ref（可变引用）：通过 to_ref/ref/deep_ref 创建，访问/修改用 .value
Getter（函数）：lambda: ...，每次取值都会计算一次；通常配合 ref_computed 更常用

示例：

from ex4nicegui import to_ref, to_value, is_ref

a = to_ref(1)
assert is_ref(a)
assert to_value(a) == 1
assert to_value(lambda: a.value + 1) == 2
assert to_value(123) == 123

3. 顶层 API（`import ex4nicegui as ex4` / `from ex4nicegui import ...`）

下面这些是 ex4nicegui/__init__.py 明确导出的公共 API（__all__）。

3.1 rxui（响应式 UI 命名空间）

rxui：from ex4nicegui import rxui
里面包含：响应式组件工厂（button/input/table/...）、vfor/vmodel、ViewModel、hooks 等，详见第 4 章。

3.2 `to_ref(maybe_ref, is_deep=False)`

来源：ex4nicegui/utils/signals.py

作用：把“值/Getter/Ref”统一成一个 可写 Ref。如果传入本身就是 Ref，会原样返回。

签名：

to_ref(maybe_ref, is_deep: bool = False) -> Ref

参数：

maybe_ref：可以是普通值、Ref、Getter
is_deep：是否深层响应（传给底层 signal 的 shallow/deep）

用法：

from ex4nicegui import to_ref

a = to_ref(1)
a.value += 1

b = to_ref(a)      # 还是同一个 ref
c = to_ref({"x": 1}, is_deep=True)  # 深层响应对象

3.3 `ref(value, is_deep=False)`

来源：ex4nicegui/utils/signals.py

作用：创建一个新的 Ref（底层用 signe.signal），适合你明确要“新建一个 ref”的场景。

签名：

ref(value, is_deep: bool = False) -> Ref

备注：

对于 str/int/float/date/datetime 等简单值，内部会开启“相等比较”以减少重复赋值触发。
None 有特殊比较逻辑，避免重复赋值 None 造成无意义触发。

用法：

from ex4nicegui import ref

count = ref(0)
count.value = 1

3.4 `deep_ref(value)`

来源：ex4nicegui/utils/signals.py

作用：to_ref(value, is_deep=True) 的便捷形式，适合 list/dict/object 等可变结构。

签名：

deep_ref(value) -> Ref

用法：

from ex4nicegui import deep_ref

data = deep_ref({"a": 1, "b": [1, 2]})
data.value["b"].append(3)  # 深层可追踪

3.5 `reactive(obj)`

来源：ex4nicegui/utils/signals.py

作用：创建一个“响应式代理对象”（底层 signe.reactive），适合希望像“原对象一样操作”但又要追踪变更的场景。

签名：

reactive(obj) -> obj  # 返回同类型的响应式代理

用法：

from ex4nicegui import reactive

state = reactive({"a": 1, "b": []})
state["a"] = 2
state["b"].append(3)

3.6 `to_value(obj)`

来源：ex4nicegui/utils/signals.py

作用：统一“解包”：

Ref -> .value
Getter -> 调用
普通值 -> 原样返回

签名：

to_value(obj) -> Any

用法：

from ex4nicegui import to_ref, to_value

a = to_ref(10)
assert to_value(a) == 10
assert to_value(lambda: a.value * 2) == 20
assert to_value("x") == "x"

3.7 `to_raw(obj)` / `is_reactive(obj)`

来源：直接转发 signe.to_raw / signe.is_reactive

to_raw(obj)：拿到 reactive/proxy 背后的原始对象（或做一次“去代理”）
is_reactive(obj)：判断是否 reactive 对象

3.8 `is_ref(obj)` / `is_setter_ref(obj)`

来源：ex4nicegui/utils/signals.py

is_ref(obj)：Ref 或 RefWrapper 则 True
is_setter_ref(obj)：可作为“双向绑定目标”的 ref（signe.Signal 或 RefWrapper）

你在写表单控件双向绑定时很常用：传入的 value= 如果是 setter-ref，则组件会把用户输入写回 .value。

3.9 `on(refs, onchanges=False, priority_level=1, effect_kws=None, deep=True, scope=None)`

来源：ex4nicegui/utils/signals.py

作用：watch 一个或多个源（Ref/Getter/ReadonlyRef/RefWrapper…），源变化时触发回调。

返回：装饰器（Decorator），用法是 @on(...)。

签名（核心参数）：

on(
  refs,
  onchanges: bool = False,
  priority_level: int = 1,
  effect_kws: dict | None = None,
  deep: bool = True,
  scope: Scope | None = None,
) -> Callable[[fn], watcher]

关键参数含义：

refs：可以是单个，也可以是列表；也允许传 RefWrapper
onchanges：
- False：更偏“立即/初始化也会跑”（具体由底层 signe.on 行为决定）
- True：更偏“只在变化时跑”
deep：深度追踪（特别是 list/dict/object 等）
scope：将 watcher 归入某个 scope，便于统一释放（见 new_scope）

示例（监听多个）：

from nicegui import ui
from ex4nicegui import to_ref, on, ref_computed

a = to_ref(1)
b = to_ref(2)
text = ref_computed(lambda: f"a={a.value}, b={b.value}")

@on([a, b, text], onchanges=True)
def _():
    ui.notify(text.value)

3.10 `batch(fn)` / `event_batch(fn)`

来源：ex4nicegui/utils/signals.py

作用：把多个 .value 变更合并到同一 tick 执行，减少中间态触发次数。

batch(fn)：手动包裹一段同步逻辑
event_batch(fn)：更偏事件回调用装饰器（内部也是 batch）

示例：

from ex4nicegui import to_ref, event_batch

a = to_ref(0)
b = to_ref(0)

@event_batch
def click():
    a.value += 1
    b.value += 1

3.11 `ref_computed(fn, desc="", debug_trigger=None, priority_level=1, debug_name=None)`

来源：ex4nicegui/utils/refComputed.py

作用：创建只读的 computed-ref（底层 signe.Computed），自动追踪依赖并更新。

用法 1：直接创建

from ex4nicegui import to_ref, ref_computed

a = to_ref(1)
b = ref_computed(lambda: a.value + 1)

用法 2：装饰器

from ex4nicegui import ref_computed

@ref_computed
def now_str():
    ...

用法 3：作为类字段（ViewModel 的 cached_var/内部 computed 也用到类似技巧） 源码支持把“类中定义的方法”转换成 computed（通过 __set_name__ 注入）。

3.12 `async_computed(refs, init=None, evaluating=None, onchanges=True, debug_trigger=None, debug_name=None)`

来源：ex4nicegui/utils/asyncComputed.py

作用：异步 computed。依赖变化后触发异步计算，计算结果作为一个 ref 输出。

参数：

refs：单个或多个依赖源
init：首次异步完成前的初始值
evaluating：可传一个 Ref[bool] 接收“正在计算”状态
onchanges：是否仅在变化时触发

示例：

from ex4nicegui import to_ref, async_computed

keyword = to_ref("hello")

result = async_computed(keyword, init="loading...")

@result
async def _(kw):  # 具体取决于 signe.async_computed 返回对象的调用方式
    ...

注：ex4nicegui 这里直接调用 signe.async_computed(...)，具体 await/回调风格以 signe 为准。

3.13 `effect(fn, priority_level=1, debug_trigger=None, debug_name=None)`

来源：ex4nicegui/utils/effect.py

作用：立即运行一次，并在依赖变化后自动重跑（类似 watchEffect）。ex4nicegui 把它调度到 UI scheduler 的 post 阶段。

示例：

from nicegui import ui
from ex4nicegui import to_ref, effect

a = to_ref(0)

@effect
def _():
    ui.notify(f"a={a.value}")

3.14 `effect_refreshable(fn, refs=[])`

来源：ex4nicegui/utils/refreshable.py

作用：把一段“创建 UI 的函数”做成可自动刷新的 refreshable 视图；并且提供了异步渲染缓冲，避免 await 时界面空白。

两种用法：

用法 1：直接实例化（构造时就渲染并建立监听）

from ex4nicegui.utils.refreshable import effect_refreshable
from ex4nicegui import to_ref

a = to_ref(1)

def view():
    ui.label(lambda: f"a={a.value}")

effect_refreshable(view, refs=[a])

用法 2：装饰器形式

from ex4nicegui import effect_refreshable, to_ref

a = to_ref(1)

@effect_refreshable.on([a])
def view():
    ui.label(lambda: f"a={a.value}")

3.15 `new_scope(detached=False)`

来源：ex4nicegui/utils/clientScope.py

作用：创建一个 scope，用来“收集并统一释放”其内部注册的 watch/effect/on 等（特别适用于组件被删除时清理订阅）。

ex4nicegui 的 rxui.BindableUi 每个实例内部都会创建一个 scope，并在 element delete 时 dispose。

示例（手动管理）：

from ex4nicegui import new_scope, on, to_ref
from nicegui import ui

scope = new_scope()
a = to_ref(0)

@on(a, scope=scope, onchanges=True)
def _():
    ui.notify(a.value)

# 不需要时：
scope.dispose()

3.16 `next_tick(job)`

来源：ex4nicegui/utils/scheduler.py

作用：把一个 job 放到下一次 scheduler tick 执行（适合“等 UI 本轮更新完再做某事”）。

from ex4nicegui import next_tick
from nicegui import ui

def later():
    ui.notify("next tick")

next_tick(later)

3.17 `reset_echarts_dependencies(echarts_js_file)`

来源：ex4nicegui/reactive/EChartsComponent/ECharts.py

作用：把 ECharts 组件依赖的 echarts.min.js 指向你自己的文件（例如 CDN 下载后的本地文件）。

示例：

from ex4nicegui import reset_echarts_dependencies

reset_echarts_dependencies(r"c:\path\to\echarts.min.js")

3.18 `PageState`

来源：ex4nicegui/utils/page_state.py

作用：每个 ui.page 维护一份独立的“页面状态单例”，通过 ContextVar 隔离不同页面/请求上下文。

用法：

from nicegui import ui
from ex4nicegui import rxui, to_ref, PageState

class MyState(PageState):
    def __init__(self):
        self.count = to_ref(0)

def sub_view():
    s = MyState.get()
    rxui.label(lambda: f"count={s.count.value}")

@ui.page("/")
def index():
    s = MyState.get()
    rxui.number(value=s.count)   # 双向绑定
    sub_view()

4. rxui（响应式 UI）完整 API

rxui 位于 ex4nicegui/reactive/__init__.py，它导出大量“与 NiceGUI 同名/近似”的组件工厂，但额外支持：

构造参数可绑定：很多参数支持传 Ref/lambda，会自动绑定到元素属性
双向绑定：输入类组件如果 value= 传的是 setter-ref（Ref/RefWrapper/vmodel 产物），用户输入会写回 .value
统一的 bind_* 方法：所有 BindableUi 都有 bind_prop/bind_classes/bind_style/...

4.1 BindableUi 通用方法（所有 rxui 组件返回的包装对象都具备）

核心类：ex4nicegui/reactive/base.py -> class BindableUi

4.1.1 .props(add=None, remove=None) / .classes(add=None, remove=None, replace=None) / .style(add=None, remove=None, replace=None)

和 NiceGUI 的 element 方法一致，链式返回 self。

4.1.2 .bind_props(props)

作用：把 props 当成“响应式字符串”或“字典形式的 prop->ref”来绑定。

props 可以是：
- dict[str, TMaybeRef[Any]]：自动拼接成 props 字符串并绑定
- TMaybeRef[str]：直接绑定为 props 字符串

示例：

from ex4nicegui import rxui, to_ref

outlined = to_ref(True)
size = to_ref("xs")

rxui.button("click").bind_props({
    "outlined": outlined,
    "size": size,
})

rxui.button("click").bind_props(lambda: f'{"outlined" if outlined.value else ""} size="{size.value}"')

4.1.3 .bind_prop(prop, value)

作用：把某个 prop 绑定到一个 getter/ref（内部会 effect 更新并 element.update()）。

特殊处理：

prop == "visible" -> .bind_visible(...)
prop == "text" 且 element 是 TextElement -> 调 .set_text(...)
prop == "value" 且 element 是 ValueElement -> 调 .set_value(...)

4.1.4 .bind_visible(value) / .bind_not_visible(value)

显示/隐藏绑定。

4.1.5 .bind_classes(classes) / .bind_style(style)

bind_classes 支持：
- dict：{"bg-red": ref_bool, "text-blue": getter_bool}
- list：[getter_str, "static-class"]
- 单个 getter/ref：lambda: "bg-red"
bind_style 支持：
- dict：{"color": ref_color, "width": lambda: "10px"}
- 单个 style 字符串 getter/ref

4.1.6 .scoped_style(selector, style)

作用：给某个容器元素注入“作用域 CSS”，只影响它的子树（通过元素 id 拼接 selector）。

示例：

from ex4nicegui import rxui
from nicegui import ui

with rxui.row().scoped_style("*", "outline: 1px solid red;"):
    ui.label("A")
    ui.label("B")

4.1.7 .tooltip(text)

便捷创建 tooltip（内部用 rxui.tooltip）。

4.2 rxui 基础组件工厂（与 `nicegui.ui.*` 对应）

说明：每个组件都使用 ParameterClassifier 将“可绑定参数（maybeRefs）”分离出来：
非绑定参数：会在创建元素时用 to_value 转换成当前值
绑定参数：创建完后用 bind_prop 绑定到 element

你可以按这个心智模型使用：能填普通值的地方，大多也能填 to_ref(...) 或 lambda: ...。

下面列出 rxui 的导出名（源码 reactive/__init__.py）。

4.2.1 文本/展示

rxui.label(...)
- 常用：rxui.label("text") 或 rxui.label(lambda: f"...{ref.value}...")
rxui.badge(...)
rxui.chip(...)
rxui.icon(name=..., size=...)
rxui.image(source=...)
rxui.html(...)

示例（label 响应式文本）：

from ex4nicegui import rxui, to_ref

count = to_ref(0)
rxui.label(lambda: f"count={count.value}")
rxui.button("inc", on_click=lambda: setattr(count, "value", count.value + 1))

4.2.2 表单/输入（支持双向绑定）

典型组件：

rxui.input(value=..., on_change=..., placeholder=...)
rxui.textarea(value=..., on_change=...)
rxui.number(value=..., on_change=...)
rxui.checkbox(value=..., text=..., on_change=...)
rxui.switch(value=..., on_change=...)
rxui.radio(options=..., value=..., on_change=...)
rxui.select(options=..., value=..., on_change=..., multiple=..., clearable=...)
rxui.slider(value=..., min=..., max=..., on_change=...)
rxui.range(value=..., min=..., max=..., on_change=...)
rxui.toggle(options=..., value=..., on_change=...)
rxui.date(value=..., on_change=...)
rxui.color_picker(value=..., on_change=...)
rxui.upload(...)

双向绑定要点：

若 value= 传入的是“可写 Ref”（is_setter_ref(value)==True），则用户操作会写回 value.value

示例（input 双向绑定）：

from ex4nicegui import rxui, to_ref

name = to_ref("Alice")
rxui.input(value=name)           # 用户输入会写回 name.value
rxui.label(lambda: name.value)   # 同步显示

4.3 `vmodel(ref_obj, *attrs)`：对 dict/list/对象字段做双向绑定

来源：ex4nicegui/reactive/_vmodel.py

作用：把“深层字段”包装成可写 Ref，从而可直接传给 value= 进行双向绑定。

签名：

rxui.vmodel(ref_obj, *attrs) -> setter-ref

示例（深层 dict 字段双向绑定）：

from ex4nicegui import rxui, deep_ref

data = deep_ref({"a": 1, "b": [10, 20]})

rxui.input(value=rxui.vmodel(data.value, "a"))   # 输入 -> data.value["a"]
rxui.input(value=rxui.vmodel(data.value, "b", 0))  # 输入 -> data.value["b"][0]

注意：vmodel 的第一个参数既可以是 ref，也可以是普通对象；如果不是 ref，它会直接取值返回（无绑定效果）。

4.4 `vfor(data, key=...)`：响应式列表渲染

来源：ex4nicegui/reactive/vfor.py

作用：对一个 list（或 list 的 ref/getter）做“增删改”追踪渲染，并为每一行提供一个 VforStore。

签名（装饰器使用）：

@rxui.vfor(items_ref, key="id" | callable)
def _(store: rxui.VforStore):
    ...

data：list 或 Ref[list] 或 getter
key：
- None：默认用 index
- str：用 item[key]/属性取值作为 key
- callable(idx, item)：自定义 key

VforStore 常用方法：

store.raw_index：当前行的固定 index
store.row_index：当前行 index 的 Ref（当列表变更导致行位置变化时会更新）
store.get_item()：拿当前项（普通值）
store.get()：拿当前项的“可写 ref 包装”（适合不可变类型）

示例（字典项双向绑定）：

from ex4nicegui import rxui, to_ref
from nicegui import ui

items = to_ref([
    {"message": "foo", "done": False},
    {"message": "bar", "done": True},
])

@rxui.vfor(items, key="message")
def _(store: rxui.VforStore):
    msg = store.get()["message"]      # 通过 RefWrapper 链式下标获取子字段
    done = store.get()["done"]

    with ui.card():
        rxui.input(value=msg)
        rxui.checkbox(text=msg, value=done)

4.5 ViewModel：类式状态管理（更“像 Vue/前端 MVVM”）

来源：ex4nicegui/reactive/view_model.py

导出：

rxui.ViewModel
rxui.var
rxui.list_var
rxui.dict_var
rxui.cached_var

4.5.1 class ViewModel

用途：把类字段自动变成响应式变量/代理变量，便于组织复杂页面状态。

示例（官方注释里的例子）：

from ex4nicegui import rxui
from nicegui import ui

class MyVm(rxui.ViewModel):
    count = 0
    data = []
    nums = rxui.list_var(lambda: [1, 2, 3])

    def __init__(self):
        super().__init__()
        self.data = [1, 2, 3]

    def increment(self):
        self.count += 1

vm = MyVm()
rxui.label(vm.count)
rxui.number(value=vm.count)
ui.button("Increment", on_click=vm.increment)

4.5.2 rxui.var(value_or_factory)

用途：在 ViewModel 内声明一个显式的 Ref 变量（深层响应）。

class VM(rxui.ViewModel):
    count = rxui.var(0)
    data = rxui.var(lambda: [1, 2, 3])

4.5.3 rxui.list_var(factory) / rxui.dict_var(factory)

用途：声明“隐式代理”的 list/dict，允许你像普通 list/dict 一样操作，但依然可响应。

class VM(rxui.ViewModel):
    items = rxui.list_var(lambda: [1, 2, 3])
    meta = rxui.dict_var(lambda: {"a": 1})

4.5.4 @rxui.cached_var

用途：把实例方法标记为“computed/cached”，在 __init__ 会自动变成 computed-ref。

class VM(rxui.ViewModel):
    name = "John"

    @rxui.cached_var
    def upper_name(self):
        return self.name.value.upper()

4.6 hooks/组件：鼠标、拖拽、分页、拖拽区、文件监听、Mermaid、ECharts

rxui 导出：

use_mouse(options=None)
use_draggable(init_x=0.0, init_y=0.0, auto_bind_style=True)
use_pagination(source, page_size=10, page=1)（返回 PaginationRef）
use_drag_zone(zone_box)
FilesWatcher(paths, recursive=False)
mermaid(content, clickable_nodes=None, zoom_mode=False)
echarts(...)（响应式版本见下一节）

4.6.1 use_mouse(options=None)

来源：reactive/useMouse/UseMouse.py

返回：单例 UseMouse 组件，包含只读 ref：

.x、.y、.sourceType

用法：

from ex4nicegui import rxui

mouse = rxui.use_mouse()
rxui.label(lambda: f"x={mouse.x.value}, y={mouse.y.value}")

4.6.2 use_draggable(init_x=0.0, init_y=0.0, auto_bind_style=True)

来源：reactive/UseDraggable/UseDraggable.py

返回：UseDraggable 组件，常用方法：

.apply(target_element)：让某个 element 可拖拽
.bind_style(target_element)：把拖拽产生的 style 自动写到 element（auto_bind_style=True 会自动做）
状态：.x/.y/.style/.is_dragging/.isFirst/.isFinal

用法：

from ex4nicegui import rxui
from nicegui import ui

box = ui.card().classes("w-40 h-40")
ud = rxui.use_draggable(100, 100)
ud.apply(box)

4.6.3 use_pagination(source, page_size=10, page=1)

来源：reactive/usePagination.py

返回 PaginationRef，常用属性：

.current_source：当前页数据（computed）
.current_page：当前页（Ref）
.page_count：总页数（computed）
.create_q_pagination()：创建一个 rxui.q_pagination 并与 page 绑定

用法：

from ex4nicegui import rxui, to_ref

items = to_ref(list(range(100)))
pg = rxui.use_pagination(items, page_size=10)

rxui.label(lambda: f"page={pg.current_page.value}/{pg.page_count.value}")
pg.create_q_pagination()

4.6.4 use_drag_zone(zone_box)

来源：reactive/dropZone/dropZone.py

返回 DropZoneResult：

.drag_keys：Ref[List[str]] 当前区内 keys
.apply(draggable_item, key_str)：把某个 draggable element 注册到 zone
.remove_item(key_str)：移除

这个功能依赖前端组件 dropZone.js，需要配套 draggable 侧的实现（本库提供的是 drop zone 部分）。

4.6.5 FilesWatcher(paths, recursive=False)

来源：reactive/fileWatcher.py

作用：封装 watchfiles 的文件变更监听（在 nicegui app 生命周期内运行）。

用法：

from ex4nicegui import rxui

fw = rxui.FilesWatcher(r"E:\test")

@fw.on_FileChange
def _(changes):
    print(changes)

4.6.6 mermaid(content, clickable_nodes=None, zoom_mode=False)

来源：reactive/mermaid/mermaid.py

content：Mermaid 语法字符串
clickable_nodes：可点击节点 id 列表
zoom_mode：是否启用缩放模式
on_node_click(handler)：注册点击事件

用法：

from ex4nicegui import rxui

m = rxui.mermaid("graph TD;A-->B;B-->C;", zoom_mode=True)

@m.on_node_click
def _(e):
    print(e.nodeId)

4.7 rxui.echarts（响应式封装）与底层 echarts 组件

底层组件：ex4nicegui/reactive/EChartsComponent/ECharts.py -> class echarts
响应式包装：ex4nicegui/reactive/officials/echarts.py -> EChartsBindableUi

你通常使用 rxui.echarts(...)（包装版）来做绑定。

此外顶层还导出 reset_echarts_dependencies(...)（见 3.17）。

5. BI 模块（`from ex4nicegui import bi`）

导出（ex4nicegui/bi/__init__.py）：

bi.data_source
bi.ui_left_drawer
bi.ui_title / ui_header / ui_subheader
bi.ui_cols

5.1 `bi.data_source(data)`：创建数据源门面 DataSourceFacade

来源：ex4nicegui/bi/index.py

签名：

bi.data_source(data: DataFrame | callable | Any) -> DataSourceFacade

支持：

pandas.DataFrame
callable（动态数据源，内部会在 effect 中取数）
其他类型若未实现协议会抛 TypeError

5.2 DataSourceFacade 常用属性/方法

来源：ex4nicegui/bi/dataSourceFacade.py -> class DataSourceFacade

5.2.1 .data / .filtered_data

.data：未过滤数据
.filtered_data：当前过滤后的数据

5.2.2 .reload(data, reset_filters=True)

替换数据源内容，并可选择清空过滤器。

5.2.3 .remove_filters(*components)

当前实现里：不传参会移除所有过滤；传 components 的分支暂未实现（源码是 pass）。

5.2.4 UI 组件生成（会自动把过滤联动“接到”数据源上）

.ui_select(column, *, sort_options=None, exclude_null_value=False, clearable=True, multiple=True, **kwargs)
.ui_radio(column, *, sort_options=None, exclude_null_value=False, hide_filtered=True, custom_options_map=None, **kwargs)
.ui_slider(column, **kwargs)
.ui_range(column, **kwargs)
.ui_table(*, columns=None, pagination=20, **kwargs)
.ui_aggrid(*, options=None, **kwargs)
.ui_echarts(fn)：把数据传入 fn 生成图表（dict 或 pyecharts.Base）

示例（DataFrame + select + table 联动）：

import pandas as pd
from ex4nicegui import bi

df = pd.DataFrame({"name": list("abcde"), "value": range(5)})
ds = bi.data_source(df)

ds.ui_select("name")     # 选择 name 会把 filter 发给数据源
ds.ui_table()            # table 会显示 filtered_data

5.2.5 .send_filter(element, filter)

你也可以自己把某个 element 的选择行为包装成 filter 回调并发送到数据源。

5.3 BI UI 的返回值：UiResult

来源：ex4nicegui/bi/elements/models.py

UiResult 是一个薄封装：

.element：底层 nicegui element
.id：element.id
.classes(...) / .props(...)：链式
.cancel_linkage(*source)：取消与某些源组件的联动（在 DataSource 内部通过 exclude_keys 实现）

6. toolbox（VueUse 工具箱）

导出（ex4nicegui/toolbox/__init__.py）：

tb.use_dark
tb.use_breakpoints
tb.use_qr_code

底层依赖：VueUse 组件（toolbox/core/vue_use.py），通过前端 VueUse.js 调用 VueUse 能力，并用事件回传状态。

6.1 `tb.use_dark(value=True, options=None, on_value_change=None)`

来源：toolbox/functions/dark.py -> class UseDark

用途：暗黑模式管理（默认用 Quasar 的 dark class 方案）。

常用：

.value：当前布尔值
.is_dark：computed-ref
.toggle(value=None)：切换/设置
.on_value_change(callback)：监听变化

示例（按钮切换暗黑）：

from ex4nicegui import rxui, toolbox as tb

dark = tb.use_dark()
rxui.button(icon=lambda: "sunny" if dark.value else "dark_mode", on_click=dark.toggle).props("flat round")

6.2 `tb.use_breakpoints(options=None, on_active_change=None)`

来源：toolbox/functions/breakpoint.py -> class UseBreakpoints

用途：视口断点监听（默认 Quasar xs/sm/md/lg/xl）。

常用：

.active_value：当前断点字符串（非 ref）
.active：当前断点 computed-ref
.between(start, end)：返回 ReadonlyRef[bool]
.is_between(start, end)：返回 bool
.on_active_change(callback)：监听

示例：

from ex4nicegui import toolbox as tb, rxui

bp = tb.use_breakpoints()
rxui.label(lambda: f"breakpoint={bp.active.value}")
rxui.label(lambda: f"is mobile? {bp.between('xs','md').value}")

6.3 `tb.use_qr_code(text, on_data_change=None)`

来源：toolbox/functions/qr_code.py -> class UseQRCode

用途：生成二维码（前端生成，回传 base64/data url 之类的数据）。

常用：

.code：computed-ref，二维码数据
.update_text(text)：更新内容
await .get_qr_code()：异步获取
.on_data_change(callback)：监听二维码变化

示例：

from ex4nicegui import to_ref, rxui, toolbox as tb

text = to_ref("ex4nicegui")
qr = tb.use_qr_code(text)

rxui.input(value=text)
rxui.image(qr.code).classes("w-20 h-20").props("no-transition")

7. layout（布局扩展）

模块：ex4nicegui/layout/__init__.py 导出：

gridFlex：grid_flex, grid_box, mark_area, item_position, GridFlex
rxFlex：rx_column, rx_row

7.1 rxFlex：`ly.rx_row` / `ly.rx_column`

来源：layout/rxFlex/index.py

用途：更“语义化”的 flex row/column，对齐方式用 left/center/right/top/bottom 等词。

7.1.1 rx_column(horizontal="left", vertical="top")

常用方法：

.horizontal(value)：设置 align-items
.vertical(value)：设置 justify-content
.gap(value)：设置 CSS gap（数值会自动转 rem）
.all_items_grow()：让所有子项 grow
.item_horizontal(value)：返回一个可用 + 应用到子元素的包装器（见下例）
.space()：返回 q-space

示例：

from ex4nicegui import layout as ly
from nicegui import ui

with ly.rx_column(horizontal="center", vertical="top").gap(1):
    ui.label("A")
    ly.rx_column().item_horizontal("center") + ui.button("B")  # 给单个子项设置 align-self

7.1.2 rx_row(horizontal="left", vertical="top")

类似 column，只是横纵含义映射到 row 版本。

7.2 gridFlex：`ly.grid_box` / `ly.grid_flex` / `ly.GridFlex`

来源：layout/gridFlex/gridFlex.py

7.2.1 grid_flex(type, template, *, horizontal="stretch", vertical="stretch", gap=1, width_full=True, break_point=None)

快速创建 GridFlex 并设置 grid-template-columns/rows。

示例：

from ex4nicegui import layout as ly
from nicegui import ui

gf = ly.grid_flex("row", "repeat(3, 1fr)", gap=1)
with gf:
    ui.card().classes("h-20")
    ui.card().classes("h-20")
    ui.card().classes("h-20")

7.2.2 grid_box(area=None, *, template_rows=None, template_columns=None, horizontal="stretch", vertical="stretch", gap=1, width_full=True, break_point=None, **kws)

支持 grid-template-areas，并自动推导 rows/cols。

示例：

from ex4nicegui import layout as ly
from nicegui import ui

gf = ly.grid_box("""
a a b
c d b
""", gap=1)

with gf:
    ly.mark_area("a") + ui.card().classes("h-20")
    ly.mark_area("b") + ui.card().classes("h-20")
    ly.mark_area("c") + ui.card().classes("h-20")
    ly.mark_area("d") + ui.card().classes("h-20")

7.2.3 mark_area(mark) / item_position(horizontal=None, vertical=None)

mark_area("a") + element：给 element 加 grid-area:a
item_position(horizontal="center", vertical="bottom") + element：给 element 加对应对齐 class

8. 其它（非顶层导出但项目内常用）

8.1 `RefWrapper` / `to_ref_wrapper`

来源：ex4nicegui/utils/refWrapper.py

用途：把“getter + setter”封装成一个具有 .value 的对象，以便当作 setter-ref 参与双向绑定。典型用途：vmodel/vfor 内部都是用 RefWrapper 做“可写引用”。

8.2 调试 UI：`ex4nicegui.tools.debug.display_ref_vars_ui(vars_dict)`

来源：ex4nicegui/tools/debug.py

用途：把当前作用域里的一堆 ref/computed/effect 以表格形式展示（便于调试响应式依赖）。

9. 常见模式速查

9.1 “值/Ref/Getter”统一写法

需要“读值”：用 to_value(x)
需要“写回”：确保传入的是 setter-ref（Ref 或 vmodel(...) 返回值）

9.2 输入组件的正确绑定姿势

只读展示：rxui.input(value=lambda: ...)
双向绑定：rxui.input(value=some_ref) 或 rxui.input(value=rxui.vmodel(...))

9.3 多个值一起改，减少抖动/重复刷新

事件回调用 @event_batch
任意代码段用 @batch 或 batch(lambda: ...)

10. API 总览（按模块列出导出名）

10.1 ex4nicegui 顶层导出

rxui
async_computed
ref_computed
effect / effect_refreshable
to_ref / ref / deep_ref / reactive
to_value / to_raw
is_ref / is_reactive / is_setter_ref
on / batch / event_batch
new_scope / next_tick
reset_echarts_dependencies
PageState
version

10.2 rxui 导出（响应式 UI）

基础：element, row, column, grid, card/card_section/card_actions, drawer, expansion, dialog, tooltip, tabs/tab/tab_panels/tab_panel/lazy_tab_panels
展示：label, icon, image, html, badge, chip, avatar
输入：input/lazy_input, textarea/lazy_textarea, number, checkbox, switch, radio, select, slider/lazy_slider, range/lazy_range, toggle, date, color_picker/lazy_color_picker, upload
反馈：spinner, linear_progress, circular_progress, knob
数据：table, aggrid, q_pagination/pagination
响应式能力：vfor, VforStore, vmodel, ViewModel, var, cached_var, list_var, dict_var
hooks/组件：use_mouse, use_draggable, use_pagination, use_drag_zone, FilesWatcher, mermaid, echarts

10.3 bi 导出

data_source
ui_left_drawer / ui_cols
ui_title / ui_header / ui_subheader

10.4 toolbox 导出

use_dark
use_breakpoints
use_qr_code

10.5 layout 导出

grid_flex / grid_box / mark_area / item_position / GridFlex
rx_column / rx_row

上一页更多学习资料

最后更新于2小时前

hashtag1. 安装与导入

hashtag1.1 安装

hashtag1.2 基本导入方式

hashtag2. 核心概念：MaybeRef / Ref / Getter

hashtag3. 顶层 API（import ex4nicegui as ex4 / from ex4nicegui import ...）

hashtag3.1 rxui（响应式 UI 命名空间）

hashtag3.2 to_ref(maybe_ref, is_deep=False)

hashtag3.3 ref(value, is_deep=False)

hashtag3.4 deep_ref(value)

hashtag3.5 reactive(obj)

hashtag3.6 to_value(obj)

hashtag3.7 to_raw(obj) / is_reactive(obj)

hashtag3.8 is_ref(obj) / is_setter_ref(obj)

hashtag3.9 on(refs, onchanges=False, priority_level=1, effect_kws=None, deep=True, scope=None)

hashtag3.10 batch(fn) / event_batch(fn)

hashtag3.11 ref_computed(fn, desc="", debug_trigger=None, priority_level=1, debug_name=None)

hashtag3.12 async_computed(refs, init=None, evaluating=None, onchanges=True, debug_trigger=None, debug_name=None)

hashtag3.13 effect(fn, priority_level=1, debug_trigger=None, debug_name=None)

hashtag3.14 effect_refreshable(fn, refs=[])

hashtag3.15 new_scope(detached=False)

hashtag3.16 next_tick(job)

hashtag3.17 reset_echarts_dependencies(echarts_js_file)

hashtag3.18 PageState

hashtag4. rxui（响应式 UI）完整 API

hashtag4.1 BindableUi 通用方法（所有 rxui 组件返回的包装对象都具备）

hashtag4.2 rxui 基础组件工厂（与 nicegui.ui.* 对应）

hashtag4.3 vmodel(ref_obj, *attrs)：对 dict/list/对象字段做双向绑定

hashtag4.4 vfor(data, key=...)：响应式列表渲染

hashtag4.5 ViewModel：类式状态管理（更“像 Vue/前端 MVVM”）

hashtag4.6 hooks/组件：鼠标、拖拽、分页、拖拽区、文件监听、Mermaid、ECharts

hashtag4.7 rxui.echarts（响应式封装）与底层 echarts 组件

hashtag5. BI 模块（from ex4nicegui import bi）

hashtag5.1 bi.data_source(data)：创建数据源门面 DataSourceFacade

hashtag5.2 DataSourceFacade 常用属性/方法

hashtag5.3 BI UI 的返回值：UiResult

hashtag6. toolbox（VueUse 工具箱）

hashtag6.1 tb.use_dark(value=True, options=None, on_value_change=None)

hashtag6.2 tb.use_breakpoints(options=None, on_active_change=None)

hashtag6.3 tb.use_qr_code(text, on_data_change=None)

hashtag7. layout（布局扩展）

hashtag7.1 rxFlex：ly.rx_row / ly.rx_column

hashtag7.2 gridFlex：ly.grid_box / ly.grid_flex / ly.GridFlex

hashtag8. 其它（非顶层导出但项目内常用）

hashtag8.1 RefWrapper / to_ref_wrapper

hashtag8.2 调试 UI：ex4nicegui.tools.debug.display_ref_vars_ui(vars_dict)

hashtag9. 常见模式速查

hashtag9.1 “值/Ref/Getter”统一写法

hashtag9.2 输入组件的正确绑定姿势

hashtag9.3 多个值一起改，减少抖动/重复刷新

hashtag10. API 总览（按模块列出导出名）

hashtag10.1 ex4nicegui 顶层导出

hashtag10.2 rxui 导出（响应式 UI）

hashtag10.3 bi 导出

hashtag10.4 toolbox 导出

hashtag10.5 layout 导出

1. 安装与导入

1.1 安装

1.2 基本导入方式

2. 核心概念：MaybeRef / Ref / Getter

3. 顶层 API（`import ex4nicegui as ex4` / `from ex4nicegui import ...`）

3.1 rxui（响应式 UI 命名空间）

3.2 `to_ref(maybe_ref, is_deep=False)`

3.3 `ref(value, is_deep=False)`

3.4 `deep_ref(value)`

3.5 `reactive(obj)`

3.6 `to_value(obj)`

3.7 `to_raw(obj)` / `is_reactive(obj)`

3.8 `is_ref(obj)` / `is_setter_ref(obj)`

3.9 `on(refs, onchanges=False, priority_level=1, effect_kws=None, deep=True, scope=None)`

3.10 `batch(fn)` / `event_batch(fn)`

3.11 `ref_computed(fn, desc="", debug_trigger=None, priority_level=1, debug_name=None)`

3.12 `async_computed(refs, init=None, evaluating=None, onchanges=True, debug_trigger=None, debug_name=None)`

3.13 `effect(fn, priority_level=1, debug_trigger=None, debug_name=None)`

3.14 `effect_refreshable(fn, refs=[])`

3.15 `new_scope(detached=False)`

3.16 `next_tick(job)`

3.17 `reset_echarts_dependencies(echarts_js_file)`

3.18 `PageState`

4. rxui（响应式 UI）完整 API

4.1 BindableUi 通用方法（所有 rxui 组件返回的包装对象都具备）

4.2 rxui 基础组件工厂（与 `nicegui.ui.*` 对应）

4.3 `vmodel(ref_obj, *attrs)`：对 dict/list/对象字段做双向绑定

4.4 `vfor(data, key=...)`：响应式列表渲染

4.5 ViewModel：类式状态管理（更“像 Vue/前端 MVVM”）

4.6 hooks/组件：鼠标、拖拽、分页、拖拽区、文件监听、Mermaid、ECharts

4.7 rxui.echarts（响应式封装）与底层 echarts 组件

5. BI 模块（`from ex4nicegui import bi`）

5.1 `bi.data_source(data)`：创建数据源门面 DataSourceFacade

5.2 DataSourceFacade 常用属性/方法

5.3 BI UI 的返回值：UiResult

6. toolbox（VueUse 工具箱）

6.1 `tb.use_dark(value=True, options=None, on_value_change=None)`

6.2 `tb.use_breakpoints(options=None, on_active_change=None)`

6.3 `tb.use_qr_code(text, on_data_change=None)`

7. layout（布局扩展）

7.1 rxFlex：`ly.rx_row` / `ly.rx_column`

7.2 gridFlex：`ly.grid_box` / `ly.grid_flex` / `ly.GridFlex`

8. 其它（非顶层导出但项目内常用）

8.1 `RefWrapper` / `to_ref_wrapper`

8.2 调试 UI：`ex4nicegui.tools.debug.display_ref_vars_ui(vars_dict)`

9. 常见模式速查

9.1 “值/Ref/Getter”统一写法

9.2 输入组件的正确绑定姿势

9.3 多个值一起改，减少抖动/重复刷新

10. API 总览（按模块列出导出名）

10.1 ex4nicegui 顶层导出

10.2 rxui 导出（响应式 UI）

10.3 bi 导出

10.4 toolbox 导出

10.5 layout 导出