基础属性和事件

大约 17 分钟

基础属性和事件

基础属性和事件,是每一个Kuikly组件都包含的属性和事件。

基础属性

Kuikly组件的基础属性按照功能可划分为样式属性布局属性

  1. 样式属性: 描述组件样式的属性
  2. 布局属性: 描述组件如何布局的属性

下面我们来看样式属性

backgroundColor方法

背景颜色

参数描述类型
color背景颜色值Color
internal class TestPage : BasePager() {

    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(50f, 50f)
                    backgroundColor(Color.GREEN)
                }
            }
        }
    }
}











 





backgroundLinearGradient方法

设置组件的背景颜色为线性渐变颜色

参数描述类型
direction渐变方向Direction
colorStops渐变颜色配置对象,为可变参数,可指定多个颜色进行渐变。ColorStop.color为渐变颜色,ColorStop.stopIn01颜色终止位置vararg ColorStop

Direction可选值:

enum class Direction(value: Int) {
    TO_TOP(0),
    TO_BOTTOM(1),
    TO_LEFT(2),
    TO_RIGHT(3),
    TO_TOP_LEFT(4),
    TO_TOP_RIGHT(5),
    TO_BOTTOM_LEFT(6),
    TO_BOTTOM_RIGHT(7),
}

注意

渐变颜色终止位置,在Android平台,只有API >= 29才生效

internal class TestPage : BasePager() {

    override fun body(): ViewBuilder {
        return {
            attr {
                backgroundColor(Color.WHITE)
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                    // 从上到下平均渐变
                    backgroundLinearGradient(Direction.TO_BOTTOM,
                        ColorStop(Color.RED, 0f), ColorStop(Color.GREEN, 1f))
                }
            }

            View {
                attr {
                    size(100f, 100f)
                    marginTop(20f)
                    backgroundLinearGradient(Direction.TO_RIGHT,
                        ColorStop(Color.RED, 0f),
                        ColorStop(Color.GREEN, 0.3f), // 绿色渐变到30%后停止
                        ColorStop(Color.BLACK, 1f) // 30% ~ 100%是绿色到黑色渐变
                    )
                }
            }
        }
    }
}













 
 







 
 
 
 






boxShadow方法

为组件设置阴影效果。该方法接收BoxShadow对象作为参数

参数描述类型
offsetX阴影效果相对于组件的X坐标偏移量Float
offsetY阴影效果相对于组件的Y坐标偏移量Float
shadowRadius阴影效果扩散半径Float
shadowColor阴影颜色Color
@Page("demo_page")
internal class TestPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.YELLOW)
                    boxShadow(BoxShadow(0f, 0f, 10f, Color.GREEN))
                }
            }
        }
    }
}












 





borderRadius方法

为组件设置圆角。该方法接收BorderRectRadius对象作为参数

参数描述类型
topLeftCornerRadius左上角圆角半径Float
topRightCornerRadius右上角圆角半径Float
bottomLeftCornerRadius左下角圆角半径Float
bottomRightCornerRadius右下角圆角半径Float

@Page("demo_page")
internal class BorderRadiusPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    borderRadius(BorderRectRadius(20f, 20f, 5f, 20f))
                }
            }
        }
    }
}












 





border方法

为组件设置边框样式。该方法接收Border对象作为参数

参数描述类型
lineWidth边框线宽Float
lineStyle边框线样式。SOLID: 实线样式; DOTTED: 点线样式; DASHED: 虚线样式BorderStyle(枚举)
color边框样色Color
@Page("demo_page")
internal class BorderPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    borderRadius(20f)
                    border(Border(2f, BorderStyle.SOLID, Color.BLACK))
                }
            }
        }
    }
}













 





visibility方法

设置组件是否可见, 所有组件默认可见

@Page("demo_page")
internal class VisibilityPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View { // 默认可见
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    marginBottom(20f)
                }
            }
            
            View { 
                attr { 
                    size(100f, 100f)
                    backgroundColor(Color.RED)
                    visibility(false) // 不可见
                }
            }
        }
    }
}




















 





opacity方法

设置组件的alpha值

@Page("demo_page")
internal class AlphaPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View { // 默认可见
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    marginBottom(20f)
                    opacity(0.5f)
                }
            }
        }
    }
}













 





touchEnable方法

是否允许组件可触摸交互

transform方法

设置组件的缩放scale,旋转rotate,位移translate和transform动作的中心点anchor。transform方法参数对象为:

  • Rotate

设置组件的旋转角度

参数描述类型
angle顺时针旋转角度Float
@Page("demo_page")
internal class RotatePage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View { // 默认可见
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    transform(rotate = Rotate(45f))
                }
            }
        }
    }
}












 





  • Scale

设置组件的缩放系数

参数描述类型
xx轴缩放系数Float
yy轴缩放系数Float
@Page("demo_page")
internal class ScalePage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View { // 默认可见
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    transform(scale = Scale(1.5f, 1.5f))
                }
            }
        }
    }
}












 





  • Translate

设置组件的位移

参数描述类型
percentageX在X轴上, 相对自身宽度位移的百分比. 取值范围[-1, 1]Float
percentageY在Y轴上, 相对自身高度位移百分比,取值范围[-1, 1]Float
@Page("demo_page")
internal class TransformPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View { // 默认可见
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    // 往右移动100f, 往下移动100f
                    transform(translate = Translate(1f, 1f))
                }
            }
        }
    }
}












 
 





  • Anchor

设置组件做Transform时, 中心点的位置

参数描述类型
x在X轴上的中心位置, 相对自身组件的宽度的百分比位置 取值范围[-1, 1]Float
y在Y轴上的中心位置, 相对自身组件高度的百分比位置,取值范围[-1, 1]Float

zIndex方法

设置组件的层级位置。组件的层级是按照书写顺序来叠放的,使用zIndex方法可更改组件的叠放顺序

@Page("demo_page")
internal class ZIndexPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    absolutePosition(100f, 20f)
                    zIndex(1) // 将层级太高, 位置View2之上
                }
            }
            View { // View2
                attr {
                    size(100f, 100f)
                    absolutePosition(120f, 40f)
                    backgroundColor(Color.RED)
                }
            }
        }
    }
}









 












overflow方法

当组件的孩子超出组件的大小时,是否要对子组件超出的区域进行裁剪。在Kuikly中默认子组件大小超出父组件时, 父组件默认不会裁剪, 子组件超出父组件部分能让能够显示

注意

overflow的默认表现在iOS开发者看来是很正常的,因此iOS默认对子View超出父View的区域是不会裁剪的。 但是对于Android开发者来说会有不同,因此Android系统默认会不显示子View超出父View的区域

@Page("demo_page")
internal class OverflowPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                View {
                    attr {
                        size(120f, 50f) // 宽度超出父亲能够显示, 因为overflow默认是false
                        backgroundColor(Color.RED)
                    }
                }
            }

            View {
                attr {
                    marginTop(40f)
                    backgroundColor(Color.BLUE)
                    size(100f, 100f)
                    overflow(true)
                }

                View {
                    attr {
                        size(200f, 50f) // 不能超出父View, 因为父View将overflow设为true
                        backgroundColor(Color.GRAY)
                    }
                }
            }
        }
    }
}















 










 




 







keepAlive方法

设置组件是否常驻。常用于有状态的组件。如果一个组件被设置为true,并且这个组件是可滚动的容器的直接孩子的话(例如List, PageList, SlidePage), 当 组件被滑出屏幕外, 组件不会被可滚动容器移除

animate方法

设置组件的动画参数, 具体效果和写法可以参看动画文档

accessibility方法

无障碍化属性, 当应用处于TalkBack模式时, 元素获取焦点后, 元素会语音读出该值


下面只描述布局相关属性方法的定义, 更详细的描述, 可查看Kuikly的布局教程

width方法

指定组件的宽度

参数描述类型
width设置组件的宽度Float

height方法

设置组件的高度

参数描述类型
height设置组件的高度Float

maxWidth方法

设置组件的最大宽度, 如果组件的宽度未达到最大宽度, 会优先尊重组件的宽度

参数描述类型
maxWidth设置组件的最大宽度Float

maxHeight方法

设置组件的最大高度, 如果组件的高度未达到最大高度, 会优先尊重组件的高度

参数描述类型
maxHeight设置组件的最大高度Float

minWidth

设置组件的最小宽度, 如果组件的宽度未小于最小宽度, 会优先尊重组件的宽度

参数描述类型
minWidth设置组件的最小宽度Float

minHeight

设置组件的最小高度, 如果组件的高度未小于最小高度, 会优先尊重组件的高度

参数描述类型
minHeight设置组件的最小高度Float

margin方法

设置组件相对于父组件的margin值

参数描述类型
top上边距Float
left左边距Float
bottom下边距Float
right右边距Float

padding方法

设置组件自身的padding值

参数描述类型
top上边距Float
left左边距Float
bottom下边距Float
right右边距Float

注意

叶子组件不支持padding方法, 可使用margin方法达到相同的效果

flexDirection方法

设置组件的孩子布局的方向, 排列方向即为主轴方法。此方法接收类型FlexDirection枚举

参数描述类型
COLUMN孩子从上往下排列布局FlexDirection
COLUMN_REVERSE孩子从下往上排列布局FlexDirection
ROW孩子从左往右排列布局FlexDirection
ROW_REVERSE孩子从右往左排列布局Float

flexWrap方法

设置组件的孩子超出组件时,是否换行

参数描述类型
NOWRAP孩子超出组件时,不换行FlexWrap
WRAP孩子超出组件时,换行FlexWrap

justifyContent方法

指定组件孩子做主轴上布局时的对齐方式。此方法接收类型FlexJustifyContent的枚举

参数描述类型
FLEX_START子组件在父容器的起始位置往主轴方向排列FlexJustifyContent
CENTER子组件在容器的主轴方向居中排列FlexJustifyContent
FLEX_END子组件在容器的终止位置往主轴方向排列FlexJustifyContent
SPACE_BETWEEN孩子在主轴方向均匀排列, 子组件之间的间距相同, 第一个子组件从父组件起始位置开始布局, 最后一个子组件布局在父组件结束位置FlexJustifyContent
SPACE_AROUND孩子在主轴方向均匀排列, 子组件之间的间距相同, 第一个子组件与父组件的起始位置的间距,最后一个子组件与父组件的终止位置之间的间距为子组件之间的间距的一半FlexJustifyContent
SPACE_EVENLY孩子在主轴方向均匀排列, 子组件之间的间距, 第一个子组件与父组件起始位置的间距, 最后一个子组件布局与父组件结束位置的间距都一样FlexJustifyContent

alignItems方法

指定子组件在交叉轴方向的排列方式。例如若子组件本来是沿着竖直方向排列的(即主轴竖直,那么交叉轴方向为水平方向)。 则alignItems决定了它们在水平方向的排列方式。此方法接收类型FlexAlign的枚举, 默认值为FlexAlign.STRETCH

参数描述类型
FLEX_START子组件在父容器中沿着交叉轴的起始位置对齐FlexAlign
CENTER子组件在父容器中沿着交叉轴的中间位置对齐FlexAlign
FLEX_END子组件在父容器中沿着交叉轴的终止位置对齐FlexAlign
STRETCH子组件在交叉轴上撑满父容器FlexAlign

alignSelf方法

justifyContent方法alignItems方法都是用于父组件指定子组件的布局方式。而alignSelf方法则是用于子组件自己指定在父组件 的交叉轴方向的排列方式(此样式设置在子元素上),其值会覆盖父元素的alignItems的值。该方法接收类型FlexAlign的枚举

参数描述类型
FLEX_START子组件在父容器中沿着交叉轴的起始位置对齐FlexAlign
CENTER子组件在父容器中沿着交叉轴的中间位置对齐FlexAlign
FLEX_END子组件在父容器中沿着交叉轴的终止位置对齐FlexAlign
STRETCH子组件在交叉轴上撑满父容器FlexAlign

positionType方法

指定组件在父容器中的排列方式, 该方法接收类型FlexPositionType的枚举。默认值为FlexPositionType.RELATIVE, 即使组件默认在父容器为相对布局

参数描述类型
RELATIVE子组件在父容器中的朴烈方式为相对排列布局FlexPositionType
ABSOLUTE子组件在父容器中的排列方式为绝对布局FlexPositionType

left方法

left方法是指将本组件的定位到距离左边的多少距离,而左边的定义取决于positionType方法设置的值。如果设置了FlexPositionType.RELATIVE, 那么left的作用相当于设置了marginLeft; 如果设置了FlexPositionType.ABSOLUTE, 那么left的作用是将元素的左边定位到距离父元素左边的left值。

top方法

top方法是指将本组件的定位到距离上边的多少距离,而上边的定义取决于positionType方法设置的值。如果设置了FlexPositionType.RELATIVE, 那么top的作用相当于设置了marginTop; 如果设置了FlexPositionType.ABSOLUTE, 那么top的作用是将元素的上边定位到距离父元素上边的top值。

right方法

right方法是指将本组件的定位到距离右边的多少距离,而右边的定义取决于positionType方法设置的值。如果设置了FlexPositionType.RELATIVE, 那么right的作用相当于设置了marginRight; 如果设置了FlexPositionType.ABSOLUTE, 那么right的作用是将元素的上边定位到距离父元素右边的right值。

bottom方法

bottom方法是指将本组件的定位到距离下边的多少距离,而下边的定义取决于positionType方法设置的值。如果设置了FlexPositionType.RELATIVE, 那么bottom的作用相当于设置了marginBottom; 如果设置了FlexPositionType.ABSOLUTE, 那么bottom的作用是将元素的上边定位到距离父元素下边的bottom值。


基础事件

每个Kuikly组件除了包含基础样式外,还包含一些通用的基础事件。这些事件是原生端的UI组件触发通知到Kuikly组件。

click事件

click事件意为单击事件,如果组件有设置单击事件,当Kuikly组件被点击时,会触发click闭包回调。click闭包中含有 ClickParams类型参数,以此来描述单击事件的信息

ClickParams

参数类型说明
xFloat相对于被点击组件的坐标x
yFloat相对于被点击组件的坐标y

示例

internal class ClickEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                }

                event {
                    click { clickParams ->
                        val x = clickParams.x
                        val y = clickParams.y
                    }
                }
            }
        }
    }
}












 
 
 
 
 
 




doubleClick事件

doubleClick事件为双击事件,当Kuikly组件有设置双击事件,并且Kuikly组件被双击时,会触发doubleClick闭包回调。 doubleClick回调闭包中含有ClickParams类型参数,以此来描述双击事件的信息

示例

internal class DoubleClickEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                }

                event {
                    doubleClick { clickParams ->
                        val x = clickParams.x
                        val y = clickParams.y
                    }
                }
            }
        }
    }
}












 
 
 
 
 
 




longPress事件

longPress事件为长按事件,当Kuikly组件有设置长按事件,并且Kuikly组件被长按时,会触发longPress闭包回调。 longPress回调闭包中含有LongPressParams类型参数,以此来描述长按事件的信息

LongPressParams

参数类型说明
xFloat相对于被长按组件的坐标x
yFloat相对于被长按组件的坐标y
stateString长按状态:"start", "move", "end"

示例

internal class LongPresskEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }

            View {
                attr {
                    size(100f, 100f)
                }

                event {
                    longPress { longPressParams ->
                        val x = longPressParams.x
                        val y = longPressParams.y
                        val state = longPressParams.state // start | move | end
                    }
                }
            }
        }
    }
}












 
 
 
 
 
 





pan事件

pan事件为拖拽事件, 常用于实现跟手拖拽的效果。当Kuikly组件有设置pan事件,并且Kuikly组件被拖拽时,会触发pan闭包回调。 pan回调闭包中含有PanGestureParams类型参数,以此来描述拖拽事件的信息。

PanGestureParams

参数描述类型
x相对于被拖拽的组件的坐标xFloat
y相对于被拖拽的组件的坐标yFloat
stateString拖拽状态:"start", "move", "end"
pageX拖拽点相对于页面的坐标xFloat
pageY拖拽点相对于页面的坐标yFloat

示例

@Page("demo_page")
internal class PanEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }
                
                event { 
                    pan { panGestureParams -> 
                        val x = panGestureParams.x
                        val y = panGestureParams.y
                        val state = panGestureParams.state
                        val pageX = panGestureParams.pageX
                        val pageY = panGestureParams.pageY
                    }
                }
            }
        }
    }
}













 
 
 
 
 
 
 
 
 
 



animationCompletion事件

animationCompletion事件为动画结束事件。当Kuikly组件有设置animationCompletion事件,并且Kuikly组件动画结束时,会触发animationCompletion闭包回调。 animationCompletion回调闭包中含有AnimationCompletionParams类型参数,以此来描述动画结束事件的信息。

animationCompletion

参数描述类型
finish动画是否正常结束。1表示动画正常结束;0表示动画被取消Int
attr标识哪个属性动画结束String

示例

@Page("demo_page")
internal class AnimationEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    animationCompletion { animationCompletionParams -> 
                        val finish = animationCompletionParams.finish == 1
                        val animationAttrKey = animationCompletionParams.attr
                    }
                }
            }
        }
    }
}













 
 
 
 
 
 




layoutFrameDidChange事件

layoutFrameDidChange事件为组件布局信息发生变化。当Kuikly组件有设置layoutFrameDidChange事件,并且Kuikly组件布局结束后,会触发layoutFrameDidChange闭包回调。 layoutFrameDidChange回调闭包中含有Frame类型参数,以此来描述组件布局信息发生事件的信息。

Frame

参数描述类型
x组件在父容器的x值Float
y组件在父容器的y值Float
width组件宽度Float
height组件高度Float

示例

@Page("demo_page")
internal class LayoutEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    layoutFrameDidChange { frame ->
                        val x = frame.x
                        val y = frame.y
                        val width = frame.width
                        val height = frame.height
                    }
                }
            }
        }
    }
}













 
 
 
 
 
 
 
 




willAppear事件

willAppear会在组件将要可见时触发(还未完全可见)。当Kuikly组件有设置willAppear事件,并且Kuikly组件将要可见时,会触发willAppear闭包回调。

示例

@Page("demo_page")
internal class WillAppearEventtPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    willAppear { 
                        // 组件将要可见
                    }
                }
            }
        }
    }
}













 
 
 
 
 




didAppear事件

didAppear会在组件完全可见时触发。当Kuikly组件有设置didAppear事件,并且Kuikly组件完全可见时,会触发didAppear闭包回调。

注: 根节点请使用页面事件 pageDidAppear

示例

@Page("demo_page")
internal class DidAppearEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    didAppear {
                        // 组件完全可见
                    }
                }
            }
        }
    }
}













 
 
 
 
 




willDisappear事件

willDisappear会在组件将要不可见时触发(还没完全不可见)。当Kuikly组件有设置willDisappear事件,并且Kuikly组件将要不可见时,会触发willDisappear闭包回调。

示例

@Page("demo_page")
internal class WillDisappearEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    willDisappear {
                        // 组件将要不可见
                    }
                }
            }
        }
    }
}













 
 
 
 
 




didDisappear事件

didDisappear会在组件完全不可见时触发。当Kuikly组件有设置didDisappear事件,并且Kuikly组件完全不可见时,会触发didDisappear闭包回调。

示例

@Page("demo_page")
internal class DidDisappearEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    didDisappear {
                        // 组件完全不可见
                    }
                }
            }
        }
    }
}













 
 
 
 
 




appearPercentage事件

appearPercentage事件为组件可见的百分比。当Kuikly组件有设置appearPercentage事件,并且Kuikly组件开始出现时, appearPercentage事件会 根据出现的百分比,会触发appearPercentage闭包回调。

示例

@Page("demo_page")
internal class AppearPercentageEventPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            attr {
                allCenter()
            }
            View { // View1
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                }

                event {
                    appearPercentage { percentage01 -> 
                        // percentage01为[0,1]的露出百分比,1为100%,0为0%]
                    }
                }
            }
        }
    }
}