NiceGUI 中文网

外观

超链接 Link ​

创建超链接。

要跳转到页面内的特定位置，你可以使用 ui.link_target("name") 方法放置锚点，然后使用 ui.link(target="#name") 方法。

参数 Param说明 Description
text显示的文本
targetpage 函数，同一页面上的 NiceGUI 元素或字符串，该字符串是一个绝对 URL 或相对于根 URL 的相对路径
new_tab在新标签页中打开 (默认值: False)
python
from nicegui import ui

ui.link('Github 上的 NiceGUI', 'https://github.com/zauberzeug/nicegui')

ui.run()

跳转到其他元素 ​

需要让其他元素呈现在屏幕上，你可以使用 ui.link_target('target_name') 来放置锚点或者直接跳转到元素。

python
from nicegui import ui

navigation = ui.row()
ui.link_target('target_A')
ui.label(
    '我是元素A'
)
label_B = ui.label(
    '我是元素B'
)
with navigation:
    ui.link('点我跳转到元素A', '#target_A')
    ui.link('点我跳转到元素B', label_B)

ui.run()

导航到其他页面 ​

你可以传入页面名或者函数名来执行页面跳转。

python
from nicegui import ui

@ui.page('/some_other_page')
def my_page():
    ui.label('This is another page')

ui.label('Go to other page')
ui.link('... with path', '/some_other_page')
ui.link('... with function reference', my_page)

ui.run()

从图片或其他元素引用链接 ​

python
from nicegui import ui

with ui.link(target='https://github.com/Yuerchu/NiceGUI-Docs'):
    ui.image('https://picsum.photos/id/41/640/360').classes('w-64')

ui.run()

特性 ​

属性 ​

  • classes: Classes[Self]
    • 元素的 Classes 。
  • client: Client
    • The client this element belongs to.
  • html_id: str ^2.16.0
    • 在 HTML DOM 中的元素 ID。
  • is_deleted: bool
    • 元素是否被删除。
  • is_ignoring_events: bool
    • 返回元素当前是否忽略事件。
  • props: Props[self]
    • 元素的 Props 。
  • style: Style[self]
    • 元素的 Style 。
  • text: BindableProperty
  • visiable: BindableProperty

方法 ​

add_dynamic_resource(name: str, function: Callable) -> None ​

向元素添加一个动态资源，该资源返回函数执行的结果。

参数 Param说明 Description
name资源名
function返回资源响应的函数

add_resource(path: Union[str, Path]) -> None ​

向元素中添加一个资源。

参数 Param说明 Description
path资源路径(例如CSS和Javascript文件的路径)

add_slot(name: str, template: Optional[str] = None) -> Slot ​

向元素中添加一个插槽。

NiceGUI使用了来自Vue的 插槽 的概念：元素可以有多个插槽，而每个插槽中又可以有若干个子元素。大多数元素只有一个插槽，比如说基于QCard的 ui.card 等等只有一个默认的插槽。但也不乏有一些复杂的元素，例如基于QTable的 ui.table 就有多个插槽，比如 header 和 body 等等。如果你使用 ui.row() 或 ui.column() 等语句来嵌套元素，那么该元素将会被加入默认的插槽；但如果你使用 table.add_slot() ，则可以添加到不同的插槽中。

插槽堆栈帮助NiceGUI追踪当前用于新元素的插槽。父字段持有对其元素的引用。每当通过 with 表达式进入一个元素时，其默认插槽也会自动进入。

参数 Param说明 Description
name插槽名
template插槽的 Vue 模板
返回 return此插槽

ancestors(include_self: bool = False) -> Iterator[Element] ​

遍历该元素的父元素。

参数 Param说明 Description
include_self是否在迭代中保留本身

bind_text(target_object: Any, target_name: str = 'text', forward: Callable[..., Any] = [...], backward: Callable[..., Any] = [...]) -> Self ​

将此元素的文本绑定到目标对象的 target_name 属性。

绑定是双向的，也就是说既会从此元素到目标对象，也会从目标对象到此元素。更新会立即执行，并在值变化时随时进行。初始同步时，反向绑定具有优先权。

参数 Param说明 Description
target_object需要绑定的目标
target_name绑定目标上的参数名
forward在绑定之前需要执行的方法
backward在绑定之后需要执行的方法

bind_text_from(target_object: Any, target_name: str = 'text', backward: Callable[..., Any] = [...]) -> Self ​

将此元素的文本与目标对象的 target_name 属性绑定。

绑定是双向的，也就是说既会从此元素到目标对象，也会从目标对象到此元素。更新会立即执行，并在值变化时随时进行。初始同步时，反向绑定具有优先权。

参数 Param说明 Description
target_object需要绑定的目标
target_name绑定目标上的参数名
backward在绑定之后需要执行的方法

bind_text_to(target_object: Any, target_name: str = 'text', forward: Callable[..., Any] = [...]) -> Self ​

将此元素的文本绑定到目标对象的 target_name 属性。

绑定是双向的，也就是说既会从此元素到目标对象，也会从目标对象到此元素。更新会立即执行，并在值变化时随时进行。初始同步时，反向绑定具有优先权。

参数 Param说明 Description
target_object需要绑定的目标
target_name绑定目标上的参数名
forward在绑定之前需要执行的方法

bind_visibility(target_object: Any, target_name: str = 'visible', forward: Callable[..., Any] = [...], backward: Callable[..., Any] = [...], value: Any = None) -> Self ​

将此元素的可见性绑定到目标对象的 target_name 属性。

绑定是双向的，也就是说既会从此元素到目标对象，也会从目标对象到此元素。更新会立即执行，并在值变化时随时进行。初始同步时，反向绑定具有优先权。

参数 Param说明 Description
target_object需要绑定的目标
target_name绑定目标上的参数名
forward在绑定之前需要执行的方法
backward在绑定之后需要执行的方法
value如果此项不缺省，该元素当且仅当等于该值时显示

bind_visibility_from(target_object: Any, target_name: str = 'visible', backward: Callable[..., Any] = [...], value: Any = None) -> Self ​

将此元素的可见性与目标对象的 target_name 属性绑定。

绑定是双向的，也就是说既会从此元素到目标对象，也会从目标对象到此元素。更新会立即执行，并在值变化时随时进行。初始同步时，反向绑定具有优先权。

参数 Param说明 Description
target_object需要绑定的目标
target_name绑定目标上的参数名
backward在绑定之后需要执行的方法
value如果此项不缺省，该元素当且仅当等于该值时显示

bind_visibility_to(target_object: Any, target_name: str = 'visible', forward: Callable[..., Any] = [...]) -> Self ​

将此元素的可见性绑定到目标对象的 target_name 属性。

绑定是双向的，也就是说既会从此元素到目标对象，也会从目标对象到此元素。更新会立即执行，并在值变化时随时进行。初始同步时，反向绑定具有优先权。

参数 Param说明 Description
target_object需要绑定的目标
target_name绑定目标上的参数名
forward在绑定之前需要执行的方法

clear() -> None ​

清除所有子元素。

default_classes(add: Optional[str] = None, remove: Optional[str] = None, toggle: Optional[str] = None, replace: Optional[str] = None) -> type[Self] ​

应用、移除、切换或替换默认的 HTML 类。

这允许使用 Tailwind 或 Quasar 类来修改元素的外观或布局。

如果不需要预定义的类，移除或替换类会很有帮助。该类的所有元素将共享这些 HTML 类。这些类必须在元素实例化之前定义。

参数 Param说明 Description
add以空格分隔的待添加类名
remove以空格分隔的待移除类名
toggle以空格分隔的待切换类名(在 v2.7.0 中新增)
replace以空格分隔的用于替换现有类的类名

default_props(add: Optional[str] = None, remove: Optional[str] = None) -> type[Self] ​

应用、移除、切换或替换默认的 Quasar Props。

这允许使用 Quasar 属性来修改元素的外观或布局。由于属性会作为 HTML 属性直接应用，因此它们可以与任何 HTML 元素一起使用。该类的所有元素都将共享这些属性。这些属性必须在元素实例化之前定义。

bool 属性如果没有指定值则默认为 True。

参数 Param说明 Description
add以空格分隔或 键=值 对列表的待添加属性
remove以空格分隔的待移除属性

default_style(add: Optional[str] = None, remove: Optional[str] = None, replace: Optional[str] = None) -> type[Self] ​

应用、移除或替换默认的 CSS 定义。

若不需要预定义样式，移除或替换样式会很有帮助。该类的所有元素将共享这些CSS定义。这些定义必须在元素实例化之前完成。

参数 Param说明 Description
add要添加到元素的样式列表
remove要从元素中移除的样式列表
replace用于替代现有样式的样式列表

delete() -> None ​

删除此元素及其所有子元素。

descendants(include_self: bool = False) -> Iterator[Element] ​

遍历该元素的子元素。

参数 Param说明 Description
include_self是否在迭代中保留本身

get_computed_prop(prop_name: str, timeout: float = 1) -> AwaitableResponse ​

返回一个计算属性。

该函数应该被等待(await)，以便正确返回计算属性。

参数 Param说明 Description
prop_name计算属性的名称
timeout等待响应的最长时间 (默认值: 1秒)

mark(*markers: str) -> Self ​

替换元素的标记。

标记用于通过 ElementFilter 识别元素进行查询。

该功能在测试中被大量使用，但也可用于减少全局变量的数量或传递依赖项。

参数 Param说明 Description
markers字符串列表或使用空格分隔的单个字符串；替换现有标记

move(target_container: Optional[Element] = None, target_index: int = -1, target_slot: Optional[str] = None) -> None ​

将元素移动到另一个容器。

参数 Param说明 Description
target_container要移动元素到的容器 (默认值: 父容器)
target_index目标槽中的索引 (默认值: 追加到末尾)
target_slot目标容器中的槽位 (默认值: 默认槽位)

on(type: str, handler: Optional[events.Handler[events.GenericEventArguments]] = None, args: Union[None, Sequence[str], Sequence[Optional[Sequence[str]]]] = None, throttle: float = 0.0, leading_events: bool = True, trailing_events: bool = True, js_handler: Optional[str] = None) -> Self ​

订阅事件。

参数 Param说明 Description
type事件名称(例如 "click"、"mousedown" 或 "update:model-value")
handler事件发生时触发的回调函数
args包含在传递给事件处理器的事件消息中的参数(默认值: None 表示全部)
throttle事件发生之间的最小时间间隔(单位：秒，默认值: 0.0)
leading_events是否在第一个事件发生时立即触发事件处理器(默认值: True)
trailing_events是否在最后一次事件发生后触发事件处理器(默认值: True)
js_handler事件发生时执行的 JavaScript 代码，例如 (evt) => alert(evt) (默认值: None)

remove(element: Union[Element, int]) -> None ​

移除子元素。

参数 Param说明 Description
element可以是元素实例或其ID

run_method(name: str, *args: Any, timeout: float = 1) -> AwaitableResponse ​

在客户端运行一个方法。

如果该函数被等待，则返回方法调用的结果。

否则，该方法将被执行，且不等待响应。

参数 Param说明 Description
name方法名称
args传递给方法的参数
timeout等待响应的最长时间 (默认值: 1秒)

set_text(text: str) -> None ​

设置元素的文本。

参数 Param说明 Description
text新的文本

set_visibility(visible: bool) -> None ​

设置元素的可见性。

参数 Param说明 Description
visible此元素是否可见

tooltip(text: str) -> Self ​

向元素中添加提示。

参数 Param说明 Description
text提示的文本

update() -> None ​

在客户端更新此元素。

遗产 ​

  • TextElement
  • Element
  • Visibility

内容同步至 NiceGUI 3.17.1 · 更新日期: 2026 年 9 月 29 日