• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 安全区域
2
3安全区域是指页面的显示区域，默认不与系统设置的非安全区域比如状态栏、导航栏区域重叠，默认情况下开发者开发的界面都被布局在安全区域内。提供属性方法允许开发者设置组件绘制内容突破安全区域的限制，通过expandSafeArea属性支持组件不改变布局情况下扩展其绘制区域至安全区外，通过设置setKeyboardAvoidMode来配置虚拟键盘弹出时页面的避让模式。
4
5> **说明：**
6>
7> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9## expandSafeArea
10
11expandSafeArea(types?: Array<SafeAreaType>, edges?: Array<SafeAreaEdge>)
12
13控制组件扩展其安全区域。
14
15**系统能力：** SystemCapability.ArkUI.ArkUI.Full
16
17**参数：**
18
19| 参数名 | 类型                                               | 必填 | 说明                                                         |
20| ------ | -------------------------------------------------- | ---- | ------------------------------------------------------------ |
21| types  | Array <[SafeAreaType](ts-types.md#safeareatype10)> | 否   | 非必填，配置扩展安全区域的类型。<br />默认值: <br />[SafeAreaType.SYSTEM, SafeAreaType.CUTOUT, SafeAreaType.KEYBOARD] |
22| edges  | Array <[SafeAreaEdge](ts-types.md#safeareaedge10)> | 否   | 非必填，配置扩展安全区域的方向。<br /> [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM, SafeAreaEdge.START, SafeAreaEdge.END]<br />扩展至所有非安全区域。 |
23
24>  **说明：**
25>
26>设置expandSafeArea属性进行组件绘制扩展时，组件不能设置固定宽高尺寸（百分比除外）。
27>
28>安全区域不会限制内部组件的布局和大小，不会裁剪内部组件。
29>
30>当父容器是滚动容器时，设置expandSafeArea属性不生效。
31
32## setKeyboardAvoidMode<sup>11+</sup>
33
34setKeyboardAvoidMode(value: KeyboardAvoidMode): void
35
36控制虚拟键盘抬起时页面的避让模式。
37
38**系统能力：** SystemCapability.ArkUI.ArkUI.Full
39
40**参数：**
41
42| 参数名 | 类型                                                 | 必填 | 说明                                                         |
43| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
44| value  | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode11) | 是   | 控制虚拟键盘抬起时页面的避让模式。<br />默认值: KeyboardAvoidMode.OFFSET <br />键盘抬起时默认页面避让模式为上抬模式。<br />必填，配置虚拟键盘避让时的页面避让模式。 |
45
46## getKeyboardAvoidMode
47
48getKeyboardAvoidMode(): KeyboardAvoidMode
49
50返回虚拟键盘抬起时的页面避让模式。
51
52**系统能力：** SystemCapability.ArkUI.ArkUI.Full
53
54**返回值：**
55
56| 名称                                                 | 说明                               |
57| ---------------------------------------------------- | ---------------------------------- |
58| [KeyboardAvoidMode](ts-types.md#keyboardavoidmode11) | 返回虚拟键盘抬起时的页面避让模式。 |
59
60## 示例
61
62### 示例1
63
64```ts
65// xxx.ets
66@Entry
67@Component
68struct SafeAreaExample1 {
69  @State text: string = ''
70  controller: TextInputController = new TextInputController()
71
72  build() {
73    Row() {
74        Column()
75          .height('100%').width('100%')
76          .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
77          .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
78    }.height('100%')
79  }
80}
81```
82
83![expandSafeArea1](figures/expandSafeArea1.png)
84
85### 示例2
86
87```ts
88// xxx.ets
89@Entry
90@Component
91struct SafeAreaExample {
92  @State text: string = ''
93  controller: TextInputController = new TextInputController()
94
95  build() {
96    Row() {
97      Stack() {
98        Column()
99          .height('100%').width('100%')
100          .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
101          .expandSafeArea([SafeAreaType.KEYBOARD, SafeAreaType.SYSTEM])
102        Column() {
103          Button('Set caretPosition 1')
104            .onClick(() => {
105              this.controller.caretPosition(1)
106            })
107          TextInput({ text: this.text, placeholder: 'input your word...', controller: this.controller })
108            .placeholderFont({ size: 14, weight: 400 })
109            .width(320).height(40).offset({y: 120})
110            .fontSize(14).fontColor(Color.Black)
111            .backgroundColor(Color.White)
112        }.width('100%').alignItems(HorizontalAlign.Center)
113      }
114    }.height('100%')
115  }
116}
117```
118
119![expandSafeArea2](figures/expandSafeArea2.png)
120
121### 示例3
122
123```ts
124// EntryAbility.ets
125import { KeyboardAvoidMode } from '@ohos.arkui.UIContext';
126
127  onWindowStageCreate(windowStage: window.WindowStage) {
128    // Main window is created, set main page for this ability
129    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
130
131    windowStage.loadContent('pages/Index', (err, data) => {
132      let a = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
133     // 设置虚拟键盘抬起时压缩页面大小为减去键盘的高度
134  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
135      if (err.code) {
136        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
137        return;
138      }
139      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
140    });
141  }
142
143// xxx.ets
144@Entry
145@Component
146struct KeyboardAvoidExample {
147    build() {
148    Column() {
149      Row().height("30%").width("100%").backgroundColor(Color.Gray)
150      TextArea().width("100%").borderWidth(1)
151      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
152    }.width('100%').height("100%")
153  }
154}
155```
156
157![keyboardAvoidMode1](figures/keyboardAvoidMode1.jpg)
158
159### 示例4
160
161```ts
162// EntryAbility.ets
163import { KeyboardAvoidMode } from '@ohos.arkui.UIContext';
164
165  onWindowStageCreate(windowStage: window.WindowStage) {
166    // Main window is created, set main page for this ability
167    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
168
169    windowStage.loadContent('pages/Index', (err, data) => {
170      let a = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
171     // 设置虚拟键盘抬起时把页面上抬直到露出光标
172  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);
173      if (err.code) {
174        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
175        return;
176      }
177      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
178    });
179  }
180
181// xxx.ets
182@Entry
183@Component
184struct KeyboardAvoidExample {
185    build() {
186    Column() {
187      Row().height("30%").width("100%").backgroundColor(Color.Gray)
188      TextArea().width("100%").borderWidth(1)
189      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
190    }.width('100%').height("100%")
191  }
192}
193```
194
195![keyboardAvoidMode1](figures/keyboardAvoidMode2.jpg)