!20450 [新需求]: 【SafeArea】补充文档

Merge pull request !20450 from zhaoxinyu/safeArea

zh-cn/application-dev/reference/arkui-ts/Readme-CN.md

@@ -51,6 +51,7 @@
     - [隐私遮罩](ts-universal-attributes-obscured.md)
     - [文本通用](ts-universal-attributes-text-style.md)
     - [拖拽控制](ts-universal-attributes-drag-drop.md)
+    - [安全区域](ts-universal-attributes-expand-safe-area.md)
   - 手势处理
     - [绑定手势方法](ts-gesture-settings.md)
     - 基础手势

zh-cn/application-dev/reference/arkui-ts/ts-types.md

@@ -319,3 +319,23 @@ Swiper组件动画相关信息集合。
 | currentOffset | number | Swiper当前显示元素在主轴方向上，相对于Swiper起始位置的位移。单位VP，默认值为0.|
 | targetOffset | number | Swiper动画目标元素在主轴方向上，相对于Swiper起始位置的位移。单位VP，默认值为0.|
 | velocity | number | Swiper离手动画开始时的离手速度。单位VP/S，默认值为0.|
+## SafeAreaType<sup>10+</sup>
+
+扩展安全区域的枚举类型。
+
+| 名称     | 描述                                       |
+| -------- | ------------------------------------------ |
+| SYSTEM   | 系统默认非安全区域，包括状态栏、导航栏。   |
+| CUTOUT   | 设备的非安全区域，例如刘海屏或挖孔屏区域。 |
+| KEYBOARD | 软键盘区域。                               |
+
+## SafeAreaEdge<sup>10+</sup>
+
+扩展安全区域的方向。
+
+| 名称   | 描述       |
+| ------ | ---------- |
+| TOP    | 上方区域。 |
+| BOTTOM | 下方区域。 |
+| START  | 前部区域。 |
+| END    | 尾部区域。 |

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-expand-safe-area.md

+# 安全区域
+
+通过expandSafeArea属性支持组件扩展其安全区域。
+
+> **说明：**
+>
+> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+
+## 属性
+
+| 名称           | 参数                           | 参数描述                                |
+| -------------- | ----------------------------- | --------------------------------------- |
+| expandSafeArea | type?: Array <[SafeAreaType](ts-types.md#safeareatype10)>,<br />edges?: Array <[SafeAreaEdge](ts-types.md#safeareaedge10)> | 控制组件扩展其安全区域。<br />默认值: <br />type: [SafeAreaType.SYSTEM, SafeAreaType.CUTOUT, SafeAreaType.KEYBOARD],<br />edges: [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM, SafeAreaEdge.START, SafeAreaEdge.END]<br />扩展至所有非安全区域。<br />type: 非必填，配置扩展安全区域的类型。<br />edges: 非必填，配置扩展安全区域的方向。 |
+
+## 示例
+
+### 示例1
+
+```
+// 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%')
+  }
+}
+```
+
+![expandSafeArea1](figures/expandSafeArea1.png)
+
+### 示例2
+
+```
+@Entry
+@Component
+struct SafeAreaExample {
+  @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%')
+  }
+}
+```
+
+![expandSafeArea2](figures/expandSafeArea2.png)