> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# popup

浮层弹出组件，从屏幕边缘滑入的容器，支持顶部、底部、左侧、右侧等方向。

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=popup"
  title="组件示例 popup"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 popup](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Fpopup%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>adjustExitTransitionByContentHeight</td><td><code>boolean</code></td><td>false</td><td>否</td><td>根据内容高度动态调整退出动画。启用后，屏幕上的动画持续时间保持不变。因此，内容高度越大，退出速度越快，以确保动画在固定时间内完成。</td></tr>
<tr><td>allowDragBeyondBottom</td><td><code>boolean</code></td><td>false</td><td>否</td><td>如果为 true，则允许组件在拖动时超出底部边界。</td></tr>
<tr><td>autoHeight</td><td><code>boolean</code></td><td>-</td><td>否</td><td>自动弹窗高度，设置为 true 时，需要指定 contentId 属性，弹窗高度会根据内容高度动态变化，拖动区域在底部和当前高度之间，initHeight 和 maxHeight 不再有效</td></tr>
<tr><td>bottomNode</td><td><code>ReactElement&lt;any, string | JSXElementConstructor&lt;any&gt;&gt;</code></td><td>-</td><td>否</td><td>固定在弹窗底部的节点，不会受到拖动影响</td></tr>
<tr><td>children</td><td><code>(prop: RenderFunction) =&gt; ReactElement</code></td><td>-</td><td>是</td><td>弹窗的子元素</td></tr>
<tr><td>closeOnMaskClick</td><td><code>boolean</code></td><td>true</td><td>否</td><td>设置为 true 时，点击遮罩会关闭弹窗</td></tr>
<tr><td>contentId</td><td><code>string</code></td><td>-</td><td>否</td><td>弹窗内容的 ID, 在 autoHeight 为 true 时需要设置，用于获取内容高度</td></tr>
<tr><td>contentStyle</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>弹窗内容的样式</td></tr>
<tr><td>enableBounces</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否需要松手回弹</td></tr>
<tr><td>enableDrag</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否启用拖动</td></tr>
<tr><td>enableScrollContainerDraggable</td><td><code>boolean</code></td><td>true</td><td>否</td><td>是否允许触摸在内部滚动容器区域时可拖拽Popup</td></tr>
<tr><td>enterDuration</td><td><code>number</code></td><td>300</td><td>否</td><td>进入动画持续时间（毫秒）</td></tr>
<tr><td>enterEasingFunction</td><td><code>string</code></td><td>'all ease-out'</td><td>否</td><td>显示动画过渡效果</td></tr>
<tr><td>exitDuration</td><td><code>number</code></td><td>300</td><td>否</td><td>退出动画持续时间（毫秒）</td></tr>
<tr><td>exitEasingFunction</td><td><code>string</code></td><td>'all ease-out'</td><td>否</td><td>隐藏动画过渡效果</td></tr>
<tr><td>heightPercent</td><td><code>HeightPercent</code></td><td>-</td><td>否</td><td>弹窗的高度百分比</td></tr>
<tr><td>main-thread:gesture</td><td><code>BaseGesture&lt;BaseGestureConfig, GestureChangeEvent&gt;</code></td><td>-</td><td>否</td><td>如果你想使用手势，请使用这个属性</td></tr>
<tr><td>maskEventThrough</td><td><code>boolean</code></td><td>false</td><td>否</td><td>当设置为true的时候，遮罩事件会传递到子元素</td></tr>
<tr><td>maskStyle</td><td><code>CSSProperties</code></td><td>-</td><td>否</td><td>遮罩的样式</td></tr>
<tr><td>maxHeight</td><td><code>number</code></td><td>screenHeight</td><td>是</td><td>理论上能拖拽到的最大高度，当使用overlayMode时需要传入屏幕高度，当不使用overlayMode时，需要传入当前LynxView的高度</td></tr>
<tr><td>onDrag</td><td><code>(eventParam: OnDragCallback) =&gt; void</code></td><td>-</td><td>否</td><td>拖动回调</td></tr>
<tr><td>onPopupPositionChange</td><td><code>(position: number) =&gt; void</code></td><td>-</td><td>否</td><td>弹窗位置回调</td></tr>
<tr><td>onPopupTopChange</td><td><code>(height: number) =&gt; void</code></td><td>-</td><td>否</td><td>弹窗高度变化回调</td></tr>
<tr><td>onRequestClose</td><td><code>() =&gt; void</code></td><td>-</td><td>否</td><td>是否左滑或者点击返回键</td></tr>
<tr><td>preload</td><td><code>boolean</code></td><td>true</td><td>否</td><td>弹窗创建时预加载，这样在 visible 为 true 时会加快显示速度</td></tr>
<tr><td>ref</td><td><code>ForwardedRef&lt;PopupRef&gt;</code></td><td>-</td><td>否</td><td>-</td></tr>
<tr><td>scrollContainerId</td><td><code>string</code></td><td>-</td><td>是</td><td>根节点滚动容器的 ID（必需）</td></tr>
<tr><td>stopGesturePropagationWhenScrollAtTop</td><td><code>boolean</code></td><td>false</td><td>否</td><td>当滚动容器滚动到顶部时，停止滚动容器的手势事件传播。</td></tr>
</tbody>
</table>

## Ref 方法

<table>
<thead>
<tr><th width="180">方法名</th><th width="260">类型</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>close</td><td><code>() =&gt; void</code></td><td>关闭弹窗</td></tr>
<tr><td>open</td><td><code>(position?: PopupStatus) =&gt; void</code></td><td>打开弹窗, 弹窗位置 0（中心）1（顶部）-1（底部）,默认是中心</td></tr>
<tr><td>setScrollContainerScrollEnabled</td><td><code>(enabled: boolean) =&gt; Promise&lt;void&gt;</code></td><td>不受当前弹窗位置限制，设置滚动容器是否允许原生滚动：true 允许，false 禁止。主线程调用完成后返回的 Promise 才会完成。滚动容器首次收到触摸前调用无效，后续手势仍可能改变此设置。</td></tr>
<tr><td>translateTo</td><td><code>(position: string | PopupStatus) =&gt; void</code></td><td>移动弹窗到指定位置，0（中心）1（顶部）-1（底部）</td></tr>
</tbody>
</table>
