Vue.py

外观

本页目录

Textual-vuepy 组件总览 ​

Textual-vuepy 将 Textual 全部内置 Widget 封装为 Vue.py 组件，让你在 .vue SFC 文件中以声明式方式构建终端 TUI 应用。

安装：pip install 'vuepy-core[textual]'

导入：在 create_app 时指定 backend='textual'，vtextual 插件将自动注册所有组件。

布局组件 ​

组件说明常用属性
VBox垂直容器，子组件从上到下排列style, id
HBox水平容器，子组件从左到右排列style, id
SlotVBox 的别名，用于 slot 占位—
Collapsible可折叠容器title, collapsed
TabbedContent标签页容器（配合 TabPane）initial
TabPane标签页内容区域title, id
ContentSwitcher根据 ID 切换显示内容initial
vue
<template>
  <VBox style="height: 1fr;">
    <HBox id="toolbar">
      <Button label="Action" @click="on_action()" />
    </HBox>
    <VBox id="content" style="height: 1fr;">
      <!-- 内容 -->
    </VBox>
  </VBox>
</template>

基础组件 ​

组件v-model 默认绑定说明常用属性
Buttonlabel按钮label, disabled, variant
Labellabel文本标签，支持 Rich markuplabel
Staticrenderable静态文本/Rich 渲染renderable, markup
Linkurl超链接url, label
Placeholder—占位符label
vue
<template>
  <VBox>
    <Label label="[bold green]Hello[/bold green]" />
    <Button label="点击我" variant="primary" @click="on_click()" />
  </VBox>
</template>

表单组件 ​

组件v-model 默认绑定说明常用属性
Inputvalue单行输入框value, placeholder, password, disabled, compact
TextAreatext多行文本编辑器text, language, code_editor
MaskedInputvalue格式化输入框（掩码）template, value
Checkboxvalue复选框label, value, disabled
RadioButtonvalue单选按钮label, value
RadioSetpressed单选按钮组—
Selectvalue下拉选择框options, value, prompt
SelectionListselected多选列表—
Switchvalue开关value, animate
vue
<template>
  <VBox>
    <Input v-model="name.value" placeholder="请输入姓名" />
    <Select v-model="lang.value"
            :options="[('Python', 'py'), ('TypeScript', 'ts')]" />
    <Switch v-model="enabled.value" />
    <Checkbox label="同意条款" v-model="agreed.value" />
  </VBox>
</template>

<script lang="py">
from vuepy import ref

name = ref("")
lang = ref("py")
enabled = ref(True)
agreed = ref(False)
</script>

数据展示 ​

组件v-model 默认绑定说明常用属性
DataTabledata数据表格cols, rows
MarkdownmarkdownMarkdown 渲染markdown
MarkdownViewermarkdownMarkdown 查看器（含目录）markdown, show_table_of_contents
PrettyobjectPython 对象格式化展示object
Sparklinedata迷你折线图data, summary_function
Digitsvalue大号数字显示（类 LCD）value
RichLoglines富文本滚动日志markup, wrap, highlight
Loglines纯文本滚动日志—
vue
<template>
  <VBox style="height: 1fr;">
    <RichLog ref="log_ref" highlight markup style="height: 1fr;" />
    <Button label="写入日志" @click="write_log()" />
  </VBox>
</template>

<script lang="py">
from vuepy import ref, onMounted

log_ref = ref(None)

def write_log():
    log_ref.value.unwrap().write("[bold cyan]事件发生[/bold cyan]")
</script>
组件说明常用属性
Tabs顶部标签页导航active
Tab单个标签（在 Tabs 内使用）label, id
ListView可滚动列表视图initial_index
ListItem列表项（在 ListView 内使用）—
OptionList可选项列表—
Option选项项（在 OptionList 内使用）prompt, id
OptionGroup选项分组name
SelectionList多选列表—
Selection多选项（在 SelectionList 内使用）prompt, value
Tree树形结构label
DirectoryTree目录树path

反馈组件 ​

组件说明常用属性 / 方法
Dialog模态对话框ref 调用 .open() / .close()，或 v-model:value
LoadingIndicator加载动画指示器—
ProgressBar进度条progress, total, show_eta
Tooltip工具提示message
vue
<template>
  <VBox>
    <Button label="打开对话框" @click="dialog_ref.value.unwrap().open()" />
    <Dialog ref="dialog_ref">
      <Label label="这是对话框内容" />
      <template #footer>
        <Button label="关闭" @click="dialog_ref.value.unwrap().close()" />
      </template>
    </Dialog>
    <ProgressBar :progress="progress.value" :total="100" />
  </VBox>
</template>

<script lang="py">
from vuepy import ref

dialog_ref = ref(None)
progress = ref(0)
</script>

结构/布局辅助 ​

组件说明
Header应用顶部标题栏
Footer应用底部状态栏（显示快捷键）
HelpPanel侧边帮助面板
KeyPanel按键面板（显示已注册的快捷键）
Rule水平分隔线
Welcome欢迎页面
Display直接显示已有的 Textual Widget 实例

自定义 SFC 组件 ​

Textual-vuepy 提供两个开箱即用的 SFC 自定义组件（位于 textual_vuepy/components/）：

ShimmerText — 闪光文字 ​

显示带有流光高亮动画的文字（适合 AI 思考状态展示）。

Prop类型默认值说明
textstr"Thinking"显示的文字
highlight_widthint3高亮区域宽度（字符数）
intervalfloat0.1动画帧间隔（秒）
runningboolFalse是否运行动画
vue
<template>
  <ShimmerText text="AI 正在思考..." :running="is_loading.value" />
</template>

<script lang="py">
from vuepy import ref
from vuepy import import_sfc
from pathlib import Path

ShimmerText = import_sfc(Path('textual_vuepy') / 'components' / 'ShimmerText.vue')
is_loading = ref(True)
</script>

Spinner — 加载旋转器 ​

显示带旋转字符动画的加载指示器。

Prop类型默认值说明
textstr"Loading..."旋转符号后的文字
intervalfloat0.1动画帧间隔（秒）
runningboolFalse是否运行动画
stylestr""TCSS 样式字符串

内置应用（VuepyAppStore） ​

安装 textual_vuepy 后自动注册以下应用，可通过 vuepy run <name> 启动：

名称说明
playground交互式 SFC 编辑器 + 实时预览，支持拖拽分隔条、文件热重载、目录树
keys按键事件查看器，显示每次按键的 Key 事件详情
sh
vuepy run playground  # 启动 SFC Playground
vuepy run keys        # 启动按键查看器

VueUse 组合式函数 ​

从 textual_vuepy.vueuse 导入：

函数说明返回值
onKeyStroke(key, cb)注册全局按键监听（在 onMounted 后生效）—
useMouse()追踪鼠标屏幕坐标(x: Ref[int], y: Ref[int])
vue
<script lang="py">
from textual_vuepy.vueuse import onKeyStroke, useMouse

# 全局按键监听
def handle_ctrl_c(event):
    app.tt_app.exit()

onKeyStroke('ctrl+c', handle_ctrl_c)

# 鼠标坐标追踪
mouse_x, mouse_y = useMouse()
</script>

<template>
  <Label :label="f'鼠标位置: ({mouse_x.value}, {mouse_y.value})'" />
</template>

事件处理 ​

Textual-vuepy 支持 Textual 原生事件，通过 @事件名 绑定：

vue
<template>
  <Input @input_submitted="on_submit" />
  <DirectoryTree path="./" @directory_tree_file_selected="on_file_selected" />
  <VBox @mouse_move="on_mouse_move" @mouse_up="on_mouse_up" />
</template>

事件名使用蛇形命名（snake_case），对应 Textual Message 类名转小写，如：

  • Input.Submitted → @input_submitted
  • DirectoryTree.FileSelected → @directory_tree_file_selected
  • Button.Pressed → @click（Button 有简化别名）

深入了解 ​

在 GitHub 上编辑此页