更新文档

Author: xinetzone

doc/ui/nicegui/events/Async.ipynb

@@ -0,0 +1,19 @@
+# NiceGUI 异步事件处理器
+
+大多数元素也支持异步事件处理器。
+
+注意：您还可以将 `functools.partial` 传递给 `on_click` 属性，以包装带参数的异步函数。
+
+```python
+import asyncio
+from nicegui import ui
+
+async def async_task():
+    ui.notify('Asynchronous task started')
+    await asyncio.sleep(5)
+    ui.notify('Asynchronous task finished')
+
+ui.button('start async task', on_click=async_task)
+
+# ui.run()
+```

doc/ui/nicegui/events/Async.md

@@ -0,0 +1,28 @@
+# NiceGUI 事件
+
+您可以注册协程或函数，以便在以下事件发生时被调用：
+
+- `app.on_startup`：在 NiceGUI 启动或重启时调用
+- `app.on_shutdown`：在 NiceGUI 关闭或重启时调用
+- `app.on_connect`：每个连接的客户端都会调用（可选参数：`nicegui.Client`）
+- `app.on_disconnect`：每个断开连接的客户端都会调用（可选参数：`nicegui.Client`）
+- `app.on_exception`：发生异常时调用（可选参数：`exception`）
+
+当 NiceGUI 关闭或重启时，所有仍在执行的任务将自动取消。
+
+```python
+from datetime import datetime
+from nicegui import app, ui
+
+dt = datetime.now()
+
+def handle_connection():
+    global dt
+    dt = datetime.now()
+app.on_connect(handle_connection)
+
+label = ui.label()
+ui.timer(1, lambda: label.set_text(f'Last new connection: {dt:%H:%M:%S}'))
+
+# ui.run()
+```

doc/ui/nicegui/events/Events.ipynb

@@ -0,0 +1,58 @@
+
+# NiceGUI 存储
+
+NiceGUI 为应用程序内的数据持久性提供了一种简便的方法。它具有三种内置存储类型：
+
+- `app.storage.user`：存储在服务器端，每个字典都与浏览器会话cookie中的唯一标识符相关联。对于每个用户都是唯一的，这种存储可以在他们所有的浏览器标签页中访问。`app.storage.browser['id']` 用于识别用户。
+- `app.storage.general`：也存储在服务器端，这个字典提供了一个所有用户都可以访问的共享存储空间。
+- `app.storage.browser`：与前两种类型不同，这个字典直接作为浏览器会话cookie存储，在同一用户的所有浏览器标签页之间共享。然而，由于 `app.storage.user` 在减少数据负载、增强安全性和提供更大的存储容量方面的优势，通常更倾向于使用它。默认情况下，NiceGUI 在 `app.storage.browser['id']` 中保存浏览器会话的唯一标识符。
+
+用户存储和浏览器存储仅在页面构建器函数 [pages](../pages/index) 中可用，因为它们正在访问 FastAPI 的底层请求对象。此外，这两种类型需要在 `ui.run()` 中的 `storage_secret` 参数来加密浏览器会话 cookie。
+
+```python
+from nicegui import app, ui
+
+@ui.page('/')
+def index():
+    app.storage.user['count'] = app.storage.user.get('count', 0) + 1
+    with ui.row():
+       ui.label('your own page visits:')
+       ui.label().bind_text_from(app.storage.user, 'count')
+
+# ui.run(storage_secret='private key to secure the browser session cookie')
+```
+
+## NiceGUI 统计页面访问次数
+
+在这里，我们使用自动可用的浏览器存储的会话 ID 来计算唯一页面访问次数。
+
+```python
+from collections import Counter
+from datetime import datetime
+from nicegui import app, ui
+
+counter = Counter()
+start = datetime.now().strftime('%H:%M, %d %B %Y')
+
+@ui.page('/')
+def index():
+    counter[app.storage.browser['id']] += 1
+    ui.label(f'{len(counter)} unique views ({sum(counter.values())} overall) since {start}')
+
+# ui.run(storage_secret='private key to secure the browser session cookie')
+```
+
+## NiceGUI 存储 UI 状态
+
+存储也可以与[绑定](https://nicegui.io/documentation/bindings)结合使用。在这里，我们正在保存访问之间的文本区域值。同一用户的所有标签页之间也共享该便签。
+
+```python
+from nicegui import app, ui
+
+@ui.page('/')
+def index():
+    ui.textarea('This note is kept between visits') \
+        .classes('w-full').bind_value(app.storage.user, 'note')
+
+# ui.run()
+```