通用属性与回调

Slint 元素有许多通用属性、回调和行为。本页介绍这些属性及其用法。

通用视觉属性

这些属性对所有可视项都有效。例如 Rectangle、Text 和 layouts。非可视项（如 Timer）没有这些属性。

x, y

lengthdefault: 0px

元素相对于其父元素的位置。

z

floatdefault: 0.0

元素在其兄弟元素之间的堆叠顺序。z 值更高的兄弟元素绘制在上层，并且最先接收输入。默认值为 0，共享相同 z 的兄弟元素保持其声明顺序。

width, height

lengthdefault: 0px

元素的宽度和高度。设置后会覆盖默认尺寸。

变换

变换允许围绕指定的原点旋转和缩放项。默认原点是元素的中心。

软件渲染器不支持变换。

Image {
    x: 0;
    y: 0;
    source: @image-url("images/slint-logo.svg");
    transform-rotation: 45deg;
    transform-origin: {x: 0, y: 0};
}

slint

transform-rotation

angledefault: 0deg

transform-origin

struct Pointdefault: {x: self.width / 2, y: self.height / 2}

旋转和缩放所围绕的原点。

默认为元素的中心。

transform-scale

floatdefault: 100%

应用于元素及其所有子元素的缩放因子。

这不会影响元素的几何尺寸（width、height），但会影响渲染。缩放围绕 transform-origin 点进行。

也可以使用 transform-scale-x 和 transform-scale-y 属性来指定 x 轴和 y 轴的缩放因子。

transform-scale-x

floatdefault: self.scale

transform-scale-y

floatdefault: self.scale

opacity

component ImageInfo inherits Rectangle {
    in property <float> img-opacity: 1.0;
    background: transparent;
    VerticalLayout {
        spacing: 5px;
        Image {
            source: @image-url("elements/slint-logo.png");
            opacity: img-opacity;
        }
        Text {
            text: "opacity: " + img-opacity;
            color: white;
            horizontal-alignment: center;
        }
    }
}
export component Example inherits Window {
    width: 100px;
    height: 310px;
    background: transparent;
    Rectangle {
        background: #141414df;
        border-radius: 10px;
    }
    VerticalLayout {
        spacing: 15px;
        padding-top: 10px;
        padding-bottom: 10px;
        ImageInfo {
            img-opacity: 1.0;
        }
        ImageInfo {
            img-opacity: 0.6;
        }
        ImageInfo {
            img-opacity: 0.3;
        }
    }
}

slint

floatdefault: 1

一个介于 0 和 1 之间（或百分比）的值，用于以透明方式绘制元素及其子元素。

0：完全透明（不可见）
1：完全不透明

不透明度应用于子元素树，就如同它们先被绘制到一个中间图层上，然后整个图层以该不透明度进行渲染。

下面的示例演示了带有子元素时的 opacity 属性。

Rectangle {
    width: 100px;
    height: 150px;
    opacity: 50%;
    Rectangle {
        x: 0;
        y: 0;
        width: 100px;
        height: 100px;
        background: blue;
    }

    Rectangle {
        x: 50px;
        y: 50px;
        width: 100px;
        height: 100px;
        background: green;
    }

}

slint

visible

booldefault: true

当设置为 false 时，元素及其所有子元素都不会被绘制，也不会响应鼠标输入。元素仍然占用任何布局容器中的布局空间。

absolute-position

struct Point(out)

在包含许多嵌套组件的 UI 中，了解它们相对于主窗口或屏幕的 (x,y) 位置很有用。这个便捷属性提供了对该值的简单只读访问。它表示一个点，指定其在所属 Window 或 PopupWindow 内的绝对位置。它定义了相对于所属 Window 或 PopupWindow 的坐标 (x,y)，但参考系未指定（可能是屏幕、窗口或弹出窗口坐标）。

杂项

cache-rendering-hint

booldefault: false

当设置为 true 时，这会向渲染器提供提示，将元素及所有子元素的内容缓存到一个中间缓存图层中。对于很少变化的复杂子树，这可能会加快渲染速度，代价是增加内存消耗。

dialog-button-role

enum DialogButtonRoledefault: none

指定这是 Dialog 中的按钮。

通用回调

init()

每个元素都隐式声明一个 init 回调。你可以为元素分配一个代码块，在元素实例化后且所有属性都以其最终绑定的值初始化后调用。调用顺序是从内到外。下面的示例依次打印 “first”、“second”，然后 “third”：

component MyButton inherits Rectangle {
    in-out property <string> text: "Initial";
    init => {
        // If `text` is queried here, it will have the value "Hello".
        debug("first");
    }
}

component MyCheckBox inherits Rectangle {
    init => { debug("second"); }
}

export component MyWindow inherits Window {
    MyButton {
        text: "Hello";
        init => { debug("third"); }
    }
    MyCheckBox {
    }
}

slint

不要使用此回调来初始化属性，因为这会违反声明式原则。

尽管所有组件上都存在 init 回调，但无法从应用程序代码中设置它，例如，生成的代码中不存在 on_init 函数。这是因为该回调在组件创建时就被调用，早于你可以调用 on_init 来实际设置它。

虽然 init 回调可以调用其他回调（例如在 global 段中定义的回调），并且你可以在后端绑定这些回调，但这对于静态创建的组件（包括窗口本身）不起作用，因为你需要一个实例来设置全局绑定。但可以将其用于动态创建的组件（例如 if 后面的组件）：

export global SystemService  {
    // This callback can be implemented in native code using the Slint API
    callback ensure_service_running();
}

component MySystemButton inherits Rectangle {
    init => {
        SystemService.ensure_service_running();
    }
    // ...
}

export component AppWindow inherits Window {
    in property <bool> show-button: false;

    // MySystemButton isn't initialized at first, only when show-button is set to true.
    // At that point, its init callback will call ensure_service_running()
    if show-button : MySystemButton {}
}

slint

无障碍属性

使用以下 accessible- 属性，让你的项与屏幕阅读器、盲文终端以及其他无障碍软件良好交互，使你的应用程序具备无障碍能力。必须先设置 accessible-role，才能设置任何其他无障碍属性或回调。

accessible-role

intdefault: 0

此元素在一组相似元素中的索引（从 0 开始）。适用于列表项、单选按钮和其他元素。

accessible-item-count

intdefault: 0

一组元素的总数。适用于一组元素的父容器，例如列表视图、单选按钮组或其他分组元素。

无障碍回调

你还可以使用以下由无障碍框架调用的回调：

accessible-action-default()

当请求此部件的默认操作时调用，例如按钮的按下操作。

accessible-action-set-value(string)

当用户想要更改无障碍值时调用。

accessible-action-increment()

当用户请求增加值时调用。

accessible-action-decrement()

当用户请求减少值时调用。

accessible-action-expand()

当用户请求展开部件时调用，例如展开组合框的可用选项列表。

accessible-action-set-selection-offsets(anchor: int, focus: int)

当用户想要更改选中的文本时调用。参数是元素文本中的 UTF-8 偏移量：anchor 是保持不动的端点，focus 是移动的端点，因此当选择是反向进行时 focus 可能在 anchor 之前，而当只有光标移动时两者相等。