鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(安全区域)

鸿蒙HarmonyOS NEXT开发:安全区域 安全区域是指页面的显示区域,默认不与系统设置的非安全区域比如状态栏、导航栏区域重叠,默认情况下开发者开发的界面都被布局在安全区域内。 阅读详情

往期鸿蒙全套实战文章必看:(文中附带全栈鸿蒙学习资料)


安全区域

安全区域是指页面的显示区域,默认不与系统设置的非安全区域比如状态栏、导航栏区域重叠,默认情况下开发者开发的界面都被布局在安全区域内。提供属性方法允许开发者设置组件绘制内容突破安全区域的限制,通过expandSafeArea属性支持组件不改变布局情况下扩展其绘制区域至安全区外,通过设置setKeyboardAvoidMode来配置虚拟键盘弹出时页面的避让模式。页面中有标题栏等文字不希望和非安全区重叠时,建议对组件设置expandSafeArea属性达到沉浸式效果,也可以直接通过窗口接口setWindowLayoutFullScreen设置沉浸式。

说明

从API Version 10开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

默认摄像头挖孔区域不为非安全区域,页面不避让挖孔。

从API Version 12开始,可在module.json5中添加配置项, 摄像头挖孔区域视为非安全区,实现页面默认避让挖孔:

"metadata": [

{

"name": "avoid_cutout",

"value": "true",

}

],

expandSafeArea

expandSafeArea(types?: Array<SafeAreaType>, edges?: Array<SafeAreaEdge>)

控制组件扩展其安全区域。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
typesArray <SafeAreaType>否

配置扩展安全区域的类型。未添加Metadata配置项时,页面不避让挖孔, CUTOUT类型不生效。

默认值:[SafeAreaType.SYSTEM, SafeAreaType.CUTOUT, SafeAreaType.KEYBOARD]

edgesArray <SafeAreaEdge>否

配置扩展安全区域的方向。

默认值:[SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM, SafeAreaEdge.START, SafeAreaEdge.END]

扩展至所有非安全区域。

说明

设置expandSafeArea属性进行组件绘制扩展时,组件不能设置固定宽高尺寸(百分比除外)。

安全区域不会限制内部组件的布局和大小,不会裁剪内部组件。

当父容器是滚动容器时,设置expandSafeArea属性不生效。

设置expandSafeArea()时,不传参,走默认值处理;设置expandSafeArea([],[])时,相当于入参是空数组,此时设置expandSafeArea属性不生效。

组件设置expandSafeArea之后生效的条件为:

1.type为SafeAreaType.KEYBOARD时默认生效,组件不避让键盘。

2.设置其他type,组件的边界与安全区域重合时组件能够延伸到安全区域下。例如:设备顶部状态栏高度100,那么组件在屏幕中的绝对位置需要为0 <= y <= 100。

组件延伸到安全区域下,在安全区域处的事件,如点击事件等可能会被系统拦截,优先给状态栏等系统组件响应。

滚动类容器内的组件不建议设置expandSafeArea属性,如果设置,需要按照组件嵌套关系,将当前节点到滚动类祖先容器间所有直接节点设置expandSafeArea属性,否则expandSafeArea属性在滚动后可能会失效,写法参考示例5。

expandSafeArea属性仅作用于当前组件,不会向父组件或子组件传递,因此使用过程中,所有相关组件均需配置。

在同时设置了expandSafeArea和position属性时,position属性会先生效,expandSafeArea属性会后生效。对于未设置position、offset等绘制属性的组件,如果组件边界没有和避让区重叠,设置expandSafeArea属性不生效,如弹窗和半模态组件。

对于expandSafeArea属性无法生效的场景,若要将组件部署在避让区,需要手动调整组件的坐标。

setKeyboardAvoidMode11+

setKeyboardAvoidMode(value: KeyboardAvoidMode): void

控制虚拟键盘抬起时页面的避让模式。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueKeyboardAvoidMode是

配置虚拟键盘抬起时页面的避让模式。

默认值:KeyboardAvoidMode.OFFSET,键盘抬起时默认页面避让模式为上抬模式。

说明

KeyboardAvoidMode.RESIZE是压缩Page的大小,Page下设置百分比宽高的组件会跟随Page压缩,直接设置宽高的组件会按设置的固定大小布局。设置KeyboardAvoidMode.RESIZE时,expandSafeArea([SafeAreaType.KEYBOARD],[SafeAreaEdge.BOTTOM])不生效。

getKeyboardAvoidMode

getKeyboardAvoidMode(): KeyboardAvoidMode

返回虚拟键盘抬起时的页面避让模式。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

名称说明
KeyboardAvoidMode返回虚拟键盘抬起时的页面避让模式。

示例

示例1(实现沉浸式效果)

该示例通过设置expandSafeArea属性向顶部和底部扩展安全区实现沉浸式效果。

// xxx.ets
@Entry
@Component
struct SafeAreaExample1 {
  @State text: string = ''
  controller: TextInputController = new TextInputController()

  build() {
    Row() {
        Column()
          .height('100%').width('100%')
          .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
          .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
    }.height('100%')
  }
}

示例2(键盘避让时固定背景图位置)

该示例通过为背景图组件设置expandSafeArea属性,来实现拉起键盘进行避让时,背景图保持不动的效果。

// xxx.ets
@Entry
@Component
struct SafeAreaExample2 {
  @State text: string = ''
  controller: TextInputController = new TextInputController()

  build() {
    Row() {
      Stack() {
        Column()
          .height('100%').width('100%')
          .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
          .expandSafeArea([SafeAreaType.KEYBOARD, SafeAreaType.SYSTEM])
        Column() {
          Button('Set caretPosition 1')
            .onClick(() => {
              this.controller.caretPosition(1)
            })
          TextInput({ text: this.text, placeholder: 'input your word...', controller: this.controller })
            .placeholderFont({ size: 14, weight: 400 })
            .width(320).height(40).offset({y: 120})
            .fontSize(14).fontColor(Color.Black)
            .backgroundColor(Color.White)
        }.width('100%').alignItems(HorizontalAlign.Center)
      }
    }.height('100%')
  }
}

示例3(设置键盘避让模式为压缩)

该示例通过调用setKeyboardAvoidMode设置键盘避让模式为RESIZE模式,实现键盘抬起时page的压缩效果。

// EntryAbility.ets
import { KeyboardAvoidMode } from '@kit.ArkUI';

onWindowStageCreate(windowStage: window.WindowStage) {
  // Main window is created, set main page for this ability
  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err, data) => {
    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
    // 设置虚拟键盘抬起时压缩页面大小为减去键盘的高度
  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
    if (err.code) {
      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
  });
}
// xxx.ets
@Entry
@Component
struct KeyboardAvoidExample1 {
  build() {
    Column() {
      Row().height("30%").width("100%").backgroundColor(Color.Gray)
      TextArea().width("100%").borderWidth(1)
      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
    }.width('100%').height("100%")
  }
}

示例4(设置键盘避让模式为上抬)

该示例通过调用setKeyboardAvoidMode设置键盘避让模式为OFFSET模式,实现键盘抬起时page的上抬效果。但当输入光标距离屏幕底部的高度大于键盘高度时,page不会抬起,如本例中所示。

// EntryAbility.ets
import { KeyboardAvoidMode } from '@kit.ArkUI';

onWindowStageCreate(windowStage: window.WindowStage) {
  // Main window is created, set main page for this ability
  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err, data) => {
    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
    // 设置虚拟键盘抬起时把页面上抬直到露出光标
  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);
    if (err.code) {
      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
      return;
    }
    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
  });
}
// xxx.ets
@Entry
@Component
struct KeyboardAvoidExample2 {
  build() {
    Column() {
      Row().height("30%").width("100%").backgroundColor(Color.Gray)
      TextArea().width("100%").borderWidth(1)
      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
    }.width('100%').height("100%")
  }
}

示例5(滚动类容器扩展安全区)

该示例通过在滚动类容器内调用expandSafeArea属性实现沉浸式效果。

class SwiperDataSource implements IDataSource {
  private list: Array<Color> = []
  constructor(list: Array<Color>) {
    this.list = list
  }
  totalCount(): number {
    return this.list.length
  }
  getData(index: number): Color {
    return this.list[index]
  }
  registerDataChangeListener(listener: DataChangeListener): void {
  }
  unregisterDataChangeListener(listener: DataChangeListener): void {
  }
}
@Entry
@Component
struct ExpandSafeAreaTest {
  private swiperController: SwiperController = new SwiperController()
  private swiperData: SwiperDataSource = new SwiperDataSource([])
  private list: Array<Color> = [
    Color.Pink,
    Color.Blue,
    Color.Green
  ]
  aboutToAppear(): void {
    this.swiperData = new SwiperDataSource(this.list)
  }
  build() {
    Scroll() {
      Column() {
        Swiper(this.swiperController) {
          LazyForEach(this.swiperData, (item: Color, index: number) => {
            Column() {
              Text('banner' + index).fontSize(50).fontColor(Color.White)
            }
            .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
            .width('100%')
            .height(400)
            .backgroundColor(item)
          })
        }
        .loop(true)
        .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
        .clip(false)
        Column(){
          Text("Tab页Content").fontSize(50)
        }.width("100%").height(1000)
        .backgroundColor(Color.Grey)
      }.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
    }
    .clip(false)
    .edgeEffect(EdgeEffect.None)
    .width("100%").height("100%")
  }
}

鸿蒙-expandSafeArea使用 由于expandSafeArea不改变子节点布局,因此,List等滚动类组件可以调用expandSafeArea,延伸List组件视图窗口大小而不改变ListItem内在布局。**应用未使用setWindowLayoutFullScreen()接口设置窗口全屏布局时,默认使能组件安全区布局。要求需要List滚动类组件滚动过程中元素可以和导航条重合,滚动至底部时,元素在导航条上面需要避让。设置背景图、视频控件大小为安全区域大小并配置expandSafeArea属性。属性扩展安全区域属性进行调整。 阅读详情

相关推荐

鸿蒙Harmony应用开发—ArkTS声明式开发(通用属性:安全区域)

ArkTS声明式开发-通用属性:安全区域

m0_64420071的博客 3427

鸿蒙开发之沉浸式效果

在移动端开发中,安全区域是指页面的显示区域,默认不与系统设置的非安全区域比如状态栏、导航栏区域重叠,默认情况下开发者开发的界面都被布局在安全区域内。例如下图中,图片被布局在顶部状态栏和底部导航栏之间:如果我们想要实现一个微信朋友圈沉浸式的效果,如下图:这个效果怎么实现呢?

yihanss的博客 2247

ArcGIS Pro 3.0 加载天地图WMTS服务,解决偏移问题的保姆级教程(附最新Key申请流程)

本文详细介绍了在ArcGIS Pro 3.0中精准加载天地图WMTS服务的全流程,包括最新Key申请流程、解决地图偏移问题的关键配置步骤以及常见问题排查方法。通过设置`esri`参数和统一坐标参考,确保地理数据与天地图底图精确匹配,提升GIS空间分析的准确性。

weixin_28713947的博客 310

鸿蒙HarmonyOS开发:安全区域、沉浸式页面开发实践,软键盘布局适配解决方案

安全区域定义为页面的显示区域,其默认不与系统设置的非安全区域(如状态栏、导航栏)重叠,以确保开发者设计的界面均布局于安全区域内。然而,当Web组件启用沉浸式模式时,网页元素可能会出现与状态栏或导航栏重叠的问题。具体示例如图1所示,中间部分的区域即为安全区域,而顶部状态栏、屏幕挖孔区域和底部导航条则被界定为避让区,Web组件开启沉浸式效果时,网页内底部元素与导航条发生重叠。

在这里,我乐于倾囊相授,分享我的技术心得、项目实战经验、技术技巧。希望能够惠及更多的开发者,助力大家在技术的海洋中扬帆远航。 3042

Geneformer实战:如何用Hugging Face Transformers快速搭建单细胞转录组分类模型

本文详细介绍了如何使用Geneformer和Hugging Face Transformers快速搭建单细胞转录组分类模型。通过环境准备、数据预处理、模型加载与配置、训练Pipeline构建等步骤,帮助读者掌握基于Transformer架构的单细胞数据分析技术,提升分类准确率和效率。

rl6adventurer的博客 605

史上最小白之RNN详解

1.前言 网上目前已经有诸多优秀的RNN相关博客,但是我写博客的出发点主要是为了加深和巩固自己的理解,所以还是决定自己再进行一下总结和描述,如有不正确的地方欢迎指正~ 2.区分RNN 循环神经网络(Recurrent Neural Network),递归神经网络(Recursive Neural Network),你有没有发现他们的缩写都是RNN,那他们两个是同一回事儿吗?网上有一些博客把这两就当...

Tink1995的博客 4万+

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(菜单控制)

为组件绑定弹出式菜单,弹出式菜单以垂直列表形式显示菜单项,可通过长按、点击或鼠标右键触发。

Androidbye的博客 1193

实战指南:将MediaPipe封装为Windows DLL,实现C++/C#高效调用

在计算机视觉和多媒体处理领域,跨平台框架为开发者提供了强大的算法模型和计算能力。其核心原理在于通过预训练的机器学习模型和优化的计算图,实现对图像、视频流中特定目标(如人脸、手势、姿态)的实时检测与分析。这项技术的价值在于能够将复杂的AI能力模块化,降低应用开发门槛。在实际工程实践中,为了突破特定语言生态的限制并优化部署流程,开发者常需将核心功能封装成独立的库。例如,将Google的MediaPipe框架封装为Windows动态链接库(DLL),就是一个典型的工程实践。此举能有效解决语言壁垒和部署简化问题,使

weixin_28691741的博客 360

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(颜色渐变)

设置组件的颜色渐变效果。

Androidbye的博客 1334

《ESP32单片机基础入门》第2章:开发环境搭建

【代码】《ESP32单片机基础入门》第2章:开发环境搭建。

2301_79143213的博客 582

Android 人像分割实战:OpenCV+YOLOv8+NCNN 三库联动(附 GPU 加速 / 内存优化全方案)

本文详细介绍了在Android项目中集成OpenCV+YOLOv8+NCNN实现实时人像分割的技术方案。主要内容包括:项目环境搭建(配置NDK、添加Native模块)、核心库文件集成(OpenCV、NCNN、YOLOv8模型)、JNI接口设计与实现(Kotlin层调用C++算法)。通过Camera API获取图像数据,使用YOLOv8进行人体检测,结合NCNN高性能推理框架实现人像分割处理,最终将原始画面与分割结果(背景透明)同时显示在Android界面上。该项目采用多技术栈协同工作,OpenCV负责图像处

FJN110的博客 236

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(浮层)

设置组件的浮层。

Androidbye的博客 1208

【nnUNetv2进阶】三、nnUNetv2 自定义网络-发paper必会

对于很多朋友来说,找到nnunet的网络结构位置的代码可能比较困难,因为nnunet的网络结构从else:代码中没有网络结构的类名,那么使用的网络是哪个呢?打开预处理后的数据集中的nnUNetPlans.json文件,如下图,configurations里面有2d、3d_fullres等,这些表示nnunet的模型,下面的network_class_name指的就是训练使用的模型结构,一般都是PlainConvUNet。

AI爱好者的博客,分享计算机领域相关知识 8759

【鸿蒙next开发】ArkUI框架:ArkTS组件-安全区域

本文详细介绍了鸿蒙5.0开发中的安全区域概念及其相关API的使用方法。

m0_73088370的博客 1330

华南理工大学-大学物理实验-不良导体热导率测量

不良导体热导率测量 引言 导热系数(又叫热导率)是反映材料热性能的重要物理量。热传导是热交换的三种(热传导、对流和辐射)基本形式之一,是工程热物理、材料科学、固体物理及能源、环保等各个研究领域的课题。材料的导热机理在很大程度上取决于它的微观结构,热量的传递依靠原子、分子围绕平衡位置的振动以及自由电子的迁移。在金属中电子流起支配作用,在绝缘体和大部分半导体中则以晶格振动起主导作用。因此,某种材料的导热系数不仅与构成材料的物质种类密切相关,而且还与材料的微观结构、温度、压力及杂质含量相联系。在科学实验和工程设计

mohen_777的博客 873

android 蓝牙通讯demo

android 下蓝牙通讯demo,实现了发现蓝牙,使能蓝牙,通过蓝牙发送消息。

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(焦点控制)

自定义组件的走焦效果,可设置组件是否走焦和具体的走焦顺序,tab键或者方向键切换焦点。

Androidbye的博客 1326

win10 跳过U8环境检测的IE WebControls.rar

win10 安装u8的时候 提示IE WebControls 不通过,这个工具可以欺骗u8的检查。 跳过U8环境检测的IE WebControls。提示导入失败后,重新检测通过。

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(栅格设置)

栅格布局的列宽、列间距由距离最近的GridContainer父组件决定。

Androidbye的博客 1140

SAP B1中文培訓教材_SDK

公司内部培训资料,对开发工具 ,DIAPI, UIAPI,Add-ON有详细解说

最新的sdio 4.0 spec 协议标准 带书签 高清完整PDF版

Part-E1-SDIO-Specification-Ver4.00-Final-120220.pdf:最新的sdio 4.0 spec 协议标准 带书签 高清完整PDF版,包括SDIO 接口的外设,SDIO 接口官方协议等。

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(形状裁剪)

用于对组件进行裁剪、遮罩处理。

Androidbye的博客 819

【鸿蒙next开发】ArkUI框架:ArkTS组件-TextInput

TextInput组件用于单行文本输入,支持多种属性和事件,如设置提示文本、文本内容、光标颜色、输入框类型等。

m0_73088370的博客 1643

鸿蒙5.0版开发:ArkUI框架开发-嵌入ArkTS组件

ArkUI在Native侧提供的能力作为ArkTS的子集...........

m0_73088370的博客 1320

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(拖拽控制)

设置组件是否可以响应拖拽事件。

Androidbye的博客 1210

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(组件标识)

id为组件的唯一标识,在整个应用内唯一。

Androidbye的博客 1019

【鸿蒙next开发】ArkUI框架:ArkTS组件-形状裁剪

本文详细讲解了clip、clipShape、mask和maskShape等接口的使用方法及其参数说明,并提供了从API版本7到12的更新和废弃信息。

m0_73088370的博客 1166

【鸿蒙next开发】ArkUI框架:ArkTS组件-SideBarContainer

本文详细介绍了鸿蒙5.0开发中的SideBarContainer组件,该组件用于创建可显示和隐藏的侧边栏。

m0_73088370的博客 1114

【鸿蒙next开发】ArkUI框架:ArkTS组件-Circle

本文详细说明了Circle的各种属性和配置选项,包括宽度/高度设置、填充颜色(fill)、透明度(fillOpacity)、边框属性(stroke)、虚线样式(strokeDashArray)等。

m0_73088370的博客 823

鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(背景设置)

设置组件的背景样式。

Androidbye的博客 1248
上一篇: 鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(拖拽控制)
下一篇: 鸿蒙5.0开发进阶:API ArkUI框架-ArkTS组件(组件内容填充方式)
懂你的大海
博客等级 码龄6年 9049粉丝 1381原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值