Aurora Toolkit - PythonIDE Docs

AppUI 高频更新组件、批量刷新、回调和实时可视化工具。

#预期效果

示例会展示实时更新工具如何批量刷新状态、减少高频 UI 更新的重复工作。

#适用场景

AppUI 高频更新工具，只更新已有稳定 id 的节点。

#标准示例

python

from aurora_toolkit import AuroraLabel, AuroraProgress, frame_batch

label = AuroraLabel("summary", text="Ready")
progress = AuroraProgress("progress", value=0.0)
label.bind()
progress.bind()

with frame_batch():
    label.text = "Working"
    progress.value = 0.5

#高频仪表盘示例

普通 AppUI 负责稳定结构，Aurora 负责高频数值。下面的 appui.Slider(value=0.0, ...) 是首屏结构占位；连续更新交给 AuroraSliderGroup 和 AuroraTextGroup。

python

import appui
from aurora_toolkit import AuroraSliderGroup, AuroraTextGroup, frame_batch

metrics = [
    {"id": "cpu", "title": "CPU"},
    {"id": "memory", "title": "Memory"},
    {"id": "network", "title": "Network"},
]
sliders = AuroraSliderGroup("metric.slider", len(metrics))
labels = AuroraTextGroup("metric.label", len(metrics))


def metric_key(metric):
    return metric["id"]


def metric_row(metric):
    index = metrics.index(metric)
    return appui.VStack([
        appui.Text(metric["title"]).id(f"metric.{index}.label"),
        appui.Slider(value=0.0, minimum=0, maximum=1).id(f"metric.{index}"),
    ], spacing=6)


def push_frame(values):
    with frame_batch():
        for index, value in enumerate(values):
            sliders[index] = value
            labels[index] = f"{metrics[index]['title']} {value:.0%}"


def body():
    return appui.List([
        appui.Section("Live", [
            appui.ForEach(metrics, row_builder=metric_row, key=metric_key)
        ])
    ]).navigation_title("Realtime")

#API 参考

类型	API	签名	说明
function	`frame_batch`	`frame_batch() -> Any`	把同一帧里的多次更新合并提交，适合进度、数值和实时状态。
function	`begin_frame`	`begin_frame() -> Any`	手动开始一组批量更新，适合已有循环里控制提交时机。
function	`end_frame`	`end_frame() -> None`	结束并提交 `begin_frame` 开始的更新。
function	`callback`	`callback(event_id: str)`	为 Aurora 控件注册事件回调。
class	`AuroraSlider`	`AuroraSlider(node_id: str, value: float=...)`	更新滑块数值。
class	`AuroraGauge`	`AuroraGauge(node_id: str, value: float=...)`	更新仪表盘或数字指标。
class	`AuroraProgress`	`AuroraProgress(node_id: str, value: float=...)`	更新进度条。
class	`AuroraStepper`	`AuroraStepper(node_id: str, value: int=..., minimum: int=..., maximum: int=..., step: int=...)`	更新步进器数值。
class	`AuroraLabel`	`AuroraLabel(node_id: str, text: str=..., text_color: Optional[str]=...)`	更新文字内容和文字颜色。
class	`AuroraTextField`	`AuroraTextField(node_id: str, text: str=..., placeholder: str=...)`	更新输入框文字和占位内容。
class	`AuroraToggle`	`AuroraToggle(node_id: str, is_on: bool=...)`	更新开关状态。
class	`AuroraView`	`AuroraView(node_id: str, opacity: float=..., offset_x: float=..., offset_y: float=..., scale: float=..., rotation: float=...)`	更新视图透明度、位移、缩放和旋转。
class	`AuroraPicker`	`AuroraPicker(node_id: str, selection: int=..., options: Optional[list[str]]=...)`	更新选择器当前项。
class	`AuroraDatePicker`	`AuroraDatePicker(node_id: str, timestamp: float=...)`	更新日期选择器时间。
class	`AuroraColorPicker`	`AuroraColorPicker(node_id: str, r: int=..., g: int=..., b: int=..., a: int=...)`	更新颜色选择器。
class	`AuroraSearchField`	`AuroraSearchField(node_id: str, query: str=...)`	更新搜索框内容。
class	`AuroraSecureField`	`AuroraSecureField(node_id: str, text: str=...)`	更新安全输入框内容。
class	`AuroraTextEditor`	`AuroraTextEditor(node_id: str, text: str=...)`	更新多行文本内容。
class	`AuroraButton`	`AuroraButton(node_id: str, title: str=..., callback_id: str=...)`	更新按钮标题并绑定回调。
class	`AuroraImage`	`AuroraImage(node_id: str, system_name: str=...)`	更新系统图标名称。
class	`AuroraLink`	`AuroraLink(node_id: str, url: str=...)`	更新链接地址。
class	`AuroraGaugeBar`	`AuroraGaugeBar(node_id: str, value: float=..., min_val: float=..., max_val: float=...)`	更新带范围的指标条。
class	`AuroraBadge`	`AuroraBadge(node_id: str, count: int=...)`	更新角标数字。
class	`AuroraSegmentedControl`	`AuroraSegmentedControl(node_id: str, selection: int=..., segments: Optional[list[str]]=...)`	更新分段控件选中项。
class	`AuroraSliderGroup`	`AuroraSliderGroup(prefix: str, count: int)`	批量更新一组滑块或数值控件。
class	`AuroraTextGroup`	`AuroraTextGroup(prefix: str, count: int)`	批量更新一组文本节点。
class	`AuroraImageGroup`	`AuroraImageGroup(prefix: str, count: int)`	批量更新一组系统图标。
class	`AuroraToggleGroup`	`AuroraToggleGroup(prefix: str, count: int)`	批量更新一组开关。
class	`AuroraIntGroup`	`AuroraIntGroup(prefix: str, count: int)`	批量更新一组整数选择值。
class	`AuroraColorGroup`	`AuroraColorGroup(prefix: str, count: int)`	批量更新一组颜色值。
class	`AuroraPointGroup`	`AuroraPointGroup(prefix: str, count: int)`	批量更新一组地图点位。
class	`AuroraAudioGroup`	`AuroraAudioGroup(band_count: int=...)`	读取实时音频频段数据，用于音频可视化。
class	`AuroraMap`	`AuroraMap(node_id: str, lat: float=..., lon: float=..., span: float=...)`	更新地图中心、缩放范围和大量标记点。
class	`AuroraNavigator`	`AuroraNavigator(node_id: str=...)`	控制轻量页面跳转。

#失败路径

情况	应该怎么处理
高频更新仍卡顿	减少每次更新的字段数量，批量提交相关变化。
状态不同步	确认 UI 展示只读取同一份状态，不混用临时副本。
页面结构变化频繁	结构变化交给普通 AppUI 重建，实时工具只处理已有控件的属性变化。
调试困难	先降到普通 `State` 写法，确认逻辑正确后再接入实时更新。

#使用规则

首屏结构仍用 appui 构建，Aurora 只负责高频值。
批量写入用 frame_batch。
普通低频表单不要过早使用 Aurora。