OpenHarmony应用开发-禁用控制/Z序控制/图像变换及效果/形状裁剪
版本:v3.2 Release
禁用控制
组件是否可交互,可交互状态下响应点击事件、触摸事件、拖拽事件、按键事件、焦点事件和鼠标事件。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 描述 |
enabled | boolean | 值为true表示组件可交互,响应点击等操作。 值为false表示组件不可交互,不响应点击等操作。 默认值:true 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
示例
// xxx.ets
@Entry
@Component
struct EnabledExample {
build() {
Flex({ justifyContent: FlexAlign.SpaceAround }) {
// 点击没有反应
Button('disable').enabled(false).backgroundColor(0x317aff).opacity(0.4)
Button('enable').backgroundColor(0x317aff)
}
.width('100%')
.padding({ top: 5 })
}
}
浮层
设置组件的遮罩文本。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 默认值 | 描述 |
overlay | value: string, options?: { align?: Alignment, offset?: {x?: number, y?: number} } | { align: Alignment.Center, offset: {0, 0} } | 在当前组件上,增加遮罩文本。 value: 遮罩文本内容。 options: 文本定位,align设置文本相对于组件的方位,offset为文本基于自身左上角的偏移量。文本默认处于组件左上角。 两者都设置时效果重叠,文本相对于组件方位定位后再基于当前位置文本的左上角进行偏移。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
示例
// xxx.ets
@Entry
@Component
struct OverlayExample {
build() {
Column() {
Column() {
Text('floating layer')
.fontSize(12).fontColor(0xCCCCCC).maxLines(1)
Column() {
Image($r('app.media.img'))
.width(240).height(240)
.overlay("Winter is a beautiful season, especially when it snows.", {
align: Alignment.Bottom,
offset: { x: 0, y: -15 }
})
}.border({ color: Color.Black, width: 2 })
}.width('100%')
}.padding({ top: 20 })
}
}
Z序控制
组件的Z序,设置组件的堆叠顺序。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 描述 |
zIndex | number | 同一容器中兄弟组件显示层级关系。zIndex值越大,显示层级越高,即zIndex值大的组件会覆盖在zIndex值小的组件上方。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
示例
// xxx.ets
@Entry
@Component
struct ZIndexExample {
build() {
Column() {
Stack() {
// stack会重叠组件, 默认后定义的在最上面,具有较高zIndex值的元素在zIndex较小的元素前面
Text('1, zIndex(2)')
.size({ width: '40%', height: '30%' }).backgroundColor(0xbbb2cb)
.zIndex(2)
Text('2, default zIndex(1)')
.size({ width: '70%', height: '50%' }).backgroundColor(0xd2cab3).align(Alignment.TopStart)
.zIndex(1)
Text('3, zIndex(0)')
.size({ width: '90%', height: '80%' }).backgroundColor(0xc1cbac).align(Alignment.TopStart)
}.width('100%').height(200)
}.width('100%').height(200)
}
}
Stack容器内子组件不设置zIndex的效果
Stack容器子组件设置zIndex后效果
图形变换
用于对组件进行旋转、平移、缩放、矩阵变换等操作。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 描述 |
rotate | { x?: number, y?: number, z?: number, angle: number | string, centerX?: number | string, centerY?: number | string } | 可使组件在以组件左上角为坐标原点的坐标系中进行旋转(坐标系如下图所示)。其中,(x, y, z)指定一个矢量,作为旋转轴。 - angle:旋转角度。取值为正时相对于旋转轴方向顺时针转动,取值为负时相对于旋转轴方向逆时针转动。取值可为string类型,如’90deg’。 - centerX和centerY用于指定旋转的中心点。 旋转轴和旋转中心点都基于坐标系设定,组件发生位移时,坐标系不会随之移动。 默认值: { x: 0, y: 0, z: 0, centerX: ‘50%’, centerY: ‘50%’ } 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
translate | { x?: number | string, y?: number | string, z? : number | string } | 可使组件在以组件左上角为坐标原点的坐标系中进行移动(坐标系如下图所示)。其中,x,y,z的值分别表示在对应轴移动的距离,值为正时表示向对应轴的正向移动,值为负时表示向对应轴的反向移动。移动距离支持数字和字符串(比如’10px’,‘10%’)两种类型。 默认值: { x: 0, y: 0, z: 0 } 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
scale | { x?: number, y?: number, z?: number, centerX?: number | string, centerY?: number | string } | 可以分别设置X轴、Y轴、Z轴的缩放比例,默认值为1,同时可以通过centerX和centerY设置缩放的中心点。 默认值: { x: 1, y: 1, z: 1, centerX:‘50%’, centerY:‘50%’ } 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
transform | 设置当前组件的变换矩阵。 |
说明:
当组件同时设置了rotate和scale属性时,centerX和centerY的取值会发生冲突,此时centerX和centerY的值以后设定属性的值为准。
示例
// xxx.ets
import matrix4 from '@ohos.matrix4'
@Entry
@Component
struct TransformExample {
build() {
Column() {
Text('rotate').width('90%').fontColor(0xCCCCCC).padding(15).fontSize(14)
Row()
.rotate({
x: 0,
y: 0,
z: 1,
centerX: '50%',
centerY: '50%',
angle: 300
}) // 组件以矢量(0,0,1)为旋转轴,绕中心点顺时针旋转300度
.width(100).height(100).backgroundColor(0xAFEEEE)
Text('translate').width('90%').fontColor(0xCCCCCC).padding(10).fontSize(14)
Row()
.translate({ x: 100, y: 10 }) // x轴方向平移100,y轴方向平移10
.width(100).height(100).backgroundColor(0xAFEEEE).margin({ bottom: 10 })
Text('scale').width('90%').fontColor(0xCCCCCC).padding(15).fontSize(14)
Row()
.scale({ x: 2, y: 0.5 }) // 高度缩小一倍,宽度放大一倍,z轴在2D下无效果
.width(100).height(100).backgroundColor(0xAFEEEE)
Text('Matrix4').width('90%').fontColor(0xCCCCCC).padding(15).fontSize(14)
Row()
.width(100).height(100).backgroundColor(0xAFEEEE)
.transform(matrix4.identity().translate({ x: 50, y: 50 }).scale({ x: 1.5, y: 1 }).rotate({
x: 0,
y: 0,
z: 1,
angle: 60
}))
}.width('100%').margin({ top: 5 })
}
}
图像效果
设置组件的模糊,阴影效果以及设置图片的图像效果。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 默认值 | 描述 |
blur | number | - | 为当前组件添加内容模糊效果,入参为模糊半径,模糊半径越大越模糊,为0时不模糊。 取值范围:[0, +∞) 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
backdropBlur | number | - | 为当前组件添加背景模糊效果,入参为模糊半径,模糊半径越大越模糊,为0时不模糊。 取值范围:[0, +∞) 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
shadow | { radius: number | Resource, color?: Color | string | Resource, offsetX?: number | Resource, offsetY?: number | Resource} | - | 为当前组件添加阴影效果。 入参类型为ShadowOptions时,可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: ArkTS卡片上不支持参数为 ShadowStyle类型。 |
grayscale | number | 0.0 | 为当前组件添加灰度效果。值定义为灰度转换的比例,入参1.0则完全转为灰度图像,入参则0.0图像无变化,入参在0.0和1.0之间时,效果呈线性变化。(百分比) 取值范围:[0, 1] 说明: 设置小于0的值时,按值为0处理,设置大于1的值时,按值为1处理。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
brightness | number | 1.0 | 为当前组件添加高光效果,入参为高光比例,值为1时没有效果,小于1时亮度变暗,0为全黑,大于1时亮度增加,数值越大亮度越大。 取值范围:[0, +∞) 说明: 设置小于0的值时,按值为0处理。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
saturate | number | 1.0 | 为当前组件添加饱和度效果,饱和度为颜色中的含色成分和消色成分(灰)的比例,入参为1时,显示原图像,大于1时含色成分越大,饱和度越大,小于1时消色成分越大,饱和度越小。(百分比) 取值范围:[0, +∞) 说明: 设置小于0的值时,按值为0处理。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
contrast | number | 1.0 | 为当前组件添加对比度效果,入参为对比度的值。值为1时,显示原图,大于1时,值越大对比度越高,图像越清晰醒目,小于1时,值越小对比度越低,当对比度为0时,图像变为全灰。(百分比) 取值范围:[0, +∞) 说明: 设置小于0的值时,按值为0处理。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
invert | number | 0 | 反转输入的图像。入参为图像反转的比例,值为1时完全反转,值为0则图像无变化。(百分比) 取值范围:[0, 1] 说明: 设置小于0的值时,按值为0处理。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
sepia | number | 0 | 将图像转换为深褐色。入参为图像反转的比例,值为1则完全是深褐色的,值为0图像无变化。 (百分比) 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
hueRotate | number | string | ‘0deg’ | 色相旋转效果,输入参数为旋转角度。 取值范围:(-∞, +∞) 说明: 色调旋转360度会显示原始颜色。先将色调旋转180 度,然后再旋转-180度会显示原始颜色。数据类型为number时,值为90和’90deg’效果一致。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
colorBlend 8+ | Color | string | Resource | - | 为当前组件添加颜色叠加效果,入参为叠加的颜色。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
ShadowOptions对象说明
阴影属性集合,用于设置阴影的模糊半径、阴影的颜色、X轴和Y轴的偏移量。
从API version 9开始,该接口支持在ArkTS卡片中使用。
名称 | 类型 | 必填 | 说明 |
radius | number | Resource | 是 | 阴影模糊半径。 取值范围:[0, +∞) 说明: 设置小于0的值时,按值为0处理。 |
color | Color | string | Resource | 否 | 阴影的颜色。 默认为黑色。 |
offsetX | number | Resource | 否 | 阴影的X轴偏移量。 默认为0。 |
offsetY | number | Resource | 否 | 阴影的Y轴偏移量。 默认为0。 |
示例
示例1
模糊属性的用法,blur内容模糊,backdropBlur背景模糊。
// xxx.ets
@Entry
@Component
struct BlurEffectsExample {
build() {
Column({ space: 10 }) {
// 对字体进行模糊
Text('font blur').fontSize(15).fontColor(0xCCCCCC).width('90%')
Flex({ alignItems: ItemAlign.Center }) {
Text('original text').margin(10)
Text('blur text')
.blur(1).margin(10)
Text('blur text')
.blur(2).margin(10)
Text('blur text')
.blur(3).margin(10)
}.width('90%').height(40)
.backgroundColor(0xF9CF93)
// 对背景进行模糊
Text('backdropBlur').fontSize(15).fontColor(0xCCCCCC).width('90%')
Text()
.width('90%')
.height(40)
.fontSize(16)
.backdropBlur(3)
.backgroundImage('/pages/attrs/image/image.jpg')
.backgroundImageSize({ width: 1200, height: 160 })
}.width('100%').margin({ top: 5 })
}
}
示例2
设置图片的效果,包括阴影,灰度,高光,饱和度,对比度,图像反转,叠色,色相旋转等。
// xxx.ets
@Entry
@Component
struct ImageEffectsExample {
build() {
Column({ space: 10 }) {
// 添加阴影效果,图片效果不变
Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image'))
.width('90%')
.height(40)
.shadow({ radius: 10, color: Color.Green, offsetX: 20, offsetY: 30 })
// 灰度效果0~1,越接近1,灰度越明显
Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).grayscale(0.3)
Image($r('app.media.image')).width('90%').height(40).grayscale(0.8)
// 高光效果,1为正常图片,<1变暗,>1亮度增大
Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).brightness(1.2)
// 饱和度,原图为1
Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).saturate(2.0)
Image($r('app.media.image')).width('90%').height(40).saturate(0.7)
// 对比度,1为原图,>1值越大越清晰,<1值越小越模糊
Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).contrast(2.0)
Image($r('app.media.image')).width('90%').height(40).contrast(0.8)
// 图像反转比例
Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).invert(0.2)
Image($r('app.media.image')).width('90%').height(40).invert(0.8)
// 叠色添加
Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).colorBlend(Color.Green)
Image($r('app.media.image')).width('90%').height(40).colorBlend(Color.Blue)
// 深褐色
Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).sepia(0.8)
// 色相旋转
Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%')
Image($r('app.media.image')).width('90%').height(40).hueRotate(90)
}.width('100%').margin({ top: 5 })
}
}
形状裁剪
用于对组件进行裁剪、遮罩处理。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 描述 |
clip | 参数为相应类型的组件,按指定的形状对当前组件进行裁剪;参数为boolean类型时,设置是否按照父容器边缘轮廓进行裁剪。 默认值:false 从API version 9开始,该接口支持在ArkTS卡片中使用。 | |
mask | 在当前组件上加上指定形状的遮罩。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
示例
// xxx.ets
@Entry
@Component
struct ClipAndMaskExample {
build() {
Column({ space: 15 }) {
Text('clip').fontSize(12).width('75%').fontColor('#DCDCDC')
Row() {
Image($r('app.media.testImg')).width('500px').height('280px')
}
.clip(true) // 如这里不设置clip为true,则Row组件的圆角不会限制其中的Image组件,Image组件的四个角会超出Row
.borderRadius(20)
// 用一个280px直径的圆对图片进行裁剪
Image($r('app.media.testImg'))
.clip(new Circle({ width: '280px', height: '280px' }))
.width('500px').height('280px')
Text('mask').fontSize(12).width('75%').fontColor('#DCDCDC')
// 给图片添加了一个500px*280px的方形遮罩
Image($r('app.media.testImg'))
.mask(new Rect({ width: '500px', height: '280px' }).fill(Color.Gray))
.width('500px').height('280px')
// 给图片添加了一个280px*280px的圆形遮罩
Image($r('app.media.testImg'))
.mask(new Circle({ width: '280px', height: '280px' }).fill(Color.Gray))
.width('500px').height('280px')
}
.width('100%')
.margin({ top: 15 })
}
}