ex4nicegui 0.6.9__tar.gz → 0.7.1__tar.gz

{ex4nicegui-0.6.9 → ex4nicegui-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ex4nicegui
-Version: 0.6.9
+Version: 0.7.1
 Summary: Extension library based on nicegui, providing data responsive,BI functionality modules
 Home-page: https://github.com/CrystalWindSnake/ex4nicegui
 License: MIT
@@ -17,13 +17,17 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: executing (>=2.0.1,<3.0.0)
 Requires-Dist: nicegui (>=1.4.25,<2.0.0)
-Requires-Dist: signe (>=0.4.14,<0.5.0)
+Requires-Dist: signe (>=0.4.20,<0.5.0)
 Project-URL: Repository, https://github.com/CrystalWindSnake/ex4nicegui
 Description-Content-Type: text/markdown
 
 # ex4nicegui
-[ENGLISH README](./README.en.md)
 
+<div align="center">
+
+简体中文| [English](./README.en.md)
+
+</div>
 
 - [教程](#教程)
 - [安装](#-安装)
@@ -34,6 +38,10 @@ Description-Content-Type: text/markdown
 对 [nicegui](https://github.com/zauberzeug/nicegui) 做的扩展库。内置响应式组件，完全实现数据响应式界面编程。
 
 
+![todo-app](https://github.com/CrystalWindSnake/ex4nicegui-examples/blob/main/asset/todo-app.02.gif)
+
+[查看更多示例](https://github.com/CrystalWindSnake/ex4nicegui-examples)
+
 ## 教程
 [头条文章-秒杀官方实现，python界面库，去掉90%事件代码的nicegui](https://www.toutiao.com/item/7253786340574265860/)
 
@@ -191,6 +199,154 @@ ui.run()
 ---
 
 
+
+## ViewModel
+在 `v0.7.0` 版本中，引入 `ViewModel` 类，用于管理一组响应式数据。
+
+下面是一个简单的计算器示例：
+
+1. 当用户修改数值输入框或符号选择框，右侧会自动显示计算结果
+2. 当结果小于 0 时，结果显示为红色，否则为黑色
+
+```python
+from ex4nicegui import rxui
+
+class Calculator(rxui.ViewModel):
+    num1 = rxui.var(0)
+    sign = rxui.var("+")
+    num2 = rxui.var(0)
+
+    def result(self):
+        # 当 num1,sign,num2 任意一个值发生变化时，result 也会重新计算
+        return eval(f"{self.num1.value}{self.sign.value}{self.num2.value}")
+
+# 每个对象拥有独立的数据
+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"
+    )
+
+```
+
+### cached_var
+
+上面的示例中，由于使用了两次 `calc.result` 。因此，每当 `num1`, `sign`, `num2` 任意一个值发生变化时，`result` 都会执行2次。
+
+实际上，第二次的计算是多余的。我们可以通过添加 `rxui.cached_var` 装饰器，避免多余的计算。
+
+```python
+class Calculator(rxui.ViewModel):
+    ...
+
+    @rxui.cached_var
+    def result(self):
+        return eval(f"{self.num1.value}{self.sign.value}{self.num2.value}")
+
+...
+```
+
+---
+
+### 使用列表
+
+当数据为可变对象时，比如列表，字典等，需要提供工厂函数传给 `rxui.var`
+
+
+```python
+class Home(rxui.ViewModel):
+    persons= rxui.var(lambda: [])
+
+```
+
+下面的示例，每个 person 使用卡片展示。最上方显示所有人的平均年龄。当个人年龄大于平均年龄，卡片外边框将变为红色。
+通过 `number` 组件修改年龄，一切都会自动更新。
+
+```python
+from ex4nicegui import rxui, Ref
+from itertools import count
+
+id_generator = count()
+
+class Person(rxui.ViewModel):
+    name = rxui.var("")
+    age = rxui.var(0)
+
+    def __init__(self, name: str = "", age: int = 0):
+        super().__init__()
+        self.name.value = name
+        self.age.value = age
+        self.id = next(id_generator)
+
+
+class Home(rxui.ViewModel):
+    persons: Ref[List[Person]] = rxui.var(lambda: [])
+
+    def avg_age(self) -> float:
+        if len(self.persons.value) == 0:
+            return 0
+
+        return sum(p.age.value for p in self.persons.value) / len(self.persons.value)
+
+    def sample_data(self):
+        self.persons.value = [
+            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()}")
+
+
+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.value > home.avg_age(),
+            }
+        ):
+            rxui.input(value=person.name, placeholder="名字")
+            rxui.number(value=person.age, min=1, max=100, step=1, placeholder="年龄")
+
+```
+
+如果你觉得 `rxui.vfor` 代码过于复杂，可以使用 `effect_refreshable` 装饰器代替。
+
+```python
+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](./examples)
+
+---
+
 ## 响应式
 
 ```python
@@ -331,15 +487,14 @@ ui.button("change", on_click=change_value)
 
 > `ref_computed` 是只读的 `to_ref`
 
-
-如果你更喜欢通过类组织代码，`ref_computed` 同样支持作用到实例方法上
+从 `v0.7.0` 版本开始，不建议使用 `ref_computed` 应用实例方法。你可以使用 `rxui.ViewModel`，并使用 `rxui.cached_var` 装饰器
 
 ```python
-class MyState:
+class MyState(rxui.ViewModel):
     def __init__(self) -> None:
         self.r_text = to_ref("")
 
-    @ref_computed
+    @rxui.cached_var
     def post_text(self):
         return self.r_text.value + "post"
 
@@ -494,70 +649,90 @@ rxui.input(value=data.value["a"])
 rxui.input(value=lambda: data.value["a"])
 
 # 要使用 vmodel 才能双向绑定
-rxui.input(value=rxui.vmodel(data.value["a"]))
+rxui.input(value=rxui.vmodel(data, "a"))
+
+# 也可以直接使用，但不推荐
+rxui.input(value=rxui.vmodel(data.value['a']))
+
 ```
 
-- 第一个输入框将完全失去响应性，因为代码等价于直接传入一个数值`1`
+- 第一个输入框将完全失去响应性，因为代码等价于 `rxui.input(value=1)`
 - 第二个输入框由于使用函数，将得到读取响应性(第三个输入框输入值，将得到同步)
 - 第三个输入框，使用 `rxui.vmodel` 包裹，即可实现双向绑定
 
-多数在配合 `vfor` 时使用 `vmodel`,可参考 [todo list 案例](./examples/todomvc/)
+> 如果使用 `rxui.ViewModel` ，你可能不需要使用 `vmodel`
 
+可参考 [todo list 案例](./examples/todomvc/)
+
+---
 
 ### vfor
-基于列表响应式数据，渲染列表组件。每项组件按需更新。数据项支持字典或任意类型对象
+基于列表响应式数据，渲染列表组件。每项组件按需更新。数据项支持字典或任意类型对象。
+
+从 `v0.7.0` 版本开始，建议配合 `rxui.ViewModel` 使用。与使用 `effect_refreshable` 装饰器不同，`vfor` 不会重新创建所有的元素，而是更新已存在的元素。
+
+下面是卡片排序例子，卡片总是按年龄排序。当你修改某个卡片中的年龄数据时，卡片会实时调整顺序。但是，光标焦点不会离开输入框。
+
 
 ```python
+from typing import List
 from nicegui import ui
-from ex4nicegui.reactive import rxui
-from ex4nicegui import deep_ref, ref_computed
-from typing import Dict
-
-# refs
-items = deep_ref(
-    [
-        {"id": 1, "message": "foo", "done": False},
-        {"id": 2, "message": "bar", "done": True},
-    ]
-)
+from ex4nicegui import rxui, deep_ref as ref, Ref
 
-# ref_computeds
-@ref_computed
-def done_count_info():
-    return f"done count:{sum(item['done'] for item in items.value)}"
 
-# method
-def check():
-    for item in items.value:
-        item["done"] = not item["done"]
+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
-rxui.label(done_count_info)
-ui.button("check", on_click=check)
+app = MyApp.create()
 
+with rxui.tabs(app.order):
+    rxui.tab("asc", "Ascending")
+    rxui.tab("desc", "Descending")
 
-@rxui.vfor(items,key='id')
-def _(store: rxui.VforStore[Dict]):
-    # 函数中构建每一行数据的界面
-    item = store.get()  # 通过 store.get 获取对应行的响应式对象(相当于每行的数据 to_ref(...))
-    mes = rxui.vmodel(item.value['message']) # 复杂结构默认没有双向绑定，需要使用 `vmodel`
 
-    # 输入框输入内容，可以看到单选框的标题同步变化
-    with ui.card():
-        with ui.row():
-            rxui.input(value=mes)
-            rxui.label(lambda: f"{mes.value=!s}")
-        rxui.checkbox(text=mes, value=rxui.vmodel(item.value['done']))
+@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` 装饰器到自定义函数
-    - 第一个参数传入响应式列表。列表中每一项可以是字典或其他对象(`dataclasses` 等等)
-    - 第二个参数 `key`: 为了可以跟踪每个节点的标识，从而重用和重新排序现有的元素，你可以为每个元素对应的块提供一个唯一的 key 。默认情况使用列表元素索引。
-- 自定义函数带有一个参数。通过 `store.get` 可以获取当前行的响应式对象
-
-> vfor 渲染的项目，只有在新增数据时，才会创建
+    - 第一个参数传入响应式列表。注意，无须调用 `app.sort_by_age`
+    - 第二个参数 `key`: 为了可以跟踪每个节点的标识，从而重用和重新排序现有的元素，你可以为每个元素对应的块提供一个唯一的 key 。默认情况使用列表元素索引。例子中假定每个人的名字唯一。
+- 自定义函数带有一个参数。通过 `store.get_item` 可以获取当前行的对象。由于 Person 本身继承自 `rxui.ViewModel`，所以它的各项属性可以直接绑定到组件。
 
 
 ---

{ex4nicegui-0.6.9 → ex4nicegui-0.7.1}/README.md

@@ -1,6 +1,10 @@
 # ex4nicegui
-[ENGLISH README](./README.en.md)
 
+<div align="center">
+
+简体中文| [English](./README.en.md)
+
+</div>
 
 - [教程](#教程)
 - [安装](#-安装)
@@ -11,6 +15,10 @@
 对 [nicegui](https://github.com/zauberzeug/nicegui) 做的扩展库。内置响应式组件，完全实现数据响应式界面编程。
 
 
+![todo-app](https://github.com/CrystalWindSnake/ex4nicegui-examples/blob/main/asset/todo-app.02.gif)
+
+[查看更多示例](https://github.com/CrystalWindSnake/ex4nicegui-examples)
+
 ## 教程
 [头条文章-秒杀官方实现，python界面库，去掉90%事件代码的nicegui](https://www.toutiao.com/item/7253786340574265860/)
 
@@ -168,6 +176,154 @@ ui.run()
 ---
 
 
+
+## ViewModel
+在 `v0.7.0` 版本中，引入 `ViewModel` 类，用于管理一组响应式数据。
+
+下面是一个简单的计算器示例：
+
+1. 当用户修改数值输入框或符号选择框，右侧会自动显示计算结果
+2. 当结果小于 0 时，结果显示为红色，否则为黑色
+
+```python
+from ex4nicegui import rxui
+
+class Calculator(rxui.ViewModel):
+    num1 = rxui.var(0)
+    sign = rxui.var("+")
+    num2 = rxui.var(0)
+
+    def result(self):
+        # 当 num1,sign,num2 任意一个值发生变化时，result 也会重新计算
+        return eval(f"{self.num1.value}{self.sign.value}{self.num2.value}")
+
+# 每个对象拥有独立的数据
+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"
+    )
+
+```
+
+### cached_var
+
+上面的示例中，由于使用了两次 `calc.result` 。因此，每当 `num1`, `sign`, `num2` 任意一个值发生变化时，`result` 都会执行2次。
+
+实际上，第二次的计算是多余的。我们可以通过添加 `rxui.cached_var` 装饰器，避免多余的计算。
+
+```python
+class Calculator(rxui.ViewModel):
+    ...
+
+    @rxui.cached_var
+    def result(self):
+        return eval(f"{self.num1.value}{self.sign.value}{self.num2.value}")
+
+...
+```
+
+---
+
+### 使用列表
+
+当数据为可变对象时，比如列表，字典等，需要提供工厂函数传给 `rxui.var`
+
+
+```python
+class Home(rxui.ViewModel):
+    persons= rxui.var(lambda: [])
+
+```
+
+下面的示例，每个 person 使用卡片展示。最上方显示所有人的平均年龄。当个人年龄大于平均年龄，卡片外边框将变为红色。
+通过 `number` 组件修改年龄，一切都会自动更新。
+
+```python
+from ex4nicegui import rxui, Ref
+from itertools import count
+
+id_generator = count()
+
+class Person(rxui.ViewModel):
+    name = rxui.var("")
+    age = rxui.var(0)
+
+    def __init__(self, name: str = "", age: int = 0):
+        super().__init__()
+        self.name.value = name
+        self.age.value = age
+        self.id = next(id_generator)
+
+
+class Home(rxui.ViewModel):
+    persons: Ref[List[Person]] = rxui.var(lambda: [])
+
+    def avg_age(self) -> float:
+        if len(self.persons.value) == 0:
+            return 0
+
+        return sum(p.age.value for p in self.persons.value) / len(self.persons.value)
+
+    def sample_data(self):
+        self.persons.value = [
+            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()}")
+
+
+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.value > home.avg_age(),
+            }
+        ):
+            rxui.input(value=person.name, placeholder="名字")
+            rxui.number(value=person.age, min=1, max=100, step=1, placeholder="年龄")
+
+```
+
+如果你觉得 `rxui.vfor` 代码过于复杂，可以使用 `effect_refreshable` 装饰器代替。
+
+```python
+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](./examples)
+
+---
+
 ## 响应式
 
 ```python
@@ -308,15 +464,14 @@ ui.button("change", on_click=change_value)
 
 > `ref_computed` 是只读的 `to_ref`
 
-
-如果你更喜欢通过类组织代码，`ref_computed` 同样支持作用到实例方法上
+从 `v0.7.0` 版本开始，不建议使用 `ref_computed` 应用实例方法。你可以使用 `rxui.ViewModel`，并使用 `rxui.cached_var` 装饰器
 
 ```python
-class MyState:
+class MyState(rxui.ViewModel):
     def __init__(self) -> None:
         self.r_text = to_ref("")
 
-    @ref_computed
+    @rxui.cached_var
     def post_text(self):
         return self.r_text.value + "post"
 
@@ -471,70 +626,90 @@ rxui.input(value=data.value["a"])
 rxui.input(value=lambda: data.value["a"])
 
 # 要使用 vmodel 才能双向绑定
-rxui.input(value=rxui.vmodel(data.value["a"]))
+rxui.input(value=rxui.vmodel(data, "a"))
+
+# 也可以直接使用，但不推荐
+rxui.input(value=rxui.vmodel(data.value['a']))
+
 ```
 
-- 第一个输入框将完全失去响应性，因为代码等价于直接传入一个数值`1`
+- 第一个输入框将完全失去响应性，因为代码等价于 `rxui.input(value=1)`
 - 第二个输入框由于使用函数，将得到读取响应性(第三个输入框输入值，将得到同步)
 - 第三个输入框，使用 `rxui.vmodel` 包裹，即可实现双向绑定
 
-多数在配合 `vfor` 时使用 `vmodel`,可参考 [todo list 案例](./examples/todomvc/)
+> 如果使用 `rxui.ViewModel` ，你可能不需要使用 `vmodel`
 
+可参考 [todo list 案例](./examples/todomvc/)
+
+---
 
 ### vfor
-基于列表响应式数据，渲染列表组件。每项组件按需更新。数据项支持字典或任意类型对象
+基于列表响应式数据，渲染列表组件。每项组件按需更新。数据项支持字典或任意类型对象。
+
+从 `v0.7.0` 版本开始，建议配合 `rxui.ViewModel` 使用。与使用 `effect_refreshable` 装饰器不同，`vfor` 不会重新创建所有的元素，而是更新已存在的元素。
+
+下面是卡片排序例子，卡片总是按年龄排序。当你修改某个卡片中的年龄数据时，卡片会实时调整顺序。但是，光标焦点不会离开输入框。
+
 
 ```python
+from typing import List
 from nicegui import ui
-from ex4nicegui.reactive import rxui
-from ex4nicegui import deep_ref, ref_computed
-from typing import Dict
-
-# refs
-items = deep_ref(
-    [
-        {"id": 1, "message": "foo", "done": False},
-        {"id": 2, "message": "bar", "done": True},
-    ]
-)
+from ex4nicegui import rxui, deep_ref as ref, Ref
 
-# ref_computeds
-@ref_computed
-def done_count_info():
-    return f"done count:{sum(item['done'] for item in items.value)}"
 
-# method
-def check():
-    for item in items.value:
-        item["done"] = not item["done"]
+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
-rxui.label(done_count_info)
-ui.button("check", on_click=check)
+app = MyApp.create()
 
+with rxui.tabs(app.order):
+    rxui.tab("asc", "Ascending")
+    rxui.tab("desc", "Descending")
 
-@rxui.vfor(items,key='id')
-def _(store: rxui.VforStore[Dict]):
-    # 函数中构建每一行数据的界面
-    item = store.get()  # 通过 store.get 获取对应行的响应式对象(相当于每行的数据 to_ref(...))
-    mes = rxui.vmodel(item.value['message']) # 复杂结构默认没有双向绑定，需要使用 `vmodel`
 
-    # 输入框输入内容，可以看到单选框的标题同步变化
-    with ui.card():
-        with ui.row():
-            rxui.input(value=mes)
-            rxui.label(lambda: f"{mes.value=!s}")
-        rxui.checkbox(text=mes, value=rxui.vmodel(item.value['done']))
+@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` 装饰器到自定义函数
-    - 第一个参数传入响应式列表。列表中每一项可以是字典或其他对象(`dataclasses` 等等)
-    - 第二个参数 `key`: 为了可以跟踪每个节点的标识，从而重用和重新排序现有的元素，你可以为每个元素对应的块提供一个唯一的 key 。默认情况使用列表元素索引。
-- 自定义函数带有一个参数。通过 `store.get` 可以获取当前行的响应式对象
-
-> vfor 渲染的项目，只有在新增数据时，才会创建
+    - 第一个参数传入响应式列表。注意，无须调用 `app.sort_by_age`
+    - 第二个参数 `key`: 为了可以跟踪每个节点的标识，从而重用和重新排序现有的元素，你可以为每个元素对应的块提供一个唯一的 key 。默认情况使用列表元素索引。例子中假定每个人的名字唯一。
+- 自定义函数带有一个参数。通过 `store.get_item` 可以获取当前行的对象。由于 Person 本身继承自 `rxui.ViewModel`，所以它的各项属性可以直接绑定到组件。
 
 
 ---