!17879 Add a description of the modal interface

Merge pull request !17879 from wanyanglan/master

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

@@ -46,6 +46,9 @@
     - [图像球面效果设置](ts-universal-attributes-sphericalEffect.md)
     - [图像渐亮效果设置](ts-universal-attributes-lightUpEffect.md)
     - [图像像素扩展效果设置](ts-universal-attributes-pixelStretchEffect.md)
+    - 模态转场设置
+      - [全屏模态转场](ts-universal-attributes-modal-transition.md)
+      - [半模态转场](ts-universal-attributes-sheet-transition.md)
   - [文本通用属性](ts-universal-attributes-text-style.md)
   - 手势处理
     - [绑定手势方法](ts-gesture-settings.md)

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

@@ -233,4 +233,14 @@
 | left     | [Length](#length) | 否    | 组件图像左边沿扩展距离。 |
 | right    | [Length](#length) | 否    | 组件图像右边沿像素扩展距离。 |
 | top  | [Length](#length) | 否    | 组件图像上边沿像素扩展距离。 |
-| bottom | [Length](#length) | 否    | 组件图像下边沿像素扩展距离。 |
\ No newline at end of file
+| bottom | [Length](#length) | 否    | 组件图像下边沿像素扩展距离。 |
+
+## ModalTransition<sup>10+</sup>
+
+全屏模态转场方式枚举类型，用于设置全屏模态转场类型。
+
+| 名称        | 描述      |
+| ---------  | ------- |
+| None  | 全屏模态无转场动画。 |
+| Default  | 全屏模态上下切换动画。 |
+| Alpha  | 全屏模态透明度渐变动画。 |
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-modal-transition.md

+# 全屏模态转场设置
+
+通过bindContentCover属性为组件绑定全屏模态页面，在组件插入和删除时可通过设置转场参数ModalTransition显示过渡动效。
+
+>  **说明：**
+>
+> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+
+## 属性
+
+| 名称 | 参数    | 参数描述 |
+| -------- | -------- | -------- |
+| bindContentCover | isShow: boolean,<br>builder: [CustomBuilder](ts-types.md#custombuilder8),<br>type?: [ModalTransition](ts-types.md#modaltransition10) | 给组件绑定全屏模态页面，点击后显示模态页面。模态页面内容自定义，显示方式可设置无动画过渡，上下切换过渡以及透明渐变过渡方式。<br/> isShow: 必填，是否显示全屏模态页面。<br/>builder: 必填，配置全屏模态页面内容。<br/> type: 非必填，配置全屏模态页面的转场方式。 |
+
+## 示例
+
+### 示例1
+
+全屏模态无动画转场模式下，自定义转场动画。
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct ModalTransitionExample {
+  @State isShow:boolean = false
+  @State isShow2:boolean = false
+
+  @Builder myBuilder2() {
+    Column() {
+      Button("close modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Orange)
+  }
+
+  @Builder myBuilder() {
+    Column() {
+      Button("transition modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = true;
+        }).bindContentCover($$this.isShow2, this.myBuilder2(), ModalTransition.NONE)
+
+      Button("close modal 1")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Pink)
+    .justifyContent(FlexAlign.Center)
+  }
+
+  build() {
+    Column() {
+      Button("transition modal 1")
+        .onClick(() => {
+          this.isShow = true
+        })
+        .fontSize(20)
+        .margin(10)
+        .bindContentCover($$this.isShow, this.myBuilder(), ModalTransition.NONE)
+    }
+    .justifyContent(FlexAlign.Center)
+    .backgroundColor("#ff49c8ab")
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+![zh-cn_full_screen_modal_none_1](figures/zh-cn_full_screen_modal_none_1.gif)
+
+### 示例2
+
+全屏模态无动画转场模式下，自定义转场动画。
+
+```ts
+// xxx.ets
+import curves from '@ohos.curves';
+@Entry
+@Component
+struct ModalTransitionExample {
+  @State  @Watch("isShow1Change") isShow:boolean = false
+  @State  @Watch("isShow2Change") isShow2:boolean = false
+  @State isScale1:number = 1;
+  @State isScale2:number = 1;
+  @State flag: boolean = true
+  @State show: string = 'show'
+
+  isShow1Change() {
+    this.isShow ? this.isScale1 = 0.95 : this.isScale1 = 1
+  }
+  isShow2Change() {
+    this.isShow2 ? this.isScale2 = 0.95 : this.isScale2 = 1
+  }
+  @Builder myBuilder2() {
+    Column() {
+      Button("close modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Orange)
+  }
+
+
+  @Builder myBuilder() {
+    Column() {
+      Button("transition modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = true;
+        }).bindContentCover($$this.isShow2, this.myBuilder2(), ModalTransition.NONE)
+
+      Button("close modal 1")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Pink)
+    .justifyContent(FlexAlign.Center)
+    .scale({x: this.isScale2, y: this.isScale2})
+    .animation({curve:curves.springMotion()})
+  }
+
+  build() {
+    Column() {
+      Button("transition modal 1")
+        .onClick(() => {
+          this.isShow = true
+        })
+        .fontSize(20)
+        .margin(10)
+        .bindContentCover($$this.isShow, this.myBuilder(), ModalTransition.NONE)
+    }
+    .justifyContent(FlexAlign.Center)
+    .backgroundColor("#ff49c8ab")
+    .width('100%')
+    .height('100%')
+    .scale({ x: this.isScale1, y: this.isScale1 })
+    .animation({ curve: curves.springMotion() })
+  }
+}
+```
+
+![zh-cn_full_screen_modal_none_2](figures/zh-cn_full_screen_modal_none_2.gif)
+
+### 示例3
+
+全屏模态上下切换转场。
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct ModalTransitionExample {
+  @State isShow:boolean = false
+  @State isShow2:boolean = false
+
+  @Builder myBuilder2() {
+    Column() {
+      Button("close modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Gray)
+  }
+
+  @Builder myBuilder() {
+    Column() {
+      Button("transition modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = true;
+        }).bindContentCover(this.isShow2, this.myBuilder2(), ModalTransition.DEFAULT)
+
+      Button("close modal 1")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Pink)
+    .justifyContent(FlexAlign.Center)
+  }
+
+  build() {
+    Column() {
+      Button("transition modal 1")
+        .onClick(() => {
+          this.isShow = true
+        })
+        .fontSize(20)
+        .margin(10)
+        .bindContentCover($$this.isShow, this.myBuilder(), ModalTransition.DEFAULT)
+    }
+    .justifyContent(FlexAlign.Center)
+    .backgroundColor(Color.White)
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+![zh-cn_full_screen_modal_default](figures/zh-cn_full_screen_modal_default.gif)
+
+### 示例4
+
+全屏模态透明度渐变转场。
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct ModalTransitionExample {
+  @State isShow:boolean = false
+  @State isShow2:boolean = false
+
+  @Builder myBuilder2() {
+    Column() {
+      Button("close modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Gray)
+    .justifyContent(FlexAlign.Center)
+  }
+
+
+  @Builder myBuilder() {
+    Column() {
+      Button("transition modal 2")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow2 = true;
+        }).bindContentCover(this.isShow2, this.myBuilder2(), ModalTransition.ALPHA)
+
+      Button("close modal 1")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor(Color.Pink)
+    .justifyContent(FlexAlign.Center)
+  }
+
+  build() {
+    Column() {
+      Button("transition modal 1")
+        .onClick(() => {
+          this.isShow = true
+        })
+        .fontSize(20)
+        .margin(10)
+        .bindContentCover($$this.isShow, this.myBuilder(), ModalTransition.ALPHA)
+    }
+    .justifyContent(FlexAlign.Center)
+    .backgroundColor(Color.White)
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+![zh-cn_full_screen_modal_alpha](figures/zh-cn_full_screen_modal_alpha.gif)
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-sheet-transition.md

+# 半模态转场
+
+通过bindSheet属性为组件绑定半模态页面，在组件插入时可通过设置自定义或默认的内置高度确定半模态大小。
+
+>  **说明： **
+>
+> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+
+## 属性
+
+| 名称 | 参数   | 参数描述 |
+| -------- | -------- | -------- |
+| bindSheet | isShow: boolean,<br>builder: [CustomBuilder](ts-types.md#custombuilder8),<br>sheetStyle?: [SheetStyle](#sheetstyle10) | 给组件绑定半模态页面，点击后显示模态页面。isShow: 必填，是否显示半模态页面。<br/>builder: 必填，配置半模态页面内容。<br/> sheetStyle: 非必填，配置半模态页面高度和是否显示控制条，默认高度是Large，默认显示控制条。 |
+
+## SheetStyle<sup>10+</sup>
+
+| 名称               | 类型                                   | 必填 | 描述                   |
+| ------------------ | -------------------------------------- | ---- | ---------------------- |
+| height             | [SheetSize](#sheetsize10)&nbsp;\|&nbsp;[Length](ts-types.md#length) | 否 | 半模态高度。          |
+| showDragBar        | boolean                                | 否   | 是否显示控制条。          |
+
+## SheetSize<sup>10+</sup>
+
+| 名称 | 参数描述 |
+| -------- | -------- |
+| MEDIUM   | 指定半模态高度为屏幕高度一半。 |
+| LARGE    | 指定半模态高度几乎为屏幕高度。 |
+
+## 示例
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct SheetTransitionExample {
+  @State isShow:boolean = false
+  @State isShow2:boolean = false
+  @State sheetHeight:number = 300;
+  @State showDragBar:boolean = true;
+
+  @Builder myBuilder() {
+    Column() {
+      Button("change height")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.sheetHeight = 500;
+        })
+
+      Button("Set Illegal height")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.sheetHeight = null;
+        })
+
+      Button("close dragBar")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.showDragBar = false;
+        })
+
+      Button("close modal 1")
+        .margin(10)
+        .fontSize(20)
+        .onClick(()=>{
+          this.isShow = false;
+        })
+    }
+    .width('100%')
+    .height('100%')
+  }
+
+  build() {
+    Column() {
+      Button("transition modal 1")
+        .onClick(() => {
+          this.isShow = true
+        })
+        .fontSize(20)
+        .margin(10)
+        .bindSheet($$this.isShow, this.myBuilder(), {height: this.sheetHeight, dragBar: this.showDragBar})
+    }
+    .justifyContent(FlexAlign.Center)
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+![zh-cn_sheet](figures/zh-cn_sheet.gif)
\ No newline at end of file