1# Safe Area
2
3A safe area refers to the display area that isn't covered by a status bar, navigation bar, or any other component in the system-defined non-safe-areas. By default, all the content you develop is placed in the safe area. If necessary, you can expand a component's safe area through the [expandSafeArea](#expandsafearea) attribute – without changing the layout, and specify how to make space for the virtual keyboard through the [setKeyboardAvoidMode](#setkeyboardavoidmode11) attribute.
4
5> **NOTE**
6>
7> This attribute is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.<br>
8> By default, the notch area is not a non-safe-area, and content can be displayed in this area.<br>
9> You can set the notch area as a non-safe-area since API version 12, so that content is not displayed in this area. To do so, add the following to the **module.json5** file:<br>
10  "metadata": [<br>
11      {<br>
12        "name": "avoid_cutout",<br>
13        "value": "true",<br>
14      }<br>
15  ],<br>
16  
17
18## expandSafeArea
19
20expandSafeArea(types?: Array&lt;SafeAreaType&gt;, edges?: Array&lt;SafeAreaEdge&gt;)
21
22Sets the safe area to be expanded to.
23
24**Atomic service API**: This API can be used in atomic services since API version 11.
25
26**System capability**: SystemCapability.ArkUI.ArkUI.Full
27
28**Parameters**
29
30| Name| Type                                              | Mandatory| Description                                                        |
31| ------ | -------------------------------------------------- | ---- | ------------------------------------------------------------ |
32| types  | Array <[SafeAreaType](ts-types.md#safeareatype10)> | No  | Types of the expanded safe area. For the **CUTOUT** type to take effect, the **metadata** item must be added to the configuration file.<br>Default value:<br>[SafeAreaType.SYSTEM, SafeAreaType.CUTOUT, SafeAreaType.KEYBOARD] |
33| edges  | Array <[SafeAreaEdge](ts-types.md#safeareaedge10)> | No  | Edges for expanding the safe area.<br> Default value: [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM, SafeAreaEdge.START, SafeAreaEdge.END]<br>The default value expands the safe area on all available edges.|
34
35>  **NOTE**
36>
37>  To set the **expandSafeArea** attribute for a component, this component cannot have its width and height fixed (except to a percentage).
38>
39>  The safe area does not restrict the layout or size of components inside, nor does it clip the components.
40>
41>  If the parent container is a scroll container, the **expandSafeArea** attribute does not take effect.
42>
43>  When **expandSafeArea()** is set, no parameter is passed in, and the default value is used. When **expandSafeArea([],[])** is set, an empty array is passed in, and the settings do not take effect.
44>   
45>  After **expandSafeArea** is set: 
46>  1. If **type** is set to **SafeAreaType.KEYBOARD**, the settings take effect without additional conditions. 
47>  2. If **type** is set to any other value, the settings take effect under the prerequisite that the component can extend to the safe area when the component border overlaps with the safe area. For example, if the height of the status bar is 100, the absolute position of the component on the screen must be 0 <= y <= 100 for the settings to take effect. 
48>   
49>  When the component extends to the safe area, the system may intercept events in the safe area to preferentially respond to events of system components, such as the status bar.
50
51## setKeyboardAvoidMode<sup>11+</sup>
52
53setKeyboardAvoidMode(value: KeyboardAvoidMode): void
54
55Sets the avoid mode for the virtual keyboard.
56
57**Atomic service API**: This API can be used in atomic services since API version 11.
58
59**System capability**: SystemCapability.ArkUI.ArkUI.Full
60
61**Parameters**
62
63| Name| Type                                                | Mandatory| Description                                                        |
64| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
65| value  | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode11) | Yes  | Avoid mode of the virtual keyboard.<br>Default value: **KeyboardAvoidMode.OFFSET**<br>By default, offset is used to avoid the virtual keyboard.<br> |
66
67>  **NOTE**
68>  With **KeyboardAvoidMode.RESIZE**, the page is resized to prevent the virtual keyboard from obstructing the view. Regarding components on the page, those whose width and height are set in percentage are resized with the page, and those whose width and height are set to specific values are laid out according to their settings.
69>
70>  When **KeyboardAvoidMode.RESIZE** is used, **expandSafeArea([SafeAreaType.KEYBOARD],[SafeAreaEdge.BOTTOM])** does not take effect.
71
72## getKeyboardAvoidMode
73
74getKeyboardAvoidMode(): KeyboardAvoidMode
75
76Obtains the avoid mode of the virtual keyboard.
77
78**Atomic service API**: This API can be used in atomic services since API version 11.
79
80**System capability**: SystemCapability.ArkUI.ArkUI.Full
81
82**Return value**
83
84| Name                                                | Description                              |
85| ---------------------------------------------------- | ---------------------------------- |
86| [KeyboardAvoidMode](ts-types.md#keyboardavoidmode11) | Avoid mode of the virtual keyboard.|
87
88## Example
89
90### Example 1
91
92```ts
93// xxx.ets
94@Entry
95@Component
96struct SafeAreaExample1 {
97  @State text: string = ''
98  controller: TextInputController = new TextInputController()
99
100  build() {
101    Row() {
102        Column()
103          .height('100%').width('100%')
104          .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
105          .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])
106    }.height('100%')
107  }
108}
109```
110
111![expandSafeArea1](figures/expandSafeArea1.png)
112
113### Example 2
114
115```ts
116// xxx.ets
117@Entry
118@Component
119struct SafeAreaExample {
120  @State text: string = ''
121  controller: TextInputController = new TextInputController()
122
123  build() {
124    Row() {
125      Stack() {
126        Column()
127          .height('100%').width('100%')
128          .backgroundImage($r('app.media.bg')).backgroundImageSize(ImageSize.Cover)
129          .expandSafeArea([SafeAreaType.KEYBOARD, SafeAreaType.SYSTEM])
130        Column() {
131          Button('Set caretPosition 1')
132            .onClick(() => {
133              this.controller.caretPosition(1)
134            })
135          TextInput({ text: this.text, placeholder: 'input your word...', controller: this.controller })
136            .placeholderFont({ size: 14, weight: 400 })
137            .width(320).height(40).offset({y: 120})
138            .fontSize(14).fontColor(Color.Black)
139            .backgroundColor(Color.White)
140        }.width('100%').alignItems(HorizontalAlign.Center)
141      }
142    }.height('100%')
143  }
144}
145```
146
147![expandSafeArea2](figures/expandSafeArea2.png)
148
149### Example 3
150
151```ts
152// EntryAbility.ets
153import { KeyboardAvoidMode } from '@kit.ArkUI';
154
155onWindowStageCreate(windowStage: window.WindowStage) {
156  // Main window is created, set main page for this ability
157  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
158
159  windowStage.loadContent('pages/Index', (err, data) => {
160    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
161    // When the virtual keyboard is displayed, the page is resized to its original height minus the keyboard height.
162  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE);
163    if (err.code) {
164      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
165      return;
166    }
167    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
168  });
169}
170```
171
172```ts
173// xxx.ets
174@Entry
175@Component
176struct KeyboardAvoidExample {
177  build() {
178    Column() {
179      Row().height("30%").width("100%").backgroundColor(Color.Gray)
180      TextArea().width("100%").borderWidth(1)
181      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
182    }.width('100%').height("100%")
183  }
184}
185```
186
187![keyboardAvoidMode1](figures/keyboardAvoidMode1.jpg)
188
189### Example 4
190
191```ts
192// EntryAbility.ets
193import { KeyboardAvoidMode } from '@kit.ArkUI';
194
195onWindowStageCreate(windowStage: window.WindowStage) {
196  // Main window is created, set main page for this ability
197  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
198
199  windowStage.loadContent('pages/Index', (err, data) => {
200    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
201    // When the virtual keyboard is displayed, the page is moved up until the caret is displayed.
202  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET);
203    if (err.code) {
204      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
205      return;
206    }
207    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
208  });
209}
210```
211
212```ts
213// xxx.ets
214@Entry
215@Component
216struct KeyboardAvoidExample {
217  build() {
218    Column() {
219      Row().height("30%").width("100%").backgroundColor(Color.Gray)
220      TextArea().width("100%").borderWidth(1)
221      Text("I can see the bottom of the page").width("100%").textAlign(TextAlign.Center).backgroundColor(Color.Pink).layoutWeight(1)
222    }.width('100%').height("100%")
223  }
224}
225```
226
227![keyboardAvoidMode1](figures/keyboardAvoidMode2.jpg)
228