native_views — 原生视图节点与 Facade

原生渲染视图的类型化节点（NativeViewNode）与 RendererView 门面。

原生视图由 self.views.outline(...)、self.views.tree(...) 等类型化入口创建。传输层仍是字典，但插件作者操作的是命名对象与视图门面，role、parentId、补丁修订等渲染协议细节被封装在 SDK 内部。

基础节点

NativeViewNode(dict)

所有类型化渲染数据的基类，可直接序列化为线缆节点。

属性	类型	说明
`id`	`str`	节点 ID
`parent_id`	`Optional[str]`	父节点 ID
`label`	`str`	节点标签
`icon`	`Optional[str]`	图标名
`icon_color`	`Optional[str]`	图标颜色
`has_children`	`bool`	是否有子节点
`children_state`	`Optional[str]`	子节点加载状态
`role`	`Optional[str]`	渲染协议角色

ChildrenState 枚举

unloaded、loading、loaded、error。

IconColor 枚举

primary、secondary、tertiary、muted、error。

icon 参数必须使用 pyrite_sdk.api.icons.Icons（MaterialIcon），传入普通字符串会抛出 TypeError。

类型化节点

类	构造参数	说明
`TreeItem(id, label, parent_id=None, icon=None, has_children=False, children_state=loaded, **metadata)`	—	树节点
`VirtualListItem(id, label, icon=None, **metadata)`	—	虚拟列表项
`TableRowItem(id, cells, **metadata)`	`cells` 为字典	表格行
`TableColumn(id, label, width=None, flex=None, frozen=None, sortable=None)`	—	表格列
`FormField(id, label, value=None, kind="text", options=None)`	—	表单字段
`MarkdownContent(text, id="content")`	—	Markdown 内容
`LogEntry(id, message, level="info", timestamp=None)`	—	日志条目
`OutlineItem(id, label, parent_id=None, icon=None, icon_color=None, has_children=False, children_state=loaded, kind=None, detail=None, line=None, column=None)`	—	大纲项
`VariableEntry(id, name, type_name="", value="", parent_id=None, icon=None, icon_color=None, has_children=False, children_state=loaded)`	—	变量条目
`VariableScope(id, name, error=None, has_children=False)`	—	变量作用域
`LoadMoreEntry(id, parent_id, progress, label="Load more...")`	—	加载更多条目
`ViewPlaceholder(state, label, icon=info_outline, icon_color=None)`	—	空态占位

VariableEntry.update_fields(...)

更新变量条目的显示字段：value、icon、icon_color、children_state。

RendererView 门面

RendererView 是渲染器驱动视图实例的高层门面，公开属性与事件方法如下：

属性/方法	说明
`.model`	底层 `ViewModel`
`.view_id`	视图 ID
`.instance_id`	实例 ID
`.visible`	当前是否可见
`.items`	当前类型化节点列表（副本）
`.nodes`	渲染节点列表（副本）
`open(callback=None)` / `close(callback=None)`	打开/关闭视图
`on_visibility(handler)`	可见性变化回调
`on_select(handler)`	选中回调，handler 接收节点
`on_activate(handler)`	激活回调
`on_request_children(handler)`	请求子节点回调
`on_context_menu(handler)`	行菜单回调，handler 返回一个 `ContextMenu` 组件，SDK 会将其转换为 ContextMenu 组件
`set_actions(actions)`	设置 AppBar 操作
`set_props(**props)`	合并视图配置属性
`set_items(items)`	替换节点，要求类型化 `NativeViewNode`
`show_placeholder(label, state="empty", icon=None, icon_color=None)`	显示空态占位

view = self.views.tree("tree")

def on_select(item):
    print(f"选中: {item.label}")

def menu_for(item):
    return ContextMenu(id=f"menu_{item.id}", items=[
        MenuItem(id="open", label="打开"),
    ], on_select=lambda e: print(e.item_id))

view.on_select(on_select)
view.on_context_menu(menu_for)
view.set_items([
    TreeItem(id="root", label="根节点", has_children=True),
    TreeItem(id="a", label="子节点 A", parent_id="root"),
])
view.open()

视图子类

子类	额外方法
`TreeView`	`configure(expanded_ids=None, selected_id=None, indent=None, searchable=None, empty_label=None)`
`VirtualListView`	`configure(item_count=None, item_height=None, selected_id=None, empty_label=None)`
`TableView`	`set_columns(columns)`；`configure(row_count=None, row_height=None, show_header=None, selected_id=None, sort_column=None, sort_ascending=None, empty_label=None)`
`MarkdownView`	`set_markdown(value)`；`on_link_tap(handler)`
`LogView`	`configure(item_height=None, empty_label=None)`；`append(entry)`；`extend(entries)`；`clear()`

set_columns 要求类型化 TableColumn，LogView.append/extend 要求 LogEntry，set_items 要求 NativeViewNode；传错类型都会抛出 TypeError。

AppBar 操作

类	说明
`ViewAction(id, label, icon, on_trigger)`	AppBar 操作按钮
`ViewMenuAction(id, label, items, icon=more_vert, on_trigger)`	打开声明式原生菜单的 AppBar 操作

view.set_actions([
    ViewAction(id="refresh", label="刷新", icon=Icons.refresh,
               on_trigger=lambda payload: print("刷新")),
    ViewMenuAction(id="more", label="更多", items=[
        {"type": "item", "id": "about", "label": "关于"},
    ], on_trigger=lambda payload: print("菜单触发")),
])

使用示例

树形视图

from pyrite_sdk.api.icons import Icons

view = self.views.tree("file_tree", searchable=True)
view.on_activate(lambda item: print(f"打开: {item.label}"))
view.set_items([
    TreeItem(id="src", label="src", icon=Icons.folder, has_children=True),
    TreeItem(id="main", label="main.py", parent_id="src",
             icon=Icons.description),
])
view.open()

日志视图

log = self.views.log("console", empty_label="暂无输出")
log.append(LogEntry(id="e1", message="连接成功", level="info"))
log.extend([
    LogEntry(id="e2", message="开始编译", level="info"),
    LogEntry(id="e3", message="编译失败", level="error"),
])
log.clear()

native_views — 原生视图节点与 Facade

On this page