Kivy 语言¶

Kivy语言是一种专门用于描述用户界面和交互的语言。你可以将这种语言与Qt的QML（http://qt.nokia.com）相比较，但我们引入了新的概念，如规则定义（这在一定程度上类似于你可能从CSS中了解的内容）、模板等。

在 1.7.0 版本发生变更: Builder 不再实时执行画布表达式。它会先打包所有需要执行的表达式，并在分发输入之后、绘制帧之前统一执行。如果你想要强制画布绘制执行，只需调用 Builder.sync。

同时包含一个用于kv语言的实验性性能分析工具。您可以通过设置环境变量`KIVY_PROFILE_LANG=1`来激活它。激活后，它将生成一个名为`builder_stats.html`的HTML文件。

概述¶

该语言包含几种你可以使用的构造：

好的，请发送需要翻译的英文内容。
规则类似于CSS规则。规则适用于控件树中的特定控件（或其类），并以某种方式修改它们。您可以使用规则来指定交互行为，或使用它们为所应用的控件添加图形表示。您可以通过使用``cls``属性（例如``cls=MyTestWidget``）来针对特定类别的控件（类似于CSS中的*类*概念）。

根部件
你可以使用该语言来创建整个用户界面。一个kv文件最多只能包含一个根部件。

动态类
(自1.7.0版本引入) 动态类允许您即时创建新的控件和规则，无需任何Python声明。

模板（已弃用）
(自1.0.5版本引入，自1.7.0版本弃用) 模板曾用于填充应用程序的各个部分，例如样式化列表内容（如左侧图标，右侧文本）。现在它们已被动态类所取代。

kv 文件的语法¶

Kivy 语言文件的扩展名必须是 .kv。

文件内容应始终以Kivy头部开始，其中`version`必须替换为你正在使用的Kivy语言版本。目前，请使用1.0：：

#:kivy `1.0`

# content here

content 可以包含规则定义、根部件、动态类定义和模板：

# Syntax of a rule definition. Note that several Rules can share the same
# definition (as in CSS). Note the braces: they are part of the definition.
<Rule1,Rule2>:
    # .. definitions ..

<Rule3>:
    # .. definitions ..

# Syntax for creating a root widget
RootClassName:
    # .. definitions ..

# Syntax for creating a dynamic class
<NewWidget@BaseClass>:
    # .. definitions ..

# Syntax for creating a template
[TemplateName@BaseClass1,BaseClass2]:
    # .. definitions ..

无论您定义的是规则、根部件、动态类还是模板，其定义格式都应如下所示：：

# With the braces it's a rule. Without them, it's a root widget.
<ClassName>:
    prop1: value1
    prop2: value2

    canvas:
        CanvasInstruction1:
            canvasprop1: value1
        CanvasInstruction2:
            canvasprop2: value2

    AnotherClass:
        prop3: value1

在这里，prop1 和 prop2 是 ClassName 的属性，而 prop3 是 AnotherClass 的属性。如果控件没有给定名称的属性，则会自动创建一个 ObjectProperty 并添加到该控件中。

AnotherClass 将被创建并作为 ClassName 实例的子项添加。

缩进非常重要，必须保持一致。缩进间距必须是首个缩进行所用空格数的倍数。建议使用空格：不推荐混用制表符和空格。
属性的值必须写在同一行内（至少目前是这样）。
保持类名首字母大写，以避免语法错误。
canvas 属性是特殊的：你可以在其中放置图形指令，以创建当前类的图形表示。

以下是一个包含根控件的kv文件的简单示例：

#:kivy 1.0

Button:
    text: 'Hello world'

在 1.7.0 版本发生变更: 缩进不再仅限于4个空格。间距必须是首个缩进行所用空格数的倍数。

: load_file() 和 load_string() 方法都会返回你在 kv 文件/字符串中定义的根部件。它们还会将任何类和模板定义添加到 Factory 中，以供后续使用。

值表达式、on_property 表达式、ids 以及保留关键字¶

当你指定一个属性的值时，该值会被当作Python表达式来求值。这个表达式可以是静态的或动态的，这意味着该值可以使用保留关键字来引用其他属性的值。

自我
关键字 self 引用“当前控件实例”：
Button:
    text: 'My state is %s' % self.state
根
此关键字仅在规则定义中可用，代表规则的根部件（规则的第一个实例）：
<MyWidget>:
    custom: 'Hello world'
    Button:
        text: root.custom
应用程序
这个关键字始终指向你的应用实例。它等同于在Python中调用:meth:kivy.app.App.get_running_app。:
Label:
    text: app.name
args
此关键字在 on_<action> 回调中可用。它指的是传递给回调的参数。
TextInput:
    on_focus: self.insert_text("Focus" if args[1] else "No focus")

在 2.1.0 版本发生变更: f-字符串现在在值表达式中被解析，允许绑定到它们所包含的属性。

ids¶

类定义中可以包含id，这些id可以用作关键字：:

<MyWidget>:
    Button:
        id: btn1
    Button:
        text: 'The state of the other button is %s' % btn1.state

请注意，id 在控件实例中不可用：它仅用于外部引用。id 是对控件的弱引用，而非控件本身。控件本身可以通过 <id>.__self__ 访问（在此例中为 btn1.__self__）。

当kv文件被处理时，所有带有id标签的widget的弱引用会被添加到根widget的`ids`字典中。换句话说，接续上述示例，按钮的状态也可以通过以下方式访问：

widget = MyWidget()
state = widget.ids["btn1"].state

# Or, as an alternative syntax,
state = widget.ids.btn1.state

请注意，最外层的控件会先对其所有内部控件应用kv规则，然后才应用其他任何规则。这意味着，如果内部控件包含ids，这些ids在内部控件的`__init__`函数执行期间可能尚不可用。

有效表达式¶

在kv文件中，有两处可以接受Python语句：一处是在属性之后，将表达式的结果赋给该属性（如上文所示按钮的文本）；另一处是在on_property之后，当属性更新时执行该语句（如on_state）。

在前一种情况下，表达式只能占据单行，不能通过换行转义扩展到多行，并且必须返回一个值。一个有效表达式的例子是 text: self.state and ('up' if self.state == 'normal' else 'down')。

在后一种情况下，多个单行语句是有效的，包括那些转义换行的语句，只要它们不增加缩进级别即可。

有效语句的示例包括：

on_press: if self.state == 'normal': print('normal')
on_state:
    if self.state == 'normal': print('normal')
    else: print('down')
    if self.state == 'normal': \
    print('multiline normal')
    for i in range(10): print(i)
    print([1,2,3,4,
    5,6,7])

无效语句的示例：

on_state:
    if self.state == 'normal':
        print('normal')

值与属性之间的关系¶

使用Kivy语言时，您可能会注意到我们在幕后进行了一些工作，以确保一切自动正常运行。您应当了解，属性实现了观察者设计模式。这意味着您可以绑定自己的函数，在属性值发生变化时被调用（即，您被动地“观察”属性以获取潜在的变化）。

Kivy 语言会检测您的 value 表达式中的属性，并在发生变化时通过您的表达式自动创建回调以更新该属性。

以下是一个简单的示例，演示了这一行为：：

Button:
    text: str(self.state)

在此示例中，解析器检测到 self.state 是一个动态值（属性）。按钮的 state 属性可以在任何时候（当用户触摸它时）发生变化。我们现在希望这个按钮能够将其自身状态显示为文本，即使状态发生变化也是如此。为此，我们使用 Button 的 state 属性，并将其用于按钮的 text 属性的值表达式中，该属性控制按钮上显示的文本（我们还将状态转换为字符串表示形式）。现在，每当按钮状态改变时，文本属性将自动更新。

请记住：该值是一个Python表达式！这意味着你可以做一些更有趣的事情，比如:

Button:
    text: 'Plop world' if self.state == 'normal' else 'Release me!'

按钮文本会随按钮状态而变化。默认情况下，按钮文本为“Plop world”，但当按钮被按下时，文本将变为“Release me!”。

更精确地说，kivy 语言解析器会检测所有形如 X.a.b 的子字符串，其中 X 是 self、root、app 或已知的 id，而 a 和 b 是属性：然后它会添加相应的依赖关系，以便在有任何变化时重新评估该约束。例如，以下代码完全按预期工作:

<IndexedExample>:
    beta: self.a.b[self.c.d]

然而，由于解析器的限制（希望未来能够解除），以下内容无法正常工作：

<BadExample>:
    beta: self.a.b[self.c.d].e.f

确实，.e.f 部分未被识别，因为它不符合预期的模式，因此不会建立适当的依赖关系。相反，应引入一个中间属性以允许以下约束：

<GoodExample>:
    alpha: self.a.b[self.c.d]
    beta: self.alpha.e.f

此外，Python f-字符串中的属性也尚未得到支持：：

<FStringExample>:
    text: f"I want to use {self.a} in property"

相反，应使用 format() 方法:

<FormatStringExample>:
    text: "I want to use {} in property".format(self.a)

图形指令¶

图形指令是Kivy语言中的一个特殊部分。它们由'canvas'属性定义来处理:

Widget:
    canvas:
        Color:
            rgb: (1, 1, 1)
        Rectangle:
            size: self.size
            pos: self.pos

canvas 属性内添加的所有类必须继承自 Instruction 类。你不能在 canvas 属性中放置任何 Widget 类（因为这样做没有意义，因为 widget 不是图形指令）。

如果你想要进行主题定制，你可能会遇到与CSS中相同的问题：哪些规则先被执行？在我们的情况下，规则按照处理顺序（即自上而下）执行。

如果你想改变按钮的渲染方式，可以创建自己的kv文件，并添加类似这样的内容:

<Button>:
    canvas:
        Color:
            rgb: (1, 0, 0)
        Rectangle:
            pos: self.pos
            size: self.size
        Rectangle:
            pos: self.pos
            size: self.texture_size
            texture: self.texture

这将导致按钮具有红色背景，标签位于左下角，同时保留之前的所有规则。您可以使用 Clear 命令清除所有先前的指令：

<Button>:
    canvas:
        Clear
        Color:
            rgb: (1, 0, 0)
        Rectangle:
            pos: self.pos
            size: self.size
        Rectangle:
            pos: self.pos
            size: self.texture_size
            texture: self.texture

之后，只有遵循 Clear 命令的规则才会被考虑。

动态类¶

动态类允许你即时创建新的控件，而无需事先进行任何Python声明。动态类的语法与规则相似，但你需要指定想要继承的基类。

语法如下：

# Simple inheritance
<NewWidget@Button>:
    # kv code here ...

# Multiple inheritance
<NewWidget@ButtonBehavior+Label>:
    # kv code here ...

@ 字符用于将你的类名与要继承的类分隔开。对应的 Python 写法原本会是：

# Simple inheritance
class NewWidget(Button):
    pass

# Multiple inheritance
class NewWidget(ButtonBehavior, Label):
    pass

任何新属性，通常在Python代码中添加，应首先声明。如果该属性在动态类中不存在，它将被自动创建为:class:`~kivy.properties.ObjectProperty`（1.8.0之前版本）或作为适当的类型化属性（自1.8.0版本起）。

在 1.8.0 版本发生变更: 如果属性值是一个可以立即求值的表达式（无外部绑定），则该值将用作属性的默认值，并且该值的类型将用于Property类的特化。换句话说：如果你声明`hello: "world"，将会实例化一个新的:class:`~kivy.properties.StringProperty，其默认值为`"world"`。支持列表、元组、字典和字符串。

让我们通过实现一个基本的图片按钮来说明这些动态类的用法。我们可以从Button类派生我们的类，并仅为图片文件名添加一个属性：

<ImageButton@Button>:
    source: None

    Image:
        source: root.source
        pos: root.pos
        size: root.size

# let's use the new classes in another rule:
<MainUI>:
    BoxLayout:
        ImageButton:
            source: 'hello.png'
            on_press: root.do_something()
        ImageButton:
            source: 'world.png'
            on_press: root.do_something_else()

在Python中，你可以按如下方式创建动态类的实例：

from kivy.factory import Factory
button_inst = Factory.ImageButton()

备注

使用动态类时，子类可以在其父类之前声明。然而，这会导致一种不直观的情况，即父类的属性/方法会覆盖子类的。如果你选择这样做，请务必小心。

模板¶

在 1.7.0 版本发生变更: 模板用法现已弃用。请改用动态类。

模板的语法¶

在Kivy中使用模板需要满足两个条件：

用于传递的上下文（在模板内部将作为 ctx 使用）。

模板的kv定义。

模板的语法：

# With only one base class
[ClassName@BaseClass]:
    # .. definitions ..

# With more than one base class
[ClassName@BaseClass1,BaseClass2]:
    # .. definitions ..

例如，对于列表，你需要在左侧创建一个带图像的条目，在右侧创建一个标签。你可以创建一个模板，使该定义更易于使用。因此，我们将创建一个模板，在上下文中使用两个条目：一个图像文件名和一个标题。

[IconItem@BoxLayout]:
    Image:
        source: ctx.image
    Label:
        text: ctx.title

然后在Python中，你可以使用以下方式实例化模板：

from kivy.lang import Builder

# create a template with hello world + an image
# the context values should be passed as kwargs to the Builder.template
# function
icon1 = Builder.template('IconItem', title='Hello world',
    image='myimage.png')

# create a second template with other information
ctx = {'title': 'Another hello world',
       'image': 'myimage2.png'}
icon2 = Builder.template('IconItem', **ctx)
# and use icon1 and icon2 as other widget.

模板示例¶

在大多数情况下，当你在kv语言中创建屏幕时，会使用大量的重新定义。在我们的示例中，我们将创建一个基于BoxLayout的工具栏，并放入几个响应*on_touch_down*事件的:class:`~kivy.uix.image.Image`控件。

<MyToolbar>:
    BoxLayout:
        Image:
            source: 'data/text.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_text()

        Image:
            source: 'data/image.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_image()

        Image:
            source: 'data/video.png'
            size: self.texture_size
            size_hint: None, None
            on_touch_down: self.collide_point(*args[1].pos) and root.create_video()

我们可以看到，size 和 size_hint 属性完全相同。此外，on_touch_down 中的回调和图像也在变化。这些可以作为模板中的可变部分，我们可以将其放入上下文中。让我们尝试为 Image 创建一个模板：

[ToolbarButton@Image]:

    # This is the same as before
    size: self.texture_size
    size_hint: None, None

    # Now, we are using the ctx for the variable part of the template
    source: 'data/%s.png' % ctx.image
    on_touch_down: self.collide_point(*args[1].pos) and ctx.callback()

模板可以直接在MyToolbar规则中使用：

<MyToolbar>:
    BoxLayout:
        ToolbarButton:
            image: 'text'
            callback: root.create_text
        ToolbarButton:
            image: 'image'
            callback: root.create_image
        ToolbarButton:
            image: 'video'
            callback: root.create_video

就这样 :)

模板限制¶

当你正在创建一个上下文时：

除了 "root" 之外，你不能使用其他引用。

<MyRule>:
    Widget:
        id: mywidget
        value: 'bleh'
    Template:
        ctxkey: mywidget.value # << fail, this references the id
        # mywidget

并非所有动态部分都会被理解：

<MyRule>:
    Template:
        ctxkey: 'value 1' if root.prop1 else 'value2' # << even if
        # root.prop1 is a property, if it changes value, ctxkey
        # will not be updated

模板定义还会完全替换任何同名的定义，因此不支持继承。

重新定义部件的样式¶

有时我们希望继承一个控件，以便使用其Python属性，而不采用其.kv文件中定义的样式。例如，我们想继承自Label，但同时希望定义自己的画布指令，而不是自动使用从Label继承的画布指令。通过在.kv样式定义中的类名前加上短横线（-），我们可以实现这一点。

在我的app.py中：

class MyWidget(Label):
    pass

在我的.kv文件中：

<-MyWidget>:
    canvas:
        Color:
            rgb: 1, 1, 1
        Rectangle:
            size: (32, 32)

MyWidget 现在将在其 canvas 中拥有一个 Color 和 Rectangle 指令，而不包含任何从 Label 继承的指令。

重新定义部件的属性样式¶

类似于重新定义样式，有时我们希望继承一个部件，保留其所有KV定义的样式，但针对特定属性应用自定义样式。例如，我们希望继承自 Button，但同时希望设置自己的 state_image，而不是依赖 background_normal 和 background_down 的值。我们可以通过在 .kv 样式定义中的 state_image 属性名前添加一个短横线（-）来实现这一点。

在我的app.py中：

class MyWidget(Button):
    new_background = StringProperty('my_background.png')

在我的.kv文件中：

<MyWidget>:
    -state_image: self.new_background

MyWidget 现在将仅通过 new_background 设置 state_image 背景，而不会受到之前可能设置过 state_image 的任何样式影响。

备注

尽管之前的规则已被清除，但在控件构造期间它们仍然会被应用，并且只有在遇到带有破折号的新规则时才会被移除。这意味着最初，之前的规则可能被用来设置该属性。

kwargs 和 KV 规则应用的顺序¶

属性既可以在KV中初始化，也可以在Python中初始化。例如，在KV中：

<MyRule@Widget>:
    text: 'Hello'
    ramp: 45.
    order: self.x + 10

那么 MyRule() 会将这三个 kivy 属性初始化为给定的 KV 值。在 Python 中单独操作时，如果这些属性已经作为 kivy 属性存在，可以例如使用 MyRule(line='Bye', side=55) 进行初始化。

然而，当执行 MyRule(text='Bye', order=55) 时，这些属性的最终值会是什么呢？快速规则是：对于常量规则，Python 初始化比 KV 初始化更具优先级。

具体来说，传递给Python初始化器的`kwargs`总是首先被应用。因此，在上述示例中，text`被设置为'Bye'，`order`被设置为`55。然后，所有KV规则都会被应用，除了那些覆盖了Python初始化器提供值的常量规则。

也就是说，对于不会创建绑定的KV规则，如 text: 'Hello' 和 ramp: 45.，如果在Python中已经为该属性提供了值，那么该规则将不会被应用。

所以在 MyRule(text='Bye', order=55) 这个例子中，text 将是 'Bye'，ramp 将是 45.，而 order`（它会创建一个绑定）首先会被设置为 `55，但随后当 KV 规则被应用时，最终会变成 self.x + 10 的值。

在 1.9.1 版本发生变更: 此前，KV规则总是覆盖Python中的值，而现在，常量规则不再覆盖Python中的值。

语言指令¶

您可以使用指令（directives）向lang文件中添加声明式命令，例如导入或常量定义。指令以注释形式添加，格式如下：

#:<directivename> <options>

导入<包>¶

在 1.0.5 版本加入.

语法：

#:import <alias> <package>

你可以通过编写以下代码来导入一个包：

#:import os os

<Rule>:
    Button:
        text: os.getcwd()

或者更复杂的情况：

#:import ut kivy.utils

<Rule>:
    canvas:
        Color:
            rgba: ut.get_random_color()

在 1.0.7 版本加入.

你可以直接从模块中导入类：

#: import Animation kivy.animation.Animation
<Rule>:
    on_prop: Animation(x=.5).start(self)

set <key> <expr>¶

在 1.0.6 版本加入.

语法：

#:set <key> <expr>

在kv中设置一个键，使其在任何地方都可用。例如：

#:set my_color (.4, .3, .4)
#:set my_color_hl (.5, .4, .5)

<Rule>:
    state: 'normal'
    canvas:
        Color:
            rgb: my_color if self.state == 'normal' else my_color_hl

请提供需要翻译的英文内容。¶

在 1.9.0 版本加入.

语法：

#:include [force] <file>

包含一个外部kivy文件。这允许你将复杂的部件拆分到它们自己的文件中。如果强制包含，该文件将首先被卸载，然后再次重新加载。例如：

# Test.kv
#:include mycomponent.kv
#:include force mybutton.kv

<Rule>:
    state: 'normal'
    MyButton:
    MyComponent:

# mycomponent.kv
#:include mybutton.kv

<MyComponent>:
    MyButton:

# mybutton.kv

<MyButton>:
    canvas:
        Color:
            rgb: (1.0, 0.0, 0.0)
        Rectangle:
            pos: self.pos
            size: (self.size[0]/4, self.size[1]/4)

class kivy.lang.BuilderBase[源代码]¶

基类：object

Builder 负责创建一个 Parser 来解析 kv 文件，并将解析结果合并到其内部规则、模板等中。

默认情况下，Builder 是 Kivy 中用于小部件的全局实例，除了默认的 kv 文件外，您还可以使用它来加载其他 kv 文件。

apply(widget, ignored_consts={}, rule_children=None, dispatch_kv_post=False)[源代码]¶

搜索所有匹配该控件的规则并应用它们。

参数:

widget：Widget

应将该类的规则应用于此widget的widget。

ignored_consts：集合

一个集合或列表类型，其元素为属性名，对于这些属性，该部件的常量KV规则（即不创建绑定的规则）将不会被应用。这允许例如跳过那些会覆盖在Python中初始化的值的常量规则。

rule_children：列表

如果不是 None，它应当是一个列表，该列表将被填充为所有由正在应用的 kv 规则所创建的控件。

在 1.11.0 版本发生变更.

dispatch_kv_post: bool

通常，Widget 类会在应用 kv 规则时，向创建的小部件分发 on_kv_post 事件。但如果通过调用 apply() 手动应用规则，则可能不会发生这种情况。因此，如果此值为 True，我们将在将规则应用于 widget 后，在需要的地方分发 on_kv_post 事件（但不会为 widget 本身分发该事件）。

默认为 False。

在 1.11.0 版本发生变更.

apply_rules(widget, rule_name, ignored_consts={}, rule_children=None, dispatch_kv_post=False)[源代码]¶

搜索所有匹配名称 rule_name 的规则，并将它们应用到 widget 上。

在 1.10.0 版本加入.

参数:

widget：Widget

匹配规则应应用于的控件。

ignored_consts：集合

一个集合或列表类型，其元素为属性名，对于这些属性，该部件的常量KV规则（即不创建绑定的规则）将不会被应用。这允许例如跳过那些会覆盖在Python中初始化的值的常量规则。

rule_children：列表

如果不是 None，它应当是一个列表，该列表将被填充为所有由正在应用的 kv 规则所创建的控件。

在 1.11.0 版本发生变更.

dispatch_kv_post: bool

通常，Widget 类会在应用 kv 规则时，向创建的小部件分发 on_kv_post 事件。但如果通过调用 apply() 手动应用规则，则可能不会发生这种情况。因此，如果此值为 True，我们将在将规则应用于 widget 后，在需要的地方分发 on_kv_post 事件（但不会为 widget 本身分发该事件）。

默认为 False。

在 1.11.0 版本发生变更.

classmethod create_from(builder)[源代码]¶

创建该类的一个实例，并初始化为``builder``所指定的状态。

参数:: builder -- 用于初始化的构建器。
返回:: 该类的一个新实例。

load_file(filename, encoding='utf8', **kwargs)[源代码]¶

将文件插入语言构建器中，并返回该kv文件的根组件（如果已定义）。

参数:

rulesonly：布尔值，默认为 False: 如果为 True，当定义中包含根控件时，Builder 将抛出异常。

encoding：文件字符编码。默认为 utf-8。

load_string(string, **kwargs)[源代码]¶

将字符串插入到语言构建器中，并返回该kv字符串的根部件（如果已定义）。

参数:

rulesonly：布尔值，默认为 False: 如果为 True，当定义中包含根控件时，Builder 将抛出异常。
filename：字符串，默认为 None: 如果指定，则使用该文件名来索引 kv 规则。

filename 参数可用于卸载 kv 字符串，方式与卸载 kv 文件相同。这可以通过使用伪文件名来实现，例如:

Build.load_string("""
    <MyRule>:
        Label:
            text="Hello"
""", filename="myrule.kv")

可以通过以下方式卸载:

Build.unload_file("myrule.kv")

match(widget)[源代码]¶: 返回与控件匹配的 ParserRule 对象列表。

match_rule_name(rule_name)[源代码]¶: 返回与控件匹配的 ParserRule 对象列表。

sync()[源代码]¶: 执行所有等待中的操作，例如执行所有与画布相关的表达式。

在 1.7.0 版本加入.

template(*args, **ctx)[源代码]¶

使用特定上下文创建专用模板。

在 1.0.5 版本加入.

使用模板，你可以通过为自定义控件提供上下文，从kv语言定义中构建它们。请参阅模板使用。

unbind_property(widget, name)[源代码]¶

解除由该组件中所有设置了该名称的规则所创建的事件处理器绑定。

这有效地清除了所有符合以下形式的widget规则:

name: rule

例如：

>>> w = Builder.load_string('''
... Widget:
...     height: self.width / 2. if self.disabled else self.width
...     x: self.y + 50
... ''')
>>> w.size
[100, 100]
>>> w.pos
[50, 0]
>>> w.width = 500
>>> w.size
[500, 500]
>>> Builder.unbind_property(w, 'height')
>>> w.width = 222
>>> w.size
[222, 500]
>>> w.y = 500
>>> w.pos
[550, 500]

在 1.9.1 版本加入.

unbind_widget(uid)[源代码]¶

解除由KV规则创建的所有处理器绑定。此处传入的是 kivy.uix.widget.Widget.uid 而非部件本身，因为Builder在部件析构函数中使用它。

这将有效清除与该部件关联的所有KV规则。例如：

>>> w = Builder.load_string('''
... Widget:
...     height: self.width / 2. if self.disabled else self.width
...     x: self.y + 50
... ''')
>>> w.size
[100, 100]
>>> w.pos
[50, 0]
>>> w.width = 500
>>> w.size
[500, 500]
>>> Builder.unbind_widget(w.uid)
>>> w.width = 222
>>> w.y = 500
>>> w.size
[222, 500]
>>> w.pos
[50, 500]

在 1.7.2 版本加入.

unload_file(filename)[源代码]¶: 卸载所有与先前导入文件关联的规则。

在 1.0.8 版本加入.

警告

这不会移除当前部件上已应用/使用的规则或模板。它只会影响下一个部件的创建或模板调用。

exception kivy.lang.BuilderException(context, line, message, cause=None)[源代码]¶

基类：ParserException

当Builder无法在控件上应用规则时引发的异常。

class kivy.lang.Observable¶

基类：ObjectWithUid

Observable 是一个定义绑定所需方法的桩类。EventDispatcher 是实现绑定接口的类的一个示例。详见 EventDispatcher。

在 1.9.0 版本加入.

bind(self, **kwargs)¶

fbind(self, name, func, *largs, **kwargs)¶: 参见 EventDispatcher.fbind()。

备注

为了保持与之前可能继承自 Observable 的派生类的向后兼容性，添加了 fbind() 方法。fbind() 的默认实现是创建一个部分函数，并将其传递给 bind，同时保存 uid 和 largs/kwargs。然而，funbind`（以及 :meth:`unbind_uid()）的效率相对较低，因为我们必须首先使用 largs/kwargs 或 uid 查找这个部分函数，然后对返回的函数调用 unbind()。建议在派生类中重写这些方法，直接进行绑定以获得更好的性能。

与 EventDispatcher.fbind() 类似，此方法在失败时返回 0，在成功时返回一个正数的唯一 uid。该 uid 可用于 unbind_uid()。

funbind(self, name, func, *largs, **kwargs)¶: 参见 fbind() 和 EventDispatcher.funbind()。

unbind(self, **kwargs)¶

unbind_uid(self, name, uid)¶: 参见 fbind() 和 EventDispatcher.unbind_uid()。

class kivy.lang.Parser(**kwargs)[源代码]¶

基类：object

创建一个Parser对象来解析Kivy语言文件或Kivy内容。

parse(content)[源代码]¶: 解析Parser文件的内容，并返回根对象列表。

parse_level(level, lines, spaces=0)[源代码]¶: 解析当前层级（层级 * 空格）的缩进。

strip_comments(lines)[源代码]¶: 原地删除所有行中的注释。注释必须独占一行，且不能位于行尾。即，注释行的第一个非空白字符必须是#。

exception kivy.lang.ParserException(context, line, message, cause=None)[源代码]¶

基类：Exception

当kv文件中出现错误时引发的异常。

« 运动事件形状

Builder »

Version

Quick search

目录

Kivy 语言¶

概述¶

kv 文件的语法¶

值表达式、on_property 表达式、ids 以及保留关键字¶

ids¶

有效表达式¶

值与属性之间的关系¶

图形指令¶

动态类¶

模板¶

模板的语法¶

模板示例¶

模板限制¶

重新定义部件的样式¶

重新定义部件的属性样式¶

kwargs 和 KV 规则应用的顺序¶

语言指令¶

导入<包>¶

set <key> <expr>¶

请提供需要翻译的英文内容。¶