ex4nicegui

ex4nicegui

簡體中文| English

對nicegui 做的擴展庫。內置響應式組件，完全實現數據響應式界面編程。

查看更多示例

---

教程

頭條文章-秒殺官方實現，python界面庫，去掉90%事件代碼的nicegui

微信公眾號-秒殺官方實現，python界面庫，去掉90%事件代碼的nicegui

? 安裝

 pip install ex4nicegui -U

---

入門

我們從一個簡單的計數器應用開始，用戶可以通過點擊按鈕讓計數增加或減少。

下面是完整代碼：

 from nicegui import ui
from ex4nicegui import rxui

# 数据状态代码
class Counter ( rxui . ViewModel ):
    count : int = 0

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

    def decrement ( self ):
        self . count -= 1

# 界面代码
counter = Counter ()

with ui . row ( align_items = "center" ):
    ui . button ( icon = "remove" , on_click = counter . decrement )
    rxui . label ( counter . count )
    ui . button ( icon = "add" , on_click = counter . increment )


ui . run ()

---

現在看更多細節。 ex4nicegui遵從數據驅動方式定義界面。狀態數據定義應用程序中所有可以變化的數據。

下面是Counter狀態數據定義：

 class Counter ( rxui . ViewModel ):
    count : int = 0

• 自定義類需要繼承rxui.ViewModel
• 這裡定義了一個變量count ，表示計數器的當前值，初始值為0

接著，在類中定義一系列操作數據的方法：

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

def decrement ( self ):
    self . count -= 1

• 這些都是實例方法，可以修改count變量的值

然後，在界面代碼中，實例化Counter的對象。

 counter = Counter ()

我們通過rxui.label組件綁定count變量。把操作數據的方法綁定到按鈕點擊事件上。

 ui . button ( icon = "remove" , on_click = counter . decrement )
rxui . label ( counter . count )
ui . button ( icon = "add" , on_click = counter . increment )

• 我們需要使用rxui命名空間下的label組件，而不是nicegui命名空間下的label組件。
• rxui.label組件綁定counter.count變量，當counter.count變化時， rxui.label組件自動更新。
• ui.button組件綁定counter.decrement和counter.increment方法，點擊按鈕時調用相應方法。

在復雜項目中， Counter定義的代碼可以放到單獨的模塊中，然後在界面代碼中導入。

注意，當類變量名前面帶有下劃線時，數據狀態不會自動更新。

 class Counter ( rxui . ViewModel ):
    count : int = 0 # 响应式数据，能自动同步界面
    _count : int = 0 # 这里的下划线表示私有变量，不会自动同步界面

---

二次計算

接著前面的例子，我們再添加一個功能。當計數器的值小於0 時，字體顯示為紅色，大於0 時顯示為綠色，否則顯示為黑色。

 # 数据状态代码
class Counter ( rxui . ViewModel ):
    count : int = 0

    def text_color ( self ):
        if self . count > 0 :
            return "green"
        elif self . count < 0 :
            return "red"
        else :
            return "black"

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

    def decrement ( self ):
        self . count -= 1

# 界面代码
counter = Counter ()

with ui . row ( align_items = "center" ):
    ui . button ( icon = "remove" , on_click = counter . decrement )
    rxui . label ( counter . count ). bind_color ( counter . text_color )
    ui . button ( icon = "add" , on_click = counter . increment )

顏色值是依據計數器當前值計算得到的。屬於二次計算。通過定義普通的實例函數即可。

 def text_color ( self ):
    if self . count > 0 :
        return "green"
    elif self . count < 0 :
        return "red"
    else :
        return "black"

然後，通過rxui.label組件的bind_color方法綁定text_color方法，使得顏色值自動更新。

 rxui . label ( counter . count ). bind_color ( counter . text_color )

二次計算緩存

現在，我們在計數器下方使用文字，顯示當前計數器的顏色文本值。

...
# 数据状态代码
class Counter ( rxui . ViewModel ):
    ...

# 界面代码
counter = Counter ()

with ui . row ( align_items = "center" ):
    ui . button ( icon = "remove" , on_click = counter . decrement )
    rxui . label ( counter . count ). bind_color ( counter . text_color )
    ui . button ( icon = "add" , on_click = counter . increment )

rxui . label ( lambda : f"当前计数器值为 { counter . count } , 颜色值为 { counter . text_color () } " )

• 當二次計算非常簡單時，可以直接使用lambda 表達式

上面的代碼中，有兩個地方使用了counter.text_color方法。當counter.count變化時， counter.text_color會執行兩次計算。第二次計算是多餘的。

為了避免多餘的計算，我們可以把counter.text_color緩存起來。

 # 数据状态代码
class Counter ( rxui . ViewModel ):
    count : int = 0

    @ rxui . cached_var
    def text_color ( self ):
        if self . count > 0 :
            return "green"
        elif self . count < 0 :
            return "red"
        else :
            return "black"

• rxui.cached_var裝飾器可以把函數結果緩存起來，避免多餘的計算。

列表

下面的示例，展示瞭如何使用列表。

 class AppState ( rxui . ViewModel ):
    nums = []
    # nums = [1,2,3]  如果需要初始化，必须在 __init__ 中设置

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

    def append ( self ):
        new_num = max ( self . nums ) + 1
        self . nums . append ( new_num )

    def pop ( self ):
        self . nums . pop ()

    def reverse ( self ):
        self . nums . reverse ()

    def display_nums ( self ):
        return ", " . join ( map ( str , self . nums ))


# 界面代码
state = AppState ()

with ui . row ( align_items = "center" ):
    ui . button ( "append" , on_click = state . append )
    ui . button ( "pop" , on_click = state . pop )
    ui . button ( "reverse" , on_click = state . reverse )

rxui . label ( state . display_nums )

如果你需要在定義列表時，初始化列表，建議在__init__中設置。

 class AppState ( rxui . ViewModel ):
    nums = []
    # nums = [1,2,3]  如果需要初始化，必须在 __init__ 中设置

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

    ...

另一種方式是使用rxui.list_var

 class AppState ( rxui . ViewModel ):
    # nums = []
    # nums = [1,2,3]  如果需要初始化，必须在 __init__ 中设置
    nums = rxui . list_var ( lambda : [ 1 , 2 , 3 ])

    ...

• rxui.list_var參數是一個返回列表的函數

列表循環

定義列表後，我們可以用effect_refreshable.on裝飾器，在界面中展示列表數據。

下面的例子中，界面會動態展示下拉框選中的圖標

 from ex4nicegui import rxui , effect_refreshable


class AppState ( rxui . ViewModel ):
    icons = []
    _option_icons = [ "font_download" , "warning" , "format_size" , "print" ]


state = AppState ()

# 界面代码
with ui . row ( align_items = "center" ):

    @ effect_refreshable . on ( state . icons )
    def _ ():
        for icon in state . icons :
            ui . icon ( icon , size = "2rem" )


rxui . select ( state . _option_icons , value = state . icons , multiple = True )

其中， @effect_refreshable.on(state.icons)明確指定了依賴關係。當state.icons變化時， _函數會重新執行。

 @ effect_refreshable . on ( state . icons )
def _ ():
    # 这里的代码会在 state.icons 变化时重新执行
    ...

注意，每次執行，裡面的內容都會被清除。這是數據驅動版本的ui.refreshable

原則上，可以不通過.on指定監控的數據，只要函數中使用到的"響應式數據"，都會自動監控

 @ effect_refreshable # 没有使用 .on(state.icons)
def _ ():
    # 这里读取了 state.icons，因此会自动监控
    for icon in state . icons :
        ui . icon ( icon , size = "2rem" )

建議總是通過.on指定依賴關係，避免預料之外的刷新

---

數據持久化

ViewModel使用代理對象創建響應式數據，當需要保存數據時，可以使用rxui.ViewModel.to_value轉換成普通數據.

下面的例子，點擊按鈕將顯示my_app 的狀態數據字典。

 from nicegui import ui
from ex4nicegui import rxui


class MyApp ( rxui . ViewModel ):
    a = 0
    sign = "+"
    b = 0

    def show_data ( self ):
        # >> {"a": 0, "sign": '+, "b": 0}
        return rxui . ViewModel . to_value ( self )

    def show_a ( self ):
        # >> 0
        return rxui . ViewModel . to_value ( self . a )

my_app = MyApp ()

rxui . number ( value = my_app . a , min = 0 , max = 10 )
rxui . radio ([ "+" , "-" , "*" , "/" ], value = my_app . sign )
rxui . number ( value = my_app . b , min = 0 , max = 10 )

ui . button ( "show data" , on_click = lambda : ui . notify ( my_app . show_data ()))

結合rxui.ViewModel.on_refs_changed ，可以在數據變化時，自動保存數據到本地。

 from nicegui import ui
from ex4nicegui import rxui
from pathlib import Path
import json


class MyApp ( rxui . ViewModel ):
    a = 0
    sign = "+"
    b = 0

    _json_path = Path ( __file__ ). parent / "data.json"

    def __init__ ( self ):
        super (). __init__ ()

        @ rxui . ViewModel . on_refs_changed ( self )
        def _ ():
            # a, sign, b 任意一个值变化时，自动保存到本地
            self . _json_path . write_text ( json . dumps ( self . show_data ()))

    def show_data ( self ):
        return rxui . ViewModel . to_value ( self )
...

---

• ex4nicegui
  • 教程
  • ? 安裝
  • 入門
    • 二次計算
    • 二次計算緩存
    • 列表
    • 列表循環
    • 數據持久化
  • apis
    • ViewModel
      • 使用列表
    • 響應式
      • to_ref
      • deep_ref
      • effect
      • ref_computed
      • async_computed
      • on
      • new_scope
    • 組件功能
      • vmodel
      • vfor
      • bind_classes
      • bind_style
      • bind_prop
      • rxui.echarts
        • echarts 圖表鼠標事件
        • rxui.echarts.from_javascript
        • rxui.echarts.register_map
      • tab_panels
      • lazy_tab_panels
      • scoped_style
    • BI 模塊
      • bi.data_source
      • ui_select
      • ui_table
      • ui_aggrid
    • toolbox
      • use_dark
      • use_breakpoints
      • use_qr_code

---

apis

ViewModel

在v0.7.0版本中，引入ViewModel類，用於管理一組響應式數據。

下面是一個簡單的計算器示例：

1. 當用戶修改數值輸入框或符號選擇框，右側會自動顯示計算結果
2. 當結果小於0 時，結果顯示為紅色，否則為黑色

 from ex4nicegui import rxui

class Calculator ( rxui . ViewModel ):
    num1 = 0
    sign = "+"
    num2 = 0

    @ rxui . cached_var
    def result ( self ):
        # 当 num1,sign,num2 任意一个值发生变化时，result 也会重新计算
        return eval ( f" { self . num1 } { self . sign } { self . num2 } " )

# 每个对象拥有独立的数据
calc = Calculator ()

with ui . row ( align_items = "center" ):
    rxui . number ( value = calc . num1 , label = "Number 1" )
    rxui . select ( value = calc . sign , options = [ "+" , "-" , "*" , "/" ], label = "Sign" )
    rxui . number ( value = calc . num2 , label = "Number 2" )
    ui . label ( "=" )
    rxui . label ( calc . result ). bind_color (
        lambda : "red" if calc . result () < 0 else "black"
    )

使用列表

下面的示例，每個person 使用卡片展示。最上方顯示所有人的平均年齡。當個人年齡大於平均年齡，卡片外邊框將變為紅色。 通過number組件修改年齡，一切都會自動更新。

 from typing import List
from ex4nicegui import rxui
from itertools import count
from nicegui import ui

id_generator = count ()

class Person ( rxui . ViewModel ):
    name = ""
    age = 0

    def __init__ ( self , name : str , age : int ):
        super (). __init__ ()
        self . name = name
        self . age = age
        self . id = next ( id_generator )


class Home ( rxui . ViewModel ):
    persons : List [ Person ] = []
    deleted_person_index = 0

    @ rxui . cached_var
    def avg_age ( self ) -> float :
        if len ( self . persons ) == 0 :
            return 0

        return round ( sum ( p . age for p in self . persons ) / len ( self . persons ), 2 )

    def avg_name_length ( self ):
        if len ( self . persons ) == 0 :
            return 0

        return round ( sum ( len ( p . name ) for p in self . persons ) / len ( self . persons ), 2 )

    def delete_person ( self ):
        if self . deleted_person_index < len ( self . persons ):
            del self . persons [ int ( self . deleted_person_index )]

    def sample_data ( self ):
        self . persons = [
            Person ( "alice" , 25 ),
            Person ( "bob" , 30 ),
            Person ( "charlie" , 31 ),
            Person ( "dave" , 22 ),
            Person ( "eve" , 26 ),
            Person ( "frank" , 29 ),
        ]


home = Home ()
home . sample_data ()

rxui . label ( lambda : f"平均年龄: { home . avg_age () } " )
rxui . label ( lambda : f"平均名字长度: { home . avg_name_length () } " )

rxui . number (
    value = home . deleted_person_index , min = 0 , max = lambda : len ( home . persons ) - 1 , step = 1
)
ui . button ( "删除" , on_click = home . delete_person )

with ui . row ():

    @ rxui . vfor ( home . persons , key = "id" )
    def _ ( store : rxui . VforStore [ Person ]):
        person = store . get_item ()
        with rxui . card (). classes ( "outline" ). bind_classes (
            {
                "outline-red-500" : lambda : person . age > home . avg_age (),
            }
        ):
            rxui . input ( value = person . name , placeholder = "名字" )
            rxui . number ( value = person . age , min = 1 , max = 100 , step = 1 , placeholder = "年龄" )

ui . run ()

如果你覺得rxui.vfor代碼過於復雜，可以使用effect_refreshable裝飾器代替。

 from ex4nicegui import rxui , Ref , effect_refreshable
...

# 明确指定监控 home.persons 变化，可以避免意外刷新
@ effect_refreshable . on ( home . persons )
def _ ():
    
    for person in home . persons . value :
        ...
        rxui . number ( value = person . age , min = 1 , max = 100 , step = 1 , placeholder = "年龄" )
...

需要注意到，每當home.persons列表變化時(比如新增或刪除元素)， effect_refreshable裝飾的函數都會重新執行。意味著所有元素都會重新創建。

更多複雜的應用，可以查看examples

---

響應式

 from ex4nicegui import (
    to_ref ,
    ref_computed ,
    on ,
    effect ,
    effect_refreshable ,
    batch ,
    event_batch ,
    deep_ref ,
    async_computed
)

常用to_ref , deep_ref , effect , ref_computed , on , async_computed

---

to_ref

定義響應式對象,通過.value讀寫

 a = to_ref ( 1 )
b = to_ref ( "text" )

a . value = 2
b . value = 'new text'

print ( a . value )

當值為複雜對象時，默認不會保持嵌套對象的響應性。

 a = to_ref ([ 1 , 2 ])

@ effect
def _ ():
    print ( 'len:' , len ( a . value ))

# 不会触发 effect
a . value . append ( 10 )

# 整个替换则会触发
a . value = [ 1 , 2 , 10 ]

參數is_deep設置為True時，能得到深度響應能力

 a = to_ref ([ 1 , 2 ], is_deep = True )

@ effect
def _ ():
    print ( 'len:' , len ( a . value ))

# print 3
a . value . append ( 10 )

deep_ref等價於is_deep設置為True時的to_ref

---

deep_ref

等價於is_deep設置為True時的to_ref 。

當數據源為列表、字典或自定義類時，特別有用。通過.value獲取的對象為代理對象

 data = [ 1 , 2 , 3 ]
data_ref = deep_ref ( data )

assert data_ref . value is not data

通過to_raw可以獲取原始對象

 from ex4nicegui import to_raw , deep_ref

data = [ 1 , 2 , 3 ]
data_ref = deep_ref ( data )

assert data_ref . value is not data
assert to_raw ( data_ref . value ) is data 

---

effect

接受一個函數,自動監控函數中使用到的響應式對像變化,從而自動執行函數

 a = to_ref ( 1 )
b = to_ref ( "text" )


@ effect
def auto_run_when_ref_value ():
    print ( f"a: { a . value } " )


def change_value ():
    a . value = 2
    b . value = "new text"


ui . button ( "change" , on_click = change_value )

首次執行effect ,函數auto_run_when_ref_value將被執行一次.之後點擊按鈕,改變a的值(通過a.value ),函數auto_run_when_ref_value再次執行

切忌把大量數據處理邏輯分散在多個on或effect中， on或effect中應該大部分為界面操作邏輯，而非響應式數據處理邏輯

---

ref_computed

與effect具備一樣的功能， ref_computed還能從函數中返回結果。一般用於從to_ref中進行二次計算

 a = to_ref ( 1 )
a_square = ref_computed ( lambda : a . value * 2 )


@ effect
def effect1 ():
    print ( f"a_square: { a_square . value } " )


def change_value ():
    a . value = 2


ui . button ( "change" , on_click = change_value )

點擊按鈕後， a.value值被修改，從而觸發a_square重新計算.由於effect1中讀取了a_square的值，從而觸發effect1執行

ref_computed是只讀的to_ref

從v0.7.0版本開始，不建議使用ref_computed應用實例方法。你可以使用rxui.ViewModel ，並使用rxui.cached_var裝飾器

 class MyState ( rxui . ViewModel ):
    def __init__ ( self ) -> None :
        self . r_text = to_ref ( "" )

    @ rxui . cached_var
    def post_text ( self ):
        return self . r_text . value + "post"

state = MyState ()

rxui . input ( value = state . r_text )
rxui . label ( state . post_text )

---

async_computed

二次計算中需要使用異步函數時，使用async_computed

 # 模拟长时间执行的异步函数
async def long_time_query ( input : str ):
    await asyncio . sleep ( 2 )
    num = random . randint ( 20 , 100 )
    return f"query result[ { input = } ]: { num = } "


search = to_ref ( "" )
evaluating = to_ref ( False )

@ async_computed ( search , evaluating = evaluating , init = "" )
async def search_result ():
    return await long_time_query ( search . value )

rxui . lazy_input ( value = search )

rxui . label (
    lambda : "查询中" if evaluating . value else "上方输入框输入内容并回车搜索"
)
rxui . label ( search_result )

• async_computed第一個參數必須明確指定需要監控的響應式數據. 使用列表可以同時指定多個響應式數據
• 參數evaluating為bool 類型的響應式數據，當異步函數執行中，此變量值為True ，計算結束後為False
• 參數init指定初始結果

---

on

類似effect的功能,但是on需要明確指定監控的響應式對象

 a1 = to_ref ( 1 )
a2 = to_ref ( 10 )
b = to_ref ( "text" )


@ on ( a1 )
def watch_a1_only ():
    print ( f"watch_a1_only ... a1: { a1 . value } ,a2: { a2 . value } " )


@ on ([ a1 , b ], onchanges = True )
def watch_a1_and_b ():
    print ( f"watch_a1_and_b ... a1: { a1 . value } ,a2: { a2 . value } ,b: { b . value } " )


def change_a1 ():
    a1 . value += 1
    ui . notify ( "change_a1" )


ui . button ( "change a1" , on_click = change_a1 )


def change_a2 ():
    a2 . value += 1
    ui . notify ( "change_a2" )


ui . button ( "change a2" , on_click = change_a2 )


def change_b ():
    b . value += "x"
    ui . notify ( "change_b" )


ui . button ( "change b" , on_click = change_b )

• 參數onchanges為True 時(默認值為False),指定的函數不會在綁定時執行

切忌把大量數據處理邏輯分散在多個on或effect中， on或effect中應該大部分為界面操作邏輯，而非響應式數據處理邏輯

---

new_scope

默認情況下，所有檢測函數在客戶端連接斷開時自動銷毀。如果需要更細粒度的控制，可以使用new_scope

 from nicegui import ui
from ex4nicegui import rxui , to_ref , effect , new_scope

a = to_ref ( 0.0 )

scope1 = new_scope ()

@ scope1 . run
def _ ():
    @ effect
    def _ ():
        print ( f"scope 1: { a . value } " )


rxui . number ( value = a )
rxui . button ( "dispose scope 1" , on_click = scope1 . dispose )

---

組件功能

vmodel

在表單輸入元素或組件上創建雙向綁定。

簡單值類型的ref默認支持雙向綁定

 from ex4nicegui import rxui , to_ref , deep_ref

data = to_ref ( "init" )

rxui . label ( lambda : f" { data . value = } " )
# 默认就是双向绑定
rxui . input ( value = data )

• 簡單值類型一般是str , int等不可變值類型

當使用複雜數據結構時，會使用deep_ref保持嵌套值的響應性

 data = deep_ref ({ "a" : 1 , "b" : [ 1 , 2 , 3 , 4 ]})

rxui . label ( lambda : f" { data . value = !s } " )

# 当前版本没有任何绑定效果.或许未来的版本可以解决
rxui . input ( value = data . value [ "a" ])

# 只读绑定.其他途径修改了 `data.value["a"]` ，此输入框会同步，但反过来不行
rxui . input ( value = lambda : data . value [ "a" ])

# 要使用 vmodel 才能双向绑定
rxui . input ( value = rxui . vmodel ( data , "a" ))

# 也可以直接使用，但不推荐
rxui . input ( value = rxui . vmodel ( data . value [ 'a' ]))

• 第一個輸入框將完全失去響應性，因為代碼等價於rxui.input(value=1)
• 第二個輸入框由於使用函數，將得到讀取響應性(第三個輸入框輸入值，將得到同步)
• 第三個輸入框，使用rxui.vmodel包裹，即可實現雙向綁定

如果使用rxui.ViewModel ，你可能不需要使用vmodel

可參考todo list 案例

---

vfor

基於列表響應式數據，渲染列表組件。每項組件按需更新。數據項支持字典或任意類型對象。

從v0.7.0版本開始，建議配合rxui.ViewModel使用。與使用effect_refreshable裝飾器不同， vfor不會重新創建所有的元素，而是更新已存在的元素。

下面是卡片排序例子，卡片總是按年齡排序。當你修改某個卡片中的年齡數據時，卡片會實時調整順序。但是，光標焦點不會離開輸入框。

 from typing import List
from nicegui import ui
from ex4nicegui import rxui , deep_ref as ref , Ref


class Person ( rxui . ViewModel ):
    def __init__ ( self , name : str , age : int ) -> None :
        self . name = name
        self . age = ref ( age )


class MyApp ( rxui . ViewModel ):
    persons : Ref [ List [ Person ]] = rxui . var ( lambda : [])
    order = rxui . var ( "asc" )

    def sort_by_age ( self ):
        return sorted (
            self . persons . value ,
            key = lambda p : p . age . value ,
            reverse = self . order . value == "desc" ,
        )

    @ staticmethod
    def create ():
        persons = [
            Person ( name = "Alice" , age = 25 ),
            Person ( name = "Bob" , age = 30 ),
            Person ( name = "Charlie" , age = 20 ),
            Person ( name = "Dave" , age = 35 ),
            Person ( name = "Eve" , age = 28 ),
        ]
        app = MyApp ()
        app . persons . value = persons
        return app


# ui
app = MyApp . create ()

with rxui . tabs ( app . order ):
    rxui . tab ( "asc" , "Ascending" )
    rxui . tab ( "desc" , "Descending" )


@ rxui . vfor ( app . sort_by_age , key = "name" )
def each_person ( s : rxui . VforStore [ Person ]):
    person = s . get_item ()

    with ui . card (), ui . row ( align_items = "center" ):
        rxui . label ( person . name )
        rxui . number ( value = person . age , step = 1 , min = 0 , max = 100 )

• rxui.vfor裝飾器到自定義函數
  • 第一個參數傳入響應式列表。注意，無須調用app.sort_by_age
  • 第二個參數key : 為了可以跟踪每個節點的標識，從而重用和重新排序現有的元素，你可以為每個元素對應的塊提供一個唯一的key 。默認情況使用列表元素索引。例子中假定每個人的名字唯一。
• 自定義函數帶有一個參數。通過store.get_item可以獲取當前行的對象。由於Person 本身繼承自rxui.ViewModel ，所以它的各項屬性可以直接綁定到組件。

---

bind_classes

所有的組件類提供bind_classes用於綁定class ，支持三種不同的數據結構。

綁定字典

 bg_color = to_ref ( False )
has_error = to_ref ( False )

rxui . label ( "test" ). bind_classes ({ "bg-blue" : bg_color , "text-red" : has_error })

rxui . switch ( "bg_color" , value = bg_color )
rxui . switch ( "has_error" , value = has_error )

字典鍵值為類名,對應值為bool 的響應式變量。當響應式值為True ，類名應用到組件class

---

綁定返回值為字典的響應式變量

 bg_color = to_ref ( False )
has_error = to_ref ( False )

class_obj = ref_computed (
    lambda : { "bg-blue" : bg_color . value , "text-red" : has_error . value }
)

rxui . switch ( "bg_color" , value = bg_color )
rxui . switch ( "has_error" , value = has_error )
rxui . label ( "bind to ref_computed" ). bind_classes ( class_obj )
# or direct function passing
rxui . label ( "bind to ref_computed" ). bind_classes (
    lambda : { "bg-blue" : bg_color . value , "text-red" : has_error . value }
)

---

綁定為列表或單個字符串的響應式變量

 bg_color = to_ref ( "red" )
bg_color_class = ref_computed ( lambda : f"bg- { bg_color . value } " )

text_color = to_ref ( "green" )
text_color_class = ref_computed ( lambda : f"text- { text_color . value } " )

rxui . select ([ "red" , "green" , "yellow" ], label = "bg color" , value = bg_color )
rxui . select ([ "red" , "green" , "yellow" ], label = "text color" , value = text_color )

rxui . label ( "binding to arrays" ). bind_classes ([ bg_color_class , text_color_class ])
rxui . label ( "binding to single string" ). bind_classes ( bg_color_class )

• 列表中每個元素為返回類名的響應式變量

---

bind_style

 from nicegui import ui
from ex4nicegui . reactive import rxui
from ex4nicegui . utils . signals import to_ref


bg_color = to_ref ( "blue" )
text_color = to_ref ( "red" )

rxui . label ( "test" ). bind_style (
    {
        "background-color" : bg_color ,
        "color" : text_color ,
    }
)

rxui . select ([ "blue" , "green" , "yellow" ], label = "bg color" , value = bg_color )
rxui . select ([ "red" , "green" , "yellow" ], label = "text color" , value = text_color )

bind_style傳入字典， key為樣式名字， value為樣式值，響應式字符串

---

bind_prop

綁定單個屬性

 label = to_ref ( "hello" )

rxui . button ( "" ). bind_prop ( "label" , label )
# 允许使用函数
rxui . button ( "" ). bind_prop (
    "label" , lambda : f" { label . value } world"
)

rxui . input ( value = label )

---

rxui.echarts

使用echarts 製作圖表

 from nicegui import ui
from ex4nicegui import ref_computed , effect , to_ref
from ex4nicegui . reactive import rxui

r_input = to_ref ( "" )

# ref_computed 创建只读响应式变量
# 函数中使用任意其他响应式变量，会自动关联
@ ref_computed
def cp_echarts_opts ():
    return {
        "title" : { "text" : r_input . value }, #字典中使用任意响应式变量，通过 .value 获取值
        "xAxis" : {
            "type" : "category" ,
            "data" : [ "Mon" , "Tue" , "Wed" , "Thu" , "Fri" , "Sat" , "Sun" ],
        },
        "yAxis" : { "type" : "value" },
        "series" : [
            {
                "data" : [ 120 , 200 , 150 , 80 , 70 , 110 , 130 ],
                "type" : "bar" ,
                "showBackground" : True ,
                "backgroundStyle" : { "color" : "rgba(180, 180, 180, 0.2)" },
            }
        ],
    }

input = rxui . input ( "输入内容，图表标题会同步" , value = r_input )
# 通过响应式组件对象的 element 属性，获取原生 nicegui 组件对象
input . element . classes ( "w-full" )

rxui . echarts ( cp_echarts_opts )

ui . run ()

echarts 圖表鼠標事件

on函數參數event_name以及query使用,查看echarts 事件中文文檔

以下例子綁定鼠標單擊事件

 from nicegui import ui
from ex4nicegui . reactive import rxui

opts = {
    "xAxis" : { "type" : "value" , "boundaryGap" : [ 0 , 0.01 ]},
    "yAxis" : {
        "type" : "category" ,
        "data" : [ "Brazil" , "Indonesia" , "USA" , "India" , "China" , "World" ],
    },
    "series" : [
        {
            "name" : "first" ,
            "type" : "bar" ,
            "data" : [ 18203 , 23489 , 29034 , 104970 , 131744 , 630230 ],
        },
        {
            "name" : "second" ,
            "type" : "bar" ,
            "data" : [ 19325 , 23438 , 31000 , 121594 , 134141 , 681807 ],
        },
    ],
}

bar = rxui . echarts ( opts )

def on_click ( e : rxui . echarts . EChartsMouseEventArguments ):
    ui . notify ( f"on_click: { e . seriesName } : { e . name } : { e . value } " )


bar . on ( "click" , on_click )

以下例子只針對指定係列觸發鼠標劃過事件

 from nicegui import ui
from ex4nicegui . reactive import rxui

opts = {
    "xAxis" : { "type" : "value" , "boundaryGap" : [ 0 , 0.01 ]},
    "yAxis" : {
        "type" : "category" ,
        "data" : [ "Brazil" , "Indonesia" , "USA" , "India" , "China" , "World" ],
    },
    "series" : [
        {
            "name" : "first" ,
            "type" : "bar" ,
            "data" : [ 18203 , 23489 , 29034 , 104970 , 131744 , 630230 ],
        },
        {
            "name" : "second" ,
            "type" : "bar" ,
            "data" : [ 19325 , 23438 , 31000 , 121594 , 134141 , 681807 ],
        },
    ],
}

bar = rxui . echarts ( opts )

def on_first_series_mouseover ( e : rxui . echarts . EChartsMouseEventArguments ):
    ui . notify ( f"on_first_series_mouseover: { e . seriesName } : { e . name } : { e . value } " )


bar . on ( "mouseover" , on_first_series_mouseover , query = { "seriesName" : "first" })

ui . run ()

---

---

rxui.echarts.from_javascript

從javascript 代碼創建echart

 from pathlib import Path

rxui . echarts . from_javascript ( Path ( "code.js" ))
# or
rxui . echarts . from_javascript (
    """
(myChart) => {

    option = {
        xAxis: {
            type: 'category',
            data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
        },
        yAxis: {
            type: 'value'
        },
        series: [
            {
                data: [120, 200, 150, 80, 70, 110, 130],
                type: 'bar'
            }
        ]
    };

    myChart.setOption(option);
}
"""
)

• 函數第一個參數為echart 實例對象.你需要在函數中通過setOption完成圖表配置

函數也有第二個參數，為echarts全局對象，你可以通過echarts.registerMap註冊地圖。

 rxui . echarts . from_javascript (
"""
(chart,echarts) =>{

    fetch('https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json')
    .then(response => response.json())
    .then(data => {
            echarts.registerMap('test_map', data);

            chart.setOption({
                geo: {
                    map: 'test_map',
                    roam: true,
                },
                tooltip: {},
                legend: {},
                series: [],
            });
    });
}
"""
)

---

rxui.echarts.register_map

註冊地圖.

 rxui . echarts . register_map (
    "china" , "https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json"
)

rxui . echarts (
    {
        "geo" : {
            "map" : "china" ,
            "roam" : True ,
        },
        "tooltip" : {},
        "legend" : {},
        "series" : [],
    }
)

• 參數map_name為自定義的地圖名字。注意在圖表配置中map必需對應註冊的名字
• 參數src為有效的地圖數據網絡鏈接。

如果是svg 數據，需要設置參數type="svg"

 rxui . echarts . register_map ( "svg-rect" , "/test/svg" , type = "svg" )

你也可以直接提供本地地圖數據的json文件路徑對象(Path)

 from pathlib import Path

rxui . echarts . register_map (
    "china" , Path ( "map-data.json" )
)

---

tab_panels

相比較於nicegui.ui.tab_panels , rxui.tab_panels沒有參數tabs 。在數據響應式機制下， tabs與tab_panels聯動只需要通過參數value即可。

 from nicegui import ui
from ex4nicegui import rxui , to_ref

names = [ "Tab 1" , "Tab 2" , "Tab 3" ]
current_tab = to_ref ( names [ 0 ])

with rxui . tabs ( current_tab ):
    for name in names :
        rxui . tab ( name )

with rxui . tab_panels ( current_tab ):
    for name in names :
        with rxui . tab_panel ( name ):
            ui . label ( f"Content of { name } " )

這是因為，數據響應機制下，組件聯動是通過中間數據層( to_ref )實現的。因此， tab_panels可以與其他組件聯動(只需要保證使用同樣的ref對象即可)

 names = [ "Tab 1" , "Tab 2" , "Tab 3" ]
current_tab = to_ref ( names [ 0 ])


with rxui . tab_panels ( current_tab ):
    for name in names :
        with rxui . tab_panel ( name ):
            ui . label ( f"Content of { name } " )

# tabs 不必在 panels 前面
with rxui . tabs ( current_tab ):
    for name in names :
        rxui . tab ( name )

rxui . select ( names , value = current_tab )
rxui . radio ( names , value = current_tab ). props ( "inline" )

rxui . label ( lambda : f"当前 tab 为: { current_tab . value } " )

---

lazy_tab_panels

懶加載模式下，只有當前激活的tab 才會渲染。

 from ex4nicegui import to_ref , rxui , on , deep_ref

current_tab = to_ref ( "t1" )

with rxui . tabs ( current_tab ):
    ui . tab ( "t1" )
    ui . tab ( "t2" )

with rxui . lazy_tab_panels ( current_tab ) as panels :

    @ panels . add_tab_panel ( "t1" )
    def _ ():
        # 通过 `panels.get_panel` 获取当前激活的 panel 组件
        panels . get_panel ( "t1" ). classes ( "bg-green" )
        ui . notify ( "Hello from t1" )
        ui . label ( "This is t1" )

    @ panels . add_tab_panel ( "t2" )
    def _ ():
        panels . get_panel ( "t2" ). style ( "background-color : red" )
        ui . notify ( "Hello from t2" )
        ui . label ( "This is t2" )

頁面加載後，立刻顯示"Hello from t1"。當切換到"t2" 頁簽，才會顯示"Hello from t2"。

---

scoped_style

scoped_style方法允許你創建限定在組件內部的樣式。

 # 所有子元素都会有红色轮廓，但排除自身
with rxui . row (). scoped_style ( "*" , "outline: 1px solid red;" ) as row :
    ui . label ( "Hello" )
    ui . label ( "World" )


# 所有子元素都会有红色轮廓，包括自身
with rxui . row (). scoped_style ( ":self *" , "outline: 1px solid red;" ) as row :
    ui . label ( "Hello" )
    ui . label ( "World" )

# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，但排除自身
with rxui . row (). scoped_style ( ":hover *" , "outline: 1px solid red;" ) as row :
    ui . label ( "Hello" )
    ui . label ( "World" )

# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，包括自身
with rxui . row (). scoped_style ( ":self:hover *" , "outline: 1px solid red;" ) as row :
    ui . label ( "Hello" )
    ui . label ( "World" )

---

BI 模塊

以最精簡的apis 創建可交互的數據可視化報表

 from nicegui import ui
import pandas as pd
import numpy as np
from ex4nicegui import bi
from ex4nicegui . reactive import rxui
from ex4nicegui import effect , effect_refreshable
from pyecharts . charts import Bar


# data ready
def gen_data ():
    np . random . seed ( 265 )
    field1 = [ "a1" , "a2" , "a3" , "a4" ]
    field2 = [ f"name { i } " for i in range ( 1 , 11 )]
    df = (
        pd . MultiIndex . from_product ([ field1 , field2 ], names = [ "cat" , "name" ])
        . to_frame ()
        . reset_index ( drop = True )
    )
    df [[ "idc1" , "idc2" ]] = np . random . randint ( 50 , 1000 , size = ( len ( df ), 2 ))
    return df


df = gen_data ()

# 创建数据源
ds = bi . data_source ( df )

# ui
ui . query ( ".nicegui-content" ). classes ( "items-stretch no-wrap" )

with ui . row (). classes ( "justify-evenly" ):
    # 基于数据源 `ds` 创建界面组件
    ds . ui_select ( "cat" ). classes ( "min-w-[10rem]" )
    ds . ui_select ( "name" ). classes ( "min-w-[10rem]" )


with ui . grid ( columns = 2 ):
    # 使用字典配置图表
    @ ds . ui_echarts
    def bar1 ( data : pd . DataFrame ):
        data = data . groupby ( "name" ). agg ({ "idc1" : "sum" , "idc2" : "sum" }). reset_index ()

        return {
            "xAxis" : { "type" : "value" },
            "yAxis" : {
                "type" : "category" ,
                "data" : data [ "name" ]. tolist (),
                "inverse" : True ,
            },
            "legend" : { "textStyle" : { "color" : "gray" }},
            "series" : [
                { "type" : "bar" , "name" : "idc1" , "data" : data [ "idc1" ]. tolist ()},
                { "type" : "bar" , "name" : "idc2" , "data" : data [ "idc2" ]. tolist ()},
            ],
        }

    bar1 . classes ( "h-[20rem]" )

    # 使用pyecharts配置图表
    @ ds . ui_echarts
    def bar2 ( data : pd . DataFrame ):
        data = data . groupby ( "name" ). agg ({ "idc1" : "sum" , "idc2" : "sum" }). reset_index ()

        return (
            Bar ()
            . add_xaxis ( data [ "name" ]. tolist ())
            . add_yaxis ( "idc1" , data [ "idc1" ]. tolist ())
            . add_yaxis ( "idc2" , data [ "idc2" ]. tolist ())
        )

    bar2 . classes ( "h-[20rem]" )

    # 绑定点击事件，即可实现跳转
    @ bar2 . on_chart_click
    def _ ( e : rxui . echarts . EChartsMouseEventArguments ):
        ui . open ( f"/details/ { e . name } " , new_tab = True )


# 利用响应式机制，你可以随意组合原生 nicegui 组件
label_a1_total = ui . label ( "" )


# 当 ds 有变化，都会触发此函数
@ effect
def _ ():
    # filtered_data 为过滤后的 DataFrame
    df = ds . filtered_data
    total = df [ df [ "cat" ] == "a1" ][ "idc1" ]. sum ()
    label_a1_total . text = f"idc1 total(cat==a1): { total } "


# 你也可以使用 `effect_refreshable`,但需要注意函数中的组件每次都被重建
@ effect_refreshable
def _ ():
    df = ds . filtered_data
    total = df [ df [ "cat" ] == "a2" ][ "idc1" ]. sum ()
    ui . label ( f"idc1 total(cat==a2): { total } " )


# 当点击图表系列时，跳转的页面
@ ui . page ( "/details/{name}" )
def details_page ( name : str ):
    ui . label ( "This table data will not change" )
    ui . aggrid . from_pandas ( ds . data . query ( f'name==" { name } "' ))

    ui . label ( "This table will change when the homepage data changes. " )

    @ bi . data_source
    def new_ds ():
        return ds . filtered_data [[ "name" , "idc1" , "idc2" ]]

    new_ds . ui_aggrid ()


ui . run ()

---

bi.data_source

數據源是BI 模塊的核心概念，所有數據的聯動基於此展開。當前版本(0.4.3)中，有兩種創建數據源的方式

接收pandas的DataFrame :

 from nicegui import ui
from ex4nicegui import bi
import pandas as pd

df = pd . DataFrame (
    {
        "name" : list ( "aabcdf" ),
        "cls" : [ "c1" , "c2" , "c1" , "c1" , "c3" , None ],
        "value" : range ( 6 ),
    }
)

ds =  bi . data_source ( df )

---

有時候，我們希望基於另一個數據源創建新的數據源，此時可以使用裝飾器創建聯動數據源:

 df = pd . DataFrame (
    {
        "name" : list ( "aabcdf" ),
        "cls" : [ "c1" , "c2" , "c1" , "c1" , "c3" , None ],
        "value" : range ( 6 ),
    }
)

ds =  bi . data_source ( df )

@ bi . data_source
def new_ds ():
    # df is pd.DataFrame 
    df = ds . filtered_data
    df = df . copy ()
    df [ 'value' ] = df [ 'value' ] * 100
    return df

ds . ui_select ( 'name' )
new_ds . ui_aggrid ()

注意，由於new_ds中使用了ds.filtered_data ，因此ds的變動會觸發new_ds的聯動變化，從而導致new_ds創建的表格組件產生變化

---

通過ds.remove_filters方法，移除所有篩選狀態:

 ds = bi . data_source ( df )

def on_remove_filters ():
    ds . remove_filters ()

ui . button ( "remove all filters" , on_click = on_remove_filters )

ds . ui_select ( "name" )
ds . ui_aggrid ()

---

通過ds.reload方法，重設數據源:

 df = pd . DataFrame (
    {
        "name" : list ( "aabcdf" ),
        "cls" : [ "c1" , "c2" , "c1" , "c1" , "c3" , None ],
        "value" : range ( 6 ),
    }
)

new_df = pd . DataFrame (
    {
        "name" : list ( "xxyyds" ),
        "cls" : [ "cla1" , "cla2" , "cla3" , "cla3" , "cla3" , None ],
        "value" : range ( 100 , 106 ),
    }
)

ds = bi . data_source ( df )

def on_remove_filters ():
    ds . reload ( new_df )

ui . button ( "reload data" , on_click = on_remove_filters )

ds . ui_select ( "name" )
ds . ui_aggrid ()

---

ui_select

 from nicegui import ui
from ex4nicegui import bi
import pandas as pd

df = pd . DataFrame (
    {
        "name" : list ( "aabcdf" ),
        "cls" : [ "c1" , "c2" , "c1" , "c1" , "c3" , None ],
        "value" : range ( 6 ),
    }
)

ds = bi . data_source ( df )

ds . ui_select ( "name" )

第一個參數column 指定數據源的列名

---

通過參數sort_options設置選項順序:

 ds . ui_select ( "name" , sort_options = { "value" : "desc" , "name" : "asc" })

---

參數exclude_null_value設置是否排除空值:

 df = pd . DataFrame (
    {
        "cls" : [ "c1" , "c2" , "c1" , "c1" , "c3" , None ],
    }
)

ds = bi . data_source ( df )
ds . ui_select ( "cls" , exclude_null_value = True )

---

你可以通過關鍵字參數，設置原生nicegui select 組件的參數.

通過value 屬性，設置默認值:

 ds . ui_select ( "cls" , value = [ 'c1' , 'c2' ])
ds . ui_select ( "cls" , multiple = False , value = 'c1' )

多選時(參數multiple默認為True)， value需要指定為list

單選時， value設置為非list

---

ui_table

表格

 from nicegui import ui
from ex4nicegui import bi
import pandas as pd

data = pd . DataFrame ({ "name" : [ "f" , "a" , "c" , "b" ], "age" : [ 1 , 2 , 3 , 1 ]})
ds = bi . data_source ( data )

ds . ui_table (
    columns = [
        { "label" : "new colA" , "field" : "colA" , "sortable" : True },
    ]
)

• columns 與nicegui ui.table一致。其中鍵值field對應數據源的列名，如果不存在，則該配置不會生效
• rows 參數不會生效。因為表格的數據源始終由data source 控制

---

ui_aggrid

 from nicegui import ui
from ex4nicegui import bi
import pandas as pd

data = pd . DataFrame (
    {
        "colA" : list ( "abcde" ),
        "colB" : [ f"n { idx } " for idx in range ( 5 )],
        "colC" : list ( range ( 5 )),
    }
)
df = pd . DataFrame ( data )

source = bi . data_source ( df )

source . ui_aggrid (
    options = {
        "columnDefs" : [
            { "headerName" : "xx" , "field" : "no exists" },
            { "headerName" : "new colA" , "field" : "colA" },
            {
                "field" : "colC" ,
                "cellClassRules" : {
                    "bg-red-300" : "x < 3" ,
                    "bg-green-300" : "x >= 3" ,
                },
            },
        ],
        "rowData" : [{ "colX" : [ 1 , 2 , 3 , 4 , 5 ]}],
    }
)

• 參數options 與nicegui ui.aggrid一致。其中columnDefs中的鍵值field對應數據源的列名，如果不存在，則該配置不會生效
• rowData鍵值不會生效。因為表格的數據源始終由data source 控制

toolbox

toolbox模塊提供了一些常用的工具函數。

 from ex4nicegui import toolbox 

use_dark

切換暗模式

 from ex4nicegui import rxui , toolbox as tb
from nicegui import ui


dark = tb . use_dark ( False )

rxui . label ( lambda : f"暗模式: { dark . value } " )
rxui . button (
    icon = lambda : "sunny" if dark . value else "dark_mode" ,
    color = lambda : "red" if dark . value else "blue" ,
    on_click = dark . toggle ,
). props ( "flat round" )

use_breakpoints

響應式斷點

 from ex4nicegui import rxui , toolbox as tb
from nicegui import ui


options = { "手机" : 0 , "平板" : 640 , "笔记本" : 1024 , "桌面" : 1280 }
bp = tb . use_breakpoints ( options )
active = bp . active
is_between = bp . between ( "手机" , "笔记本" )

with ui . card ():
    rxui . label ( lambda : f"当前断点: { active . value } " )
    rxui . label ( lambda : f"是否在手机-笔记本(不含)之间: { is_between . value } " ). bind_classes (
        { "text-red-500" : is_between }
    )

    rxui . label ( lambda : f'手机(0px - 640px): { active . value == "手机" } ' ). bind_classes (
        { "bg-red-300" : lambda : active . value == "手机" }
    )
    rxui . label ( lambda : f'平板(640px - 1024px): { active . value == "平板" } ' ). bind_classes (
        { "bg-red-300" : lambda : active . value == "平板" }
    )
    rxui . label (
        lambda : f'笔记本(1024px - 1280px): { active . value == "笔记本" } '
    ). bind_classes ({ "bg-red-300" : lambda : active . value == "笔记本" })
    rxui . label ( lambda : f'桌面(1280px+): { active . value == "桌面" } ' ). bind_classes (
        { "bg-red-300" : lambda : active . value == "桌面" }
    )

use_qr_code

生成二維碼

 from ex4nicegui import rxui , to_ref , toolbox as tb
from nicegui import ui


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

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