1# 半模态转场 2 3通过bindSheet属性为组件绑定半模态页面，在组件插入时可通过设置自定义或默认的内置高度确定半模态大小。 4 5> **说明：** 6> 7> 从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 不支持路由跳转。 10 11## bindSheet 12 13bindSheet(isShow: Optional\<boolean\>, builder: CustomBuilder, options?: SheetOptions) 14 15给组件绑定半模态页面，点击后显示模态页面。 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21**参数：** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| ------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 25| isShow | Optional\<boolean\> | 是 | 是否显示半模态页面。<br/>从API version 10开始，该参数支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 | 26| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 配置半模态页面内容。 | 27| options | [SheetOptions](#sheetoptions) | 否 | 配置半模态页面的可选属性。 | 28 29> **说明：** 30> 31> 1. 在非双向绑定情况下，以拖拽方式关闭半模态页面不会改变isShow参数的值。 32> 33> 2. 为了使isShow参数值与半模态界面的状态同步，建议使用[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定isShow参数。 34> 35> 3. 在半模态单挡位向上拖拽或是多挡位上滑换挡情况下，内容在拖拽结束或换挡结束后更新显示区域。 36> 37> 4. 半模态是一个严格和宿主节点绑定在一起的弹窗。若是想实现类似“页面显示的瞬间就弹出半模态”的效果，请确认宿主节点是否已挂载上树。若宿主节点还没上树就将isShow置为true，半模态将不生效。建议使用[onAppear](ts-universal-events-show-hide.md#onappear)函数，确保在宿主节点挂载后再显示半模态。 38> 尤其是 [SheetMode](#sheetmode12) = EMBEDDED 时，除宿主节点外，还需确保对应的页面节点成功挂载。 39> 40> 5. 半模态页面的离场动效不支持打断，动效执行期间无法响应其他手势动作。目前离场动效使用[弹簧曲线](../../../ui/arkts-spring-curve.md)，该动画曲线存在视觉上并不明显的拖尾动画。因此，在半模态退出时，视觉上半模态页面已经消失，但此时动效可能还未结束，若想再次点击拉起半模态页面则不会响应。需要等动效完全结束后，才可以再次拉起。 41> 42## SheetOptions 43 44继承自[BindOptions](#bindoptions)。 45 46| 名称 | 类型 | 必填 | 描述 | 47| --------------- | ---------------------------------------- | ---- | --------------- | 48| height | [SheetSize](#sheetsize枚举说明) \| [Length](ts-types.md#length) | 否 | 半模态高度，默认是LARGE。<br/>**说明：**<br/>API version 12之前，底部弹窗横屏时该属性设置无效，高度为距离屏幕顶部8vp。<br/>API version 12开始，底部弹窗横屏时该属性设置生效，最大高度为距离屏幕顶部8vp。<br/>API version 14开始，底部弹窗横屏时，无状态栏则最大高度为距离屏幕顶部8vp，有状态栏则最大高度为距离状态栏8vp。<br/>底部弹窗时，当设置detents时，该属性设置无效。<br/>底部弹窗竖屏时，最大高度为距离状态栏8vp。<br />居中弹窗和跟手弹窗设置类型为SheetSize.LARGE和SheetSize.MEDIUM无效，显示默认高度560vp。居中弹窗和跟手弹窗最小高度为320vp，最大高度为窗口短边的90%。当使用Length设置的高度和使用SheetSize.FIT_CONTENT自适应的高度大于最大高度，则显示最大高度，小于最小高度，则显示最小高度。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 49| detents<sup>11+</sup> | [([SheetSize](#sheetsize枚举说明) \| [Length](ts-types.md#length)), ( [SheetSize](#sheetsize枚举说明) \| [Length](ts-types.md#length))?, ([SheetSize](#sheetsize枚举说明) \| [Length](ts-types.md#length))?] | 否 | 半模态页面的切换高度档位。<br/>**说明：**<br/>从API version 12开始，底部弹窗横屏时该属性设置生效。<br/>底部弹窗竖屏生效，元组中第一个高度为初始高度。<br />面板可跟手滑动切换档位，松手后是否滑动至目标档位有两个判断条件：速度和距离。速度超过阈值，则执行滑动至与手速方向一致的目标档位；速度小于阈值，则引入距离判断条件，当位移距离>当前位置与目标位置的1/2，滑动至与手速方向一致的目标档位，位移距离当前位置与目标位置的1/2，返回至当前档位。速度阈值：1000，距离阈值：50%。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 50| preferType<sup>11+</sup> | [SheetType](#sheettype11枚举说明) | 否 | 半模态页面的样式。<br/>**说明：**<br/>半模态在不同窗口所支持的显示类型：<br/>1. 宽度 < 600vp：底部。<br/>2. 600vp <= 宽度 < 840vp：底部、居中。默认居中样式。<br/>3. 宽度 >= 840vp：底部、居中、跟手。默认跟手样式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 51| showClose<sup>11+</sup> | boolean \| [Resource](ts-types.md#resource) | 否 | 是否显示关闭图标，默认显示。<br/> 2in1设备默认无按钮底板。<br/>**说明：**<br/>Resource需要为boolean类型。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 52| dragBar | boolean | 否 | 是否显示控制条。<br/>**说明：**<br/>半模态面板的detents属性设置多个不同高度并且设置生效时，默认显示控制条。否则不显示控制条。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 53| blurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 半模态面板的模糊背景。默认无模糊背景。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 54| maskColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 半模态页面的背景蒙层颜色。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 55| title<sup>11+</sup> | [SheetTitleOptions](#sheettitleoptions11) \| [CustomBuilder](ts-types.md#custombuilder8) | 否 | 半模态面板的标题。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| enableOutsideInteractive<sup>11+</sup> | boolean | 否 | 半模态所在页面是否允许交互。<br/>**说明：**<br/>设置为true时允许交互，不显示蒙层；设置为false时不允许交互，显示蒙层；若不进行设置，默认底部弹窗与居中弹窗不允许交互，跟手弹窗允许交互。当设置为true时，maskColor设置无效。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 57| shouldDismiss<sup>11+</sup> | (sheetDismiss: [SheetDismiss](#sheetdismiss11)) => void | 否 | 半模态页面交互式关闭回调函数。<br/>**说明：**<br/>当用户执行下拉关闭、触发back事件、点击遮罩层关闭或关闭按钮的交互操作时，如果已注册回调函数，模态窗口将不会立即关闭。要关闭半模态，需在回调函数中调用shouldDismiss.dismiss()方法来实现。<br/>如果不注册该回调函数，则用户执行下拉关闭、触发back事件、点击遮罩层关闭或关闭按钮的交互操作时，正常关闭半模态，无其他行为。<br/>建议在[二次确认](../../../ui/arkts-sheet-page.md#二次确认能力)场景使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 58| onWillDismiss<sup>12+</sup> | [DismissSheetAction](#dismisssheetaction12) | 否 | 半模态页面的交互式关闭回调函数允许开发者注册，以获取关闭操作的类型，并决定是否关闭半模态状态。<br/>**说明：**<br />当用户触发关闭操作时，若已注册回调函数，则不会立即关闭页面，而是由开发者通过回调函数中的[reason](../js-apis-promptAction.md#dismissreason12枚举说明)参数判断关闭操作的类型，进而根据具体原因自主选择是否关闭半模态页面。<br/>如果不注册该回调函数，则用户执行关闭操作时，正常关闭半模态，无其他行为。<br />在onWillDismiss回调中，不能再做onWillDismiss拦截。<br />建议在[二次确认](../../../ui/arkts-sheet-page.md#二次确认能力)场景使用。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 59| onWillSpringBackWhenDismiss<sup>12+</sup> | [SpringBackAction](#springbackaction12) | 否 | 半模态页面交互式关闭前控制回弹函数允许开发者注册，以控制半模态页面交互式关闭时的回弹效果。<br/>**说明：**<br />当用户触发执行下拉关闭操作并同时注册该回调函数与shouldDimiss或onWillDismiss时，由开发者控制下滑关闭时是否回弹。在回调函数中可以通过调用springBack来实现回弹效果。也可以通过不调用springBack来取消回弹效果。<br />若不注册该回调函数，但注册shouldDimiss或onWillDismiss时，则默认在下滑关闭时，会触发回弹效果，回弹后再根据shouldDimiss或onWillDismiss内的回调行为决定半模态是否关闭。<br />如果不注册该回调函数，且未注册shouldDimiss或onWillDismiss时，默认在下滑关闭时，触发半模态关闭。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 60| onHeightDidChange<sup>12+</sup> | Callback<number> | 否 | 半模态页面高度变化回调函数。<br/>**说明：**<br/>底部弹窗时，只有档位变化和拖拽跟手才返回每一帧高度，拉起半模态和避让软键盘只返回最后的高度，其他弹窗只在半模态拉起返回最后高度。<br/>返回值为px。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 61| onDetentsDidChange<sup>12+</sup> | Callback<number> | 否 | 半模态页面档位变化回调函数。<br/>**说明：**<br/>底部弹窗时，档位变化返回最后的高度。<br/>返回值为px。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 62| onWidthDidChange<sup>12+</sup> | Callback<number> | 否 | 半模态页面宽度变化回调函数。<br/>**说明：**<br/>宽度变化时返回最后的宽度。<br/>返回值为px。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 63| onTypeDidChange<sup>12+</sup> | Callback<[SheetType](#sheettype11枚举说明)> | 否 | 半模态页面形态变化回调函数。<br/>**说明：**<br/>形态变化时返回最后的形态。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 64| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup> | 否 | 设置半模态页面的边框宽度。<br />可分别设置4个边框宽度。<br />默认值：0<br /> 百分比参数方式：以父元素半模态页面宽的百分比来设置半模态页面的边框宽度。<br />当半模态页面左边框和右边框大于半模态页面宽度，半模态页面上边框和下边框大于半模态页面高度，显示可能不符合预期。<br />**说明：**<br />底部弹窗时，底部边框宽度设置无效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 65| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) \| [LocalizedEdgeColors](ts-types.md#localizededgecolors12)<sup>12+</sup> | 否 | 设置半模态页面的边框颜色。<br/>默认值：Color.Black<br/> 如果使用borderColor属性，需要和borderWidth属性一起使用。 <br />**说明：**<br />底部弹窗时，底部边框颜色设置无效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 66| borderStyle<sup>12+</sup> | [BorderStyle](ts-appendix-enums.md#borderstyle) \| [EdgeStyles](ts-types.md#edgestyles9) | 否 | 设置半模态页面的边框样式。<br/>默认值：BorderStyle.Solid<br/>如果使用borderStyle属性，需要和borderWidth属性一起使用。 <br />**说明：**<br />底部弹窗时，底部边框样式设置无效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 67| width<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置半模态页面的宽度。<br /> 百分比参数方式：以父元素宽的百分比来设置半模态页面的宽度。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 68| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置半模态页面的阴影。<br />2in1设备默认值：ShadowStyle.OUTER_FLOATING_SM。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 69| uiContext<sup>12+</sup> | [UIContext](../js-apis-arkui-UIContext.md#uicontext) | 否 | 在UIContext实例对应的窗口中显示半模态。<br />**说明：**<br />使用[openBindSheet](../js-apis-arkui-UIContext.md#openbindsheet12)启动的半模态页面，不支持设置、更新该属性。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 70| mode<sup>12+</sup> | [SheetMode](#sheetmode12) | 否 | 设置半模态页面的显示层级。<br/>默认值：SheetMode.OVERLAY<br />**说明：**<br /> 1. 半模态显示期间mode属性不支持动态切换，两种模式的显示层级完全不同，无法做到显示期间同一个半模态从一个层级变换到另一个层级。建议在使用时明确诉求固定mode值。 <br/> 2. 设置SheetMode.EMBEDDED时不支持设置UIContext属性，两者对应的半模态显示层级效果互相冲突。<br />3. 使用[openBindSheet](../js-apis-arkui-UIContext.md#openbindsheet12)启动半模态页面，若未传入有效的targetId，则不支持设置为SheetMode.EMBEDDED，默认为SheetMode.OVERLAY。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 71| scrollSizeMode<sup>12+</sup> | [ScrollSizeMode](#scrollsizemode12) | 否 | 设置半模态面板滑动时，内容区域刷新时机。<br/>默认值：ScrollSizeMode.FOLLOW_DETENT | 72| keyboardAvoidMode<sup>13+</sup> | [SheetKeyboardAvoidMode](#sheetkeyboardavoidmode13枚举说明) | 否 | 设置半模态激活输入法时对软键盘的避让方式。<br/> **默认值：** TRANSLATE_AND_SCROLL<br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 73| enableHoverMode<sup>14+</sup> | boolean | 否 | 是否响应悬停态。<br />默认值：false，默认不响应。<br />**说明：**<br />底部弹窗样式和跟手弹窗样式不响应悬停态。| 74| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype14) | 否 | 悬停态下弹窗默认展示区域。<br />默认值：HoverModeAreaType.BOTTOM_SCREEN| 75 76## SheetSize枚举说明 77 78| 名称 | 值 | 参数描述 | 79| ------------------------- | ---- | -------------------------------- | 80| MEDIUM | 0 | 指定半模态高度为屏幕高度一半。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 81| LARGE | 1 | 指定半模态高度几乎为屏幕高度。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 82| FIT_CONTENT<sup>11+</sup> | 2 | 指定半模态高度为适应内容的高度。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 83 84## BindOptions 85 86| 名称 | 类型 | 必填 | 说明 | 87| --------------- | ------------------------------------------ | ---- | ------------------------ | 88| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 半模态页面的背板颜色。<br />默认值：Color.White。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 89| onWillAppear<sup>12+</sup> | () => void | 否 | 半模态页面显示（动画开始前）回调函数。**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 90| onAppear | () => void | 否 | 半模态页面显示（动画结束后）回调函数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 91| onWillDisappear<sup>12+</sup> | () => void | 否 | 半模态页面回退（动画开始前）回调函数。<br />**说明：**<br />不允许在onWillDisappear函数中修改状态变量，可能会导致组件行为不稳定。**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 92| onDisappear | () => void | 否 | 半模态页面回退（动画结束后）回调函数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 93 94## SheetType<sup>11+</sup>枚举说明 95 96**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 97 98| 名称 | 值 | 参数描述 | 99| ------ | ---- | ------------------------------------------------------ | 100| BOTTOM | 0 | 底部弹窗。 | 101| CENTER | 1 | 居中弹窗。 | 102| POPUP | 2 | 跟手弹窗。跟手弹窗面板不支持跟手滑动，下滑面板不关闭。 | 103 104## SheetDismiss<sup>11+</sup> 105 106**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 107 108| 名称 | 类型 | 必填 | 描述 | 109| ------- | ---------- | ---- | ------------------------------------------------------------ | 110| dismiss | () => void | 是 | 半模态面板关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 111 112## SheetTitleOptions<sup>11+</sup> 113 114**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 115 116| 名称 | 类型 | 必填 | 描述 | 117| -------- | -------------------------------------- | ---- | -------------------- | 118| title | [ResourceStr](ts-types.md#resourcestr) | 是 | 半模态面板的主标题。 | 119| subtitle | [ResourceStr](ts-types.md#resourcestr) | 否 | 半模态面板的副标题。 | 120 121## SheetMode<sup>12+</sup> 122 123**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 124 125| 名称 | 值 | 参数描述 | 126| ------------------------- | ---- | -------------------------------- | 127| OVERLAY | 0 | 设置半模态面板在当前UIContext内顶层显示，在所有页面之上。和弹窗类组件显示在一个层级。 | 128| EMBEDDED | 1 | 设置半模态面板在当前页面内的顶层显示。 <br />**说明：**<br />目前只支持挂载在Page或者NavDestination节点上，若有NavDestination优先挂载在NavDestination上。只支持在这两种页面内顶层显示。<br /> 该模式下新起的页面可以覆盖在半模态弹窗上，页面返回后该半模态依旧存在，半模态面板内容不丢失。 <br /> 该模式下需确保目标页面节点如Page节点已挂载上树，再拉起半模态，否则半模态将无法挂载到对应的页面节点内。| 129 130## ScrollSizeMode<sup>12+</sup> 131| 名称 | 值 | 参数描述 | 132| ------------------------- | ---- | -------------------------------- | 133| FOLLOW_DETENT | 0 | 设置半模态面板跟手滑动结束后更新内容显示区域。 | 134| CONTINUOUS | 1 | 设置半模态面板在滑动过程中持续更新内容显示区域。| 135 136## DismissSheetAction<sup>12+</sup> 137 138**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 139 140| 名称 | 类型 | 必填 | 描述 | 141| --------------- | ---------------------------------------- | ---- | ------------- | 142| dismiss | function | 是 | 半模态页面关闭回调函数。开发者需要退出页面时调用。 | 143| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12枚举说明) | 是 | 返回本次半模态页面退出的操作类型。 | 144 145## SpringBackAction<sup>12+</sup> 146 147| 名称 | 类型 | 必填 | 描述 | 148| --------------- | ---------------------------------------- | ---- | ------------- | 149| springBack | function | 是 | 半模态页面关闭前控制回弹函数，开发者需要半模态回弹时调用。 | 150 151## SheetKeyboardAvoidMode<sup>13+</sup>枚举说明 152 153| 名称 | 值 | 描述 | 154| ------------------------- | ---- | -------------------------------- | 155| NONE | 0 | 设置半模态不避让软键盘。 | 156| TRANSLATE_AND_RESIZE | 1 | 设置半模态先上抬面板避让软键盘；<br/>当上抬至最大高度仍不足以避让软键盘时，则通过压缩整体内容完成避让。| 157| RESIZE_ONLY | 2 | 设置半模态通过压缩整体内容避让软键盘。| 158| TRANSLATE_AND_SCROLL | 3 | 设置半模态先上抬面板避让软键盘；<br/>当上抬至最大高度仍不足以避让软键盘时，则通过滚动内容完成避让。| 159 160## 示例 161### 示例1（不同高度的半模态弹窗） 162 163该示例通过height设置不同高度的半模态弹窗。 164 165```ts 166// xxx.ets 167@Entry 168@Component 169struct SheetTransitionExample { 170 @State isShow: boolean = false 171 @State isShow2: boolean = false 172 @State sheetHeight: number = 300; 173 174 @Builder 175 myBuilder() { 176 Column() { 177 Button("change height") 178 .margin(10) 179 .fontSize(20) 180 .onClick(() => { 181 this.sheetHeight = 500; 182 }) 183 184 Button("Set Illegal height") 185 .margin(10) 186 .fontSize(20) 187 .onClick(() => { 188 this.sheetHeight = -1; 189 }) 190 191 Button("close modal 1") 192 .margin(10) 193 .fontSize(20) 194 .onClick(() => { 195 this.isShow = false; 196 }) 197 } 198 .width('100%') 199 .height('100%') 200 } 201 202 build() { 203 Column() { 204 Button("transition modal 1") 205 .onClick(() => { 206 this.isShow = true 207 }) 208 .fontSize(20) 209 .margin(10) 210 .bindSheet($$this.isShow, this.myBuilder(), { 211 height: this.sheetHeight, 212 backgroundColor: Color.Green, 213 onWillAppear: () => { 214 console.log("BindSheet onWillAppear.") 215 }, 216 onAppear: () => { 217 console.log("BindSheet onAppear.") 218 }, 219 onWillDisappear: () => { 220 console.log("BindSheet onWillDisappear.") 221 }, 222 onDisappear: () => { 223 console.log("BindSheet onDisappear.") 224 } 225 }) 226 } 227 .justifyContent(FlexAlign.Center) 228 .width('100%') 229 .height('100%') 230 } 231} 232``` 233 234 235 236### 示例2（设置三个不同高度的档位） 237 238使用bindSheet的detents属性设置三个不同高度的档位。 2391、dragBar拖拽条只在多个档位高度时生效； 2402、区别于height属性在不同时刻设置不同档位的能力，多档位能力有手势切换档位高度的效果，且更适合固定高度区间的场景； 2413、若高度范围不确定，且可能存在大于3个不同高度的场景，不建议使用detents属性。 242 243```ts 244// xxx.ets 245@Entry 246@Component 247struct SheetTransitionExample { 248 @State isShow: boolean = false 249 250 @Builder 251 myBuilder() { 252 Column() { 253 Button("content1") 254 .margin(10) 255 .fontSize(20) 256 257 Button("content2") 258 .margin(10) 259 .fontSize(20) 260 } 261 .width('100%') 262 } 263 264 build() { 265 Column() { 266 Button("transition modal 1") 267 .onClick(() => { 268 this.isShow = true 269 }) 270 .fontSize(20) 271 .margin(10) 272 .bindSheet($$this.isShow, this.myBuilder(), { 273 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 274 backgroundColor: Color.Gray, 275 blurStyle: BlurStyle.Thick, 276 showClose: true, 277 title: { title: "title", subtitle: "subtitle" }, 278 }) 279 } 280 .justifyContent(FlexAlign.Start) 281 .width('100%') 282 .height('100%') 283 } 284} 285``` 286 287 288 289### 示例3（使用边框宽度和颜色） 290 291bindSheet属性的borderWidth、borderColor属性值使用LocalizedEdgeWidths类型和LocalizedEdgeColors类型。 292 293```ts 294// xxx.ets 295import { LengthMetrics } from '@kit.ArkUI' 296 297@Entry 298@Component 299struct SheetTransitionExample { 300 @State isShow: boolean = false 301 302 @Builder 303 myBuilder() { 304 Column() { 305 Button("content1") 306 .margin(10) 307 .fontSize(20) 308 309 Button("content2") 310 .margin(10) 311 .fontSize(20) 312 } 313 .width('100%') 314 } 315 316 build() { 317 Column() { 318 Button("transition modal 1") 319 .onClick(() => { 320 this.isShow = true 321 }) 322 .fontSize(20) 323 .margin(10) 324 .bindSheet($$this.isShow, this.myBuilder(), { 325 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 326 backgroundColor: Color.Gray, 327 blurStyle: BlurStyle.Thick, 328 showClose: true, 329 title: { title: "title", subtitle: "subtitle" }, 330 borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) }, 331 borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow }, 332 }) 333 } 334 .justifyContent(FlexAlign.Start) 335 .width('100%') 336 .height('100%') 337 } 338} 339``` 340 341从左至右显示语言模式示例图 342 343 344 345从右至左显示语言模式示例图 346 347 348 349### 示例4（使用关闭回调函数） 350 351bindSheet注册onWillDismiss与onWillSpringBackWhenDismiss。 352 353```ts 354// xxx.ets 355@Entry 356@Component 357struct bindSheetExample { 358 @State isShow: Boolean = false; 359 360 @Builder 361 myBuilder() { 362 Column() { 363 Button() { 364 Text("CONTEXT") 365 }.height(50) 366 } 367 } 368 369 build() { 370 Column() { 371 Button("NoRegisterSpringback") 372 .onClick(() => { 373 this.isShow = true 374 }) 375 .fontSize(20) 376 .margin(10) 377 .bindSheet($$this.isShow, this.myBuilder(), { 378 height: SheetSize.MEDIUM, 379 blurStyle: BlurStyle.Thick, 380 showClose: true, 381 title: { title: "title", subtitle: "subtitle" }, 382 preferType: SheetType.CENTER, 383 384 385 onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 386 if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) { 387 DismissSheetAction.dismiss() //注册dismiss行为 388 } 389 }), 390 391 onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { 392 //没有注册springBack, 下拉半模态页面无回弹行为 393 //SpringBackAction.springBack() 394 }), 395 }) 396 } 397 } 398} 399``` 400 401 402### 示例5（设置内容区刷新时机） 403 404ScrollSizeMode.CONTINUOUS 持续更新内容适合detents多档位切换场景。 405建议在builder内减少UI加载耗时的操作，滑动时内容实时刷新对性能要求较高。 406 407```ts 408// xxx.ets 409@Entry 410@Component 411struct Index { 412 @State isShow: boolean = false; 413 414 @Builder 415 myBuilder() { 416 Column() { 417 Column() 418 .backgroundColor(Color.Blue) 419 .height(200) 420 .width('100%') 421 Column() 422 .backgroundColor(Color.Green) 423 .height(200) 424 .width('100%') 425 } 426 } 427 428 build() { 429 Column() { 430 Button('BindSheet') 431 .onClick(() => { 432 this.isShow = true; 433 }) 434 .bindSheet($$this.isShow, this.myBuilder(), { 435 detents: [300, 600, 900], 436 uiContext: this.getUIContext(), 437 mode: SheetMode.OVERLAY, 438 scrollSizeMode: ScrollSizeMode.CONTINUOUS, 439 backgroundColor: Color.Orange, 440 title: { title: 'Title', subtitle: 'Subtitle' } 441 }) 442 } 443 .justifyContent(FlexAlign.Center) 444 .width('100%') 445 .height('100%') 446 } 447} 448``` 449跟手触发档位切换时，松手才触发面板内容高度刷新 450 451 452 453跟手触发档位切换时，跟手时期就会触发面板内容高度刷新 454 455 456 457### 示例6（监测键盘高度变化） 458 459在resizeOnly模式下，监测键盘高度变化并根据高度变化做滚动组件的滚动。 460 461```ts 462//xxx.ets 463import { window } from '@kit.ArkUI'; 464import { BusinessError } from '@kit.BasicServicesKit'; 465 466@Entry 467@Component 468struct ListenKeyboardHeightChange { 469 @State isShow: boolean = false; 470 @State avoidMode: SheetKeyboardAvoidMode = SheetKeyboardAvoidMode.RESIZE_ONLY; 471 scroller = new Scroller(); 472 private arr: number[] = [0, 1, 2, 3, 4, 5, 6]; 473 @State scrollHeight: number = 0; 474 @State keyBoardChange: boolean = false; 475 windowClass: window.Window | undefined = undefined; 476 477 aboutToAppear(): void { 478 try { 479 window.getLastWindow(getContext(this), (err: BusinessError, data) => { 480 const errCode: number = err.code; 481 if (errCode) { 482 console.error(`Failed to obtain the top window, Cause code: ${err.code}, message: ${err.message}`); 483 return; 484 } 485 this.windowClass = data; 486 try { 487 if (this.windowClass !== undefined) { 488 console.log('success in listen height change'); 489 //注册键盘高度变化监听回调 490 this.windowClass.on('keyboardHeightChange', this.callback); 491 } 492 } catch (exception) { 493 console.error(`Failed to enable the listener for keyboard height changes, Cause code: ${exception.code}, message: ${exception.message}`); 494 } 495 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 496 }); 497 } catch (exception) { 498 console.error(`Failed to obtain the top window, Cause code: ${exception.code}, message: ${exception.message}`); 499 } 500 } 501 502 //当键盘高度变化时，设置相应标志位 503 callback = (height: number) => { 504 this.scrollHeight = height; 505 console.log('height change: ' + this.scrollHeight); 506 if (height !== 0) { 507 this.keyBoardChange = true; 508 } 509 } 510 //当滚动组件高度变化时，根据标志位触发滚动 511 sizeChangeCallback = (oldValue: SizeOptions, newValue: SizeOptions) => { 512 if (this.keyBoardChange) { 513 this.scroller.scrollBy(0, this.scrollHeight); 514 this.keyBoardChange = false; 515 } 516 } 517 518 @Builder 519 myBuilder() { 520 Scroll(this.scroller) { 521 Column() { 522 ForEach(this.arr, (item: number) => { 523 Row() { 524 Text(item.toString()) 525 .width('80%') 526 .height(60) 527 .backgroundColor('#3366CC') 528 .borderRadius(15) 529 .fontSize(16) 530 .textAlign(TextAlign.Center) 531 .margin({ top: 5 }) 532 } 533 }, (item: number) => item.toString()) 534 535 TextInput().height('100') 536 537 Flex({ alignItems: ItemAlign.End }) { 538 Row() { 539 Button("click") 540 .margin(10) 541 .fontSize(20) 542 .width('45%') 543 544 Button("cancel") 545 .margin(10) 546 .fontSize(20) 547 .width('45%') 548 }.width('100%') 549 }.height('100%') 550 }.margin({ right: 15 }) 551 } 552 .scrollBar(BarState.On) 553 .scrollable(ScrollDirection.Vertical) 554 .onSizeChange(this.sizeChangeCallback) 555 } 556 557 build() { 558 Column() { 559 Button("transition modal 1") 560 .onClick(() => { 561 this.isShow = true 562 }) 563 .fontSize(20) 564 .margin(10) 565 .bindSheet($$this.isShow, this.myBuilder(), { 566 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 567 backgroundColor: Color.Gray, 568 blurStyle: BlurStyle.Thick, 569 showClose: true, 570 title: { title: "title", subtitle: "subtitle" }, 571 keyboardAvoidMode: SheetKeyboardAvoidMode.RESIZE_ONLY 572 }) 573 } 574 .justifyContent(FlexAlign.Start) 575 .width('100%') 576 .height('100%') 577 } 578} 579```
