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| radius<sup>15+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) \| [BorderRadiuses](ts-types.md#borderradiuses9) \| [LocalizedBorderRadiuses](ts-types.md#LocalizedBorderRadiuses12) | 否 | 设置半模态页面圆角半径。<br/>不建议设置4个圆角大小不相等，圆角大小相等时面板视觉体验最佳。<br/>**默认值**：32vp。<br/>**说明：**<br/>1. 根据设置的圆角半径值显示，如果未设置，则使用默认值。底部样式不显示半模态底部2个圆角，即使设置了底部2个圆角也不生效。<br/>2. 分别设置4个方向的圆角半径后，如果某个方向的值异常，异常方向的圆角值重置为默认值，非异常方向的圆角值为已设置的值。统一设置4个方向的圆角时，如果设置的值异常，4个方向的圆角都重置为默认值。<br/>3. 半径设置为百分比时，以半模态页面的宽度为基准。<br/>4. 当圆角的半径大于半模态页面宽度一半时，圆角的半径取值为半模态页面宽度的一半。<br/>5. 当半模态页面高度过小且圆角半径设置过大时，可能导致显示异常。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 76| detentSelection<sup>15+</sup> | [SheetSize](#sheetsize枚举说明) \| [Length](ts-types.md#length) | 否 | 支持非手势切换挡位。<br/>**说明：**<br/>当设置SheetSize.FIT_CONTENT时，该接口无效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 77 78## SheetSize枚举说明 79 80指定半模态的高度。 81 82| 名称 | 值 | 说明 | 83| ------------------------- | ---- | -------------------------------- | 84| MEDIUM | 0 | 指定半模态高度为屏幕高度一半。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 85| LARGE | 1 | 指定半模态高度几乎为屏幕高度。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 86| FIT_CONTENT<sup>11+</sup> | 2 | 指定半模态高度为适应内容的高度。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 87 88## BindOptions 89 90半模态、全模态的公共配置接口。 91 92| 名称 | 类型 | 必填 | 说明 | 93| --------------- | ------------------------------------------ | ---- | ------------------------ | 94| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 半模态页面的背板颜色。<br />默认值：Color.White。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 95| onWillAppear<sup>12+</sup> | () => void | 否 | 半模态页面显示（动画开始前）回调函数。**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 96| onAppear | () => void | 否 | 半模态页面显示（动画结束后）回调函数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 97| onWillDisappear<sup>12+</sup> | () => void | 否 | 半模态页面回退（动画开始前）回调函数。<br />**说明：**<br />不允许在onWillDisappear函数中修改状态变量，可能会导致组件行为不稳定。**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 98| onDisappear | () => void | 否 | 半模态页面回退（动画结束后）回调函数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 99 100## SheetType<sup>11+</sup>枚举说明 101 102半模态弹窗的样式。 103 104**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 105 106| 名称 | 值 | 说明 | 107| ------ | ---- | ------------------------------------------------------ | 108| BOTTOM | 0 | 底部弹窗。 | 109| CENTER | 1 | 居中弹窗。 | 110| POPUP | 2 | 跟手弹窗。跟手弹窗面板不支持跟手滑动，下滑面板不关闭。 | 111 112## SheetDismiss<sup>11+</sup> 113 114控制半模态的关闭。 115 116**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 117 118| 名称 | 类型 | 必填 | 说明 | 119| ------- | ---------- | ---- | ------------------------------------------------------------ | 120| dismiss | () => void | 是 | 半模态面板关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 121 122## SheetTitleOptions<sup>11+</sup> 123 124半模态面板的标题。 125 126**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 127 128| 名称 | 类型 | 必填 | 说明 | 129| -------- | -------------------------------------- | ---- | -------------------- | 130| title | [ResourceStr](ts-types.md#resourcestr) | 是 | 半模态面板的主标题。 | 131| subtitle | [ResourceStr](ts-types.md#resourcestr) | 否 | 半模态面板的副标题。 | 132 133## SheetMode<sup>12+</sup>枚举说明 134 135半模态的显示层级模式。 136 137**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 138 139| 名称 | 值 | 说明 | 140| ------------------------- | ---- | -------------------------------- | 141| OVERLAY | 0 | 设置半模态面板在当前UIContext内顶层显示，在所有页面之上。和弹窗类组件显示在一个层级。 | 142| EMBEDDED | 1 | 设置半模态面板在当前页面内的顶层显示。 <br />**说明：**<br />目前只支持挂载在Page或者NavDestination节点上，若有NavDestination优先挂载在NavDestination上。只支持在这两种页面内顶层显示。<br /> 该模式下新起的页面可以覆盖在半模态弹窗上，页面返回后该半模态依旧存在，半模态面板内容不丢失。 <br /> 该模式下需确保目标页面节点如Page节点已挂载上树，再拉起半模态，否则半模态将无法挂载到对应的页面节点内。| 143 144## ScrollSizeMode<sup>12+</sup>枚举说明 145 146半模态面板上下滑动时的内容更新方式。 147 148| 名称 | 值 | 说明 | 149| ------------------------- | ---- | -------------------------------- | 150| FOLLOW_DETENT | 0 | 设置半模态面板跟手滑动结束后更新内容显示区域。 | 151| CONTINUOUS | 1 | 设置半模态面板在滑动过程中持续更新内容显示区域。| 152 153## DismissSheetAction<sup>12+</sup> 154 155半模态关闭前的回调。 156 157**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 158 159| 名称 | 类型 | 必填 | 说明 | 160| --------------- | ---------------------------------------- | ---- | ------------- | 161| dismiss | function | 是 | 半模态页面关闭回调函数。开发者需要退出页面时调用。 | 162| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12枚举说明) | 是 | 返回本次半模态页面退出的操作类型。 | 163 164## SpringBackAction<sup>12+</sup> 165 166控制半模态关闭前的回弹。 167 168| 名称 | 类型 | 必填 | 说明 | 169| --------------- | ---------------------------------------- | ---- | ------------- | 170| springBack | function | 是 | 半模态页面关闭前控制回弹函数，开发者需要半模态回弹时调用。 | 171 172## SheetKeyboardAvoidMode<sup>13+</sup>枚举说明 173 174| 名称 | 值 | 说明 | 175| ------------------------- | ---- | -------------------------------- | 176| NONE | 0 | 设置半模态不避让软键盘。 | 177| TRANSLATE_AND_RESIZE | 1 | 设置半模态先上抬面板避让软键盘；<br/>当上抬至最大高度仍不足以避让软键盘时，则通过压缩整体内容完成避让。| 178| RESIZE_ONLY | 2 | 设置半模态通过压缩整体内容避让软键盘。| 179| TRANSLATE_AND_SCROLL | 3 | 设置半模态先上抬面板避让软键盘；<br/>当上抬至最大高度仍不足以避让软键盘时，则通过滚动内容完成避让。| 180 181## 示例 182### 示例1（不同高度的半模态弹窗） 183 184该示例通过height设置不同高度的半模态弹窗。 185 186```ts 187// xxx.ets 188@Entry 189@Component 190struct SheetTransitionExample { 191 @State isShow: boolean = false 192 @State sheetHeight: number = 300; 193 194 @Builder 195 myBuilder() { 196 Column() { 197 Button("change height") 198 .margin(10) 199 .fontSize(20) 200 .onClick(() => { 201 this.sheetHeight = 500; 202 }) 203 204 Button("Set Illegal height") 205 .margin(10) 206 .fontSize(20) 207 .onClick(() => { 208 this.sheetHeight = -1; 209 }) 210 211 Button("close modal 1") 212 .margin(10) 213 .fontSize(20) 214 .onClick(() => { 215 this.isShow = false; 216 }) 217 } 218 .width('100%') 219 .height('100%') 220 } 221 222 build() { 223 Column() { 224 Button("transition modal 1") 225 .onClick(() => { 226 this.isShow = true 227 }) 228 .fontSize(20) 229 .margin(10) 230 .bindSheet($$this.isShow, this.myBuilder(), { 231 height: this.sheetHeight, 232 backgroundColor: Color.Green, 233 onWillAppear: () => { 234 console.log("BindSheet onWillAppear.") 235 }, 236 onAppear: () => { 237 console.log("BindSheet onAppear.") 238 }, 239 onWillDisappear: () => { 240 console.log("BindSheet onWillDisappear.") 241 }, 242 onDisappear: () => { 243 console.log("BindSheet onDisappear.") 244 } 245 }) 246 } 247 .justifyContent(FlexAlign.Center) 248 .width('100%') 249 .height('100%') 250 } 251} 252``` 253 254 255 256### 示例2（设置三个不同高度的档位） 257 258使用bindSheet的detents属性设置三个不同高度的档位。 2591、dragBar拖拽条只在多个档位高度时生效； 2602、区别于height属性在不同时刻设置不同档位的能力，多档位能力有手势切换档位高度的效果，且更适合固定高度区间的场景； 2613、若高度范围不确定，且可能存在大于3个不同高度的场景，不建议使用detents属性。 262 263```ts 264// xxx.ets 265@Entry 266@Component 267struct SheetTransitionExample { 268 @State isShow: boolean = false 269 270 @Builder 271 myBuilder() { 272 Column() { 273 Button("content1") 274 .margin(10) 275 .fontSize(20) 276 277 Button("content2") 278 .margin(10) 279 .fontSize(20) 280 } 281 .width('100%') 282 } 283 284 build() { 285 Column() { 286 Button("transition modal 1") 287 .onClick(() => { 288 this.isShow = true 289 }) 290 .fontSize(20) 291 .margin(10) 292 .bindSheet($$this.isShow, this.myBuilder(), { 293 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 294 backgroundColor: Color.Gray, 295 blurStyle: BlurStyle.Thick, 296 showClose: true, 297 title: { title: "title", subtitle: "subtitle" }, 298 }) 299 } 300 .justifyContent(FlexAlign.Start) 301 .width('100%') 302 .height('100%') 303 } 304} 305``` 306 307 308 309### 示例3（使用边框宽度和颜色） 310 311bindSheet属性的borderWidth、borderColor属性值使用LocalizedEdgeWidths类型和LocalizedEdgeColors类型。 312 313```ts 314// xxx.ets 315import { LengthMetrics } from '@kit.ArkUI' 316 317@Entry 318@Component 319struct SheetTransitionExample { 320 @State isShow: boolean = false 321 322 @Builder 323 myBuilder() { 324 Column() { 325 Button("content1") 326 .margin(10) 327 .fontSize(20) 328 329 Button("content2") 330 .margin(10) 331 .fontSize(20) 332 } 333 .width('100%') 334 } 335 336 build() { 337 Column() { 338 Button("transition modal 1") 339 .onClick(() => { 340 this.isShow = true 341 }) 342 .fontSize(20) 343 .margin(10) 344 .bindSheet($$this.isShow, this.myBuilder(), { 345 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 346 backgroundColor: Color.Gray, 347 blurStyle: BlurStyle.Thick, 348 showClose: true, 349 title: { title: "title", subtitle: "subtitle" }, 350 borderWidth: { top: LengthMetrics.vp(10), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) }, 351 borderColor: { top: Color.Pink, start: Color.Blue, end: Color.Yellow }, 352 }) 353 } 354 .justifyContent(FlexAlign.Start) 355 .width('100%') 356 .height('100%') 357 } 358} 359``` 360 361从左至右显示语言模式示例图 362 363 364 365从右至左显示语言模式示例图 366 367 368 369### 示例4（使用关闭回调函数） 370 371bindSheet注册onWillDismiss与onWillSpringBackWhenDismiss。 372 373```ts 374// xxx.ets 375@Entry 376@Component 377struct bindSheetExample { 378 @State isShow: Boolean = false; 379 380 @Builder 381 myBuilder() { 382 Column() { 383 Button() { 384 Text("CONTEXT") 385 }.height(50) 386 } 387 } 388 389 build() { 390 Column() { 391 Button("NoRegisterSpringback") 392 .onClick(() => { 393 this.isShow = true 394 }) 395 .fontSize(20) 396 .margin(10) 397 .bindSheet($$this.isShow, this.myBuilder(), { 398 height: SheetSize.MEDIUM, 399 blurStyle: BlurStyle.Thick, 400 showClose: true, 401 title: { title: "title", subtitle: "subtitle" }, 402 preferType: SheetType.CENTER, 403 404 405 onWillDismiss: ((DismissSheetAction: DismissSheetAction) => { 406 if (DismissSheetAction.reason == DismissReason.SLIDE_DOWN) { 407 DismissSheetAction.dismiss() //注册dismiss行为 408 } 409 }), 410 411 onWillSpringBackWhenDismiss: ((SpringBackAction: SpringBackAction) => { 412 //没有注册springBack, 下拉半模态页面无回弹行为 413 //SpringBackAction.springBack() 414 }), 415 }) 416 } 417 } 418} 419``` 420 421 422### 示例5（设置内容区刷新时机） 423 424ScrollSizeMode.CONTINUOUS 持续更新内容适合detents多档位切换场景。 425建议在builder内减少UI加载耗时的操作，滑动时内容实时刷新对性能要求较高。 426 427```ts 428// xxx.ets 429@Entry 430@Component 431struct Index { 432 @State isShow: boolean = false; 433 434 @Builder 435 myBuilder() { 436 Column() { 437 Column() 438 .backgroundColor(Color.Blue) 439 .height(200) 440 .width('100%') 441 Column() 442 .backgroundColor(Color.Green) 443 .height(200) 444 .width('100%') 445 } 446 } 447 448 build() { 449 Column() { 450 Button('BindSheet') 451 .onClick(() => { 452 this.isShow = true; 453 }) 454 .bindSheet($$this.isShow, this.myBuilder(), { 455 detents: [300, 600, 900], 456 uiContext: this.getUIContext(), 457 mode: SheetMode.OVERLAY, 458 scrollSizeMode: ScrollSizeMode.CONTINUOUS, 459 backgroundColor: Color.Orange, 460 title: { title: 'Title', subtitle: 'Subtitle' } 461 }) 462 } 463 .justifyContent(FlexAlign.Center) 464 .width('100%') 465 .height('100%') 466 } 467} 468``` 469跟手触发档位切换时，松手才触发面板内容高度刷新 470 471 472 473跟手触发档位切换时，跟手时期就会触发面板内容高度刷新 474 475 476 477### 示例6（设置压缩模态内容） 478 479通过设置SheetKeyboardAvoidMode为RESIZE_ONLY，当键盘高度变化时，根据高度变化实现滚动组件的滚动。 480 481```ts 482//xxx.ets 483import window from '@ohos.window'; 484import { BusinessError } from '@ohos.base'; 485 486@Entry 487@Component 488struct ListenKeyboardHeightChange { 489 @State isShow: boolean = false; 490 @State avoidMode: SheetKeyboardAvoidMode = SheetKeyboardAvoidMode.RESIZE_ONLY; 491 scroller = new Scroller(); 492 private arr: number[] = [0, 1, 2, 3, 4, 5, 6]; 493 windowClass: window.Window | undefined = undefined; 494 495 aboutToAppear(): void { 496 try { 497 window.getLastWindow(getContext(this), (err: BusinessError, data) => { 498 const errCode: number = err.code; 499 if (errCode) { 500 console.error(`Failed to obtain the top window, Cause code: ${err.code}, message: ${err.message}`); 501 return; 502 } 503 this.windowClass = data; 504 try { 505 if (this.windowClass !== undefined) { 506 console.log('success in listen height change'); 507 this.windowClass.on('keyboardHeightChange', this.callback); 508 } 509 } catch (exception) { 510 console.error(`Failed to enable the listener for keyboard height changes, Cause code: ${exception.code}, message: ${exception.message}`); 511 } 512 console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data)); 513 }); 514 } catch (exception) { 515 console.error(`Failed to obtain the top window, Cause code: ${exception.code}, message: ${exception.message}`); 516 } 517 } 518 519 callback = (height: number) => { 520 console.log('height change: ' + height); 521 if (height !== 0) { 522 this.scroller.scrollTo({ 523 xOffset: 0, yOffset: height + this.scroller.currentOffset().yOffset, 524 animation: { duration: 1000, curve: Curve.Ease, canOverScroll: false } 525 }); 526 } 527 } 528 529 @Builder 530 myBuilder() { 531 Scroll(this.scroller) { 532 Column() { 533 ForEach(this.arr, (item: number) => { 534 Row() { 535 Text(item.toString()) 536 .width('80%') 537 .height(60) 538 .backgroundColor('#3366CC') 539 .borderRadius(15) 540 .fontSize(16) 541 .textAlign(TextAlign.Center) 542 .margin({ top: 5 }) 543 } 544 }, (item: number) => item.toString()) 545 546 TextInput().height('100') 547 548 Flex({ alignItems: ItemAlign.End }) { 549 Row() { 550 Button("click") 551 .margin(10) 552 .fontSize(20) 553 .width('45%') 554 555 Button("cancel") 556 .margin(10) 557 .fontSize(20) 558 .width('45%') 559 }.width('100%') 560 }.height(100) 561 }.margin({ right: 15, bottom: 50 }) 562 } 563 .height('100%') 564 .scrollBar(BarState.On) 565 .scrollable(ScrollDirection.Vertical) 566 } 567 568 build() { 569 Column() { 570 Button("transition modal 1") 571 .onClick(() => { 572 this.isShow = true 573 }) 574 .fontSize(20) 575 .margin(10) 576 .bindSheet($$this.isShow, this.myBuilder(), { 577 height: 750, 578 backgroundColor: Color.Gray, 579 blurStyle: BlurStyle.Thick, 580 showClose: true, 581 title: { title: "title", subtitle: "subtitle" }, 582 keyboardAvoidMode: SheetKeyboardAvoidMode.RESIZE_ONLY, 583 }) 584 } 585 .justifyContent(FlexAlign.Start) 586 .width('100%') 587 .height('100%') 588 } 589} 590``` 591 592 593### 示例7（镜像场景下如何设置圆角属性） 594 595此示例为说明镜像场景而设置了不同的圆角半径，通常不建议开发者设置不同的值，会造成视觉体验不佳。 596 597其中，半模态的radius属性值使用LocalizedBorderRadiuses类型。 598 599```ts 600import { LengthMetrics } from '@kit.ArkUI'; 601 602@Entry 603@Component 604struct SheetTransitionExample { 605 @State isShow: boolean = false 606 607 @Builder 608 myBuilder() { 609 Column() { 610 Button("content1") 611 .margin(10) 612 .fontSize(20) 613 614 Button("content2") 615 .margin(10) 616 .fontSize(20) 617 } 618 .width('100%') 619 } 620 621 build() { 622 Column() { 623 Button("transition modal 1") 624 .onClick(() => { 625 this.isShow = true 626 }) 627 .fontSize(20) 628 .margin(10) 629 .bindSheet($$this.isShow, this.myBuilder(), { 630 detents: [SheetSize.MEDIUM, SheetSize.LARGE, 200], 631 title: { title: "title", subtitle: "subtitle" }, 632 radius: { topStart: LengthMetrics.vp(50), topEnd: LengthMetrics.vp(10) }, 633 }) 634 } 635 .justifyContent(FlexAlign.Start) 636 .width('100%') 637 .height('100%') 638 } 639} 640``` 641 642从左至右显示语言模式示例图 643 644 645 646从右至左显示语言模式示例图 647 648
