> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landerlab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 Popup API 控制弹窗

> 通过按钮、链接和自定义代码打开、关闭和切换 LanderLab 弹窗。包含 JavaScript API 以及无代码打开/关闭链接的完整参考。

Popup API 让你可以用代码控制任意弹窗，而不只依赖内置触发器（页面加载、延时、滚动、退出意图）。在 Custom Code 元素或任意脚本中调用 `window.llPopupsApi`，即可通过按钮打开弹窗、在表单提交后关闭弹窗，或把弹窗接入你自己的集成。

<Note>
  **使用弹窗的 ID，而不是名称。** API 中的所有操作都通过 `id` 定位弹窗。弹窗**名称**（你在编辑器中看到的易读标签）只是用于数据分析和显示的元数据，绝不会用于定位。如果你按名称定位，什么都不会发生。
</Note>

## 第 1 步 - 准备弹窗

在用代码控制弹窗之前，先做好设置，避免它与你的触发器冲突，并给它一个可以引用的 ID。

<Steps>
  <Step title="将触发器设为 Manual">
    在右侧栏的 **Popup** 标签页中，将 **Trigger** 设为 **Manual**（仅按钮触发）。弹窗永远不会自动打开，只有在你的链接或脚本打开它时才会出现。

    <Tip>
      你并不是\_必须\_使用 Manual。无论弹窗设置了什么触发器，API 都能正常工作。Manual 只是确保弹窗在你亲自打开之前一直保持关闭。
    </Tip>
  </Step>

  <Step title="复制弹窗的 ID">
    每个弹窗都已有一个唯一 ID。要找到它，打开左侧栏中的 **Popups** 面板，点击弹窗旁边的**三个点（操作）**，然后选择 **Copy ID**。在 API 需要弹窗 ID 的地方粘贴这个值即可。

    <Frame>
      <img src="https://mintcdn.com/landerlab-babdc23f/fgP40icRWa6qGg0H/images/image-35.png?fit=max&auto=format&n=fgP40icRWa6qGg0H&q=85&s=f28dda295445ca5b6f2491081455ef51" alt="在 Popups 面板中通过操作菜单复制弹窗 ID" width="599" height="575" data-path="images/image-35.png" />
    </Frame>
  </Step>
</Steps>

## JavaScript API（`window.llPopupsApi`）

调用全局对象 `window.llPopupsApi` 来打开、关闭或切换弹窗：可以在自定义事件发生时、在你控制的延时之后，或从其他脚本中调用。把代码放进页面上的 **Custom Code** 元素即可。

```javascript theme={null}
// 打开指定弹窗
window.llPopupsApi.open('promo-popup-id');
```

### 定位：ID 可选

每个方法都接受一个**可选的**弹窗 ID：

* **传入 ID** → 操作只作用于该弹窗。
* **省略 ID** → 操作作用于页面上的**所有弹窗**。

```javascript theme={null}
window.llPopupsApi.close('promo-popup-id'); // 关闭一个弹窗
window.llPopupsApi.close();              // 关闭页面上的所有弹窗
```

### 方法

| 方法 | 作用 |
| - | - |
| `open(id?)` | 强制打开弹窗。即使访客在本次会话中早些时候关闭过它，也会重新打开（你的显式调用优先）。 |
| `close(id?)` | 以动画效果关闭弹窗。**不会**设置 “stay dismissed” cookie，弹窗之后仍可再次被触发。 |
| `dismiss(id?)` | 关闭弹窗**并**锁定它：如果开启了 **Stay Dismissed**，会设置 30 天的 cookie；如果开启了 **Show Once**，会设置会话标记。内置关闭按钮执行的就是这个操作。 |
| `toggle(id?)` | 弹窗关闭时打开它，打开时关闭它。（通过 toggle 打开属于强制打开，与 `open` 相同。） |
| `get(id?)` | 传入 ID 时返回该弹窗的 HTML 元素（找不到则返回 `null`）；省略 ID 时返回由所有弹窗元素组成的数组。 |

<Note>
  **`close` 与 `dismiss` 的区别。** `close()` 是临时关闭，exit-intent 等自动触发器之后仍可能再次触发。`dismiss()` 在本次会话中永久生效（开启 **Stay Dismissed** 时最长可达 30 天）。“以后再说”用 `close()`，“不再显示”用 `dismiss()`。
</Note>

### 示例

<CodeGroup>
  ```javascript 从按钮打开 theme={null}
  // 等页面就绪后再绑定事件。
  // DOMContentLoaded 能确保你的按钮和 llPopupsApi 都已存在。
  document.addEventListener('DOMContentLoaded', function () {
    const button = document.getElementById('my-button');

    button.addEventListener('click', function () {
      window.llPopupsApi.open('promo-popup-id');
    });
  });
  ```

  ```javascript 延时关闭 theme={null}
  // 弹窗打开 5 秒后自动关闭
  window.llPopupsApi.open('promo-popup-id');
  setTimeout(function () {
    window.llPopupsApi.close('promo-popup-id');
  }, 5000);
  ```

  ```javascript 切换 / 关闭全部 theme={null}
  // 切换单个弹窗
  window.llPopupsApi.toggle('promo-popup-id');

  // 一次关闭页面上的所有弹窗
  window.llPopupsApi.close();
  ```

  ```javascript 获取弹窗元素 theme={null}
  // 传入 ID 获取单个元素（找不到则为 null）
  const popup = window.llPopupsApi.get('promo-popup-id');

  // 省略 ID 获取页面上所有弹窗组成的数组
  const allPopups = window.llPopupsApi.get();
  ```
</CodeGroup>

## 须知

* **在页面就绪后再运行你的代码。** `window.llPopupsApi` 只有在弹窗脚本加载完成后才存在。把你的调用包裹在 `DOMContentLoaded` 监听器中（就像上面的 **从按钮打开** 示例那样），确保调用时 API 已经可用。
* **预览模式。** 在预览 URL 上，“Stay Dismissed” cookie 和 “Show Once” 标记永远不会被读取或写入，因此测试时弹窗总会出现。
* **按 ESC 关闭。** 如果弹窗启用了 **Close on ESC**，按下 <kbd>Esc</kbd> 会关闭最上层打开的弹窗，无需任何代码。
* **打开优先于关闭锁定。** 即使访客已经关闭并锁定了弹窗，调用 `open()` 仍会重新打开它，但弹窗自身的自动触发器仍会遵守该关闭状态。如果想重新锁定，请使用 `dismiss()`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.