Iframe 嵌入页面

avue-iframe 为嵌入页面提供加载、超时、错误和空状态，并封装了刷新、聚焦与跨窗口消息通信能力。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space wrap :size="12">
    <el-button type="primary" @click="reload">重新加载</el-button>
    <el-button @click="sendMessage">通知子页面</el-button>
  </el-space>
  <div class="iframe-demo__content">
    <avue-iframe
      ref="iframeRef"
      src="/examples/iframe-child.html"
      :timeout="10000"
      @load="appendLog('页面加载完成')"
      @message="handleMessage"
      @timeout="appendLog('页面加载超时')"
    />
  </div>
  <div class="iframe-demo__log">{{ log }}</div>
</template>

<script setup>
import { ref } from 'vue';

const iframeRef = ref();
const log = ref('等待子页面消息…');

const appendLog = (message) => {
  log.value = `${new Date().toLocaleTimeString()} ${message}`;
};

const reload = () => {
  iframeRef.value?.reload();
};

const sendMessage = () => {
  iframeRef.value?.postMessage(
    { type: 'notice', content: '来自父页面的消息' },
    window.location.origin,
  );
};

const handleMessage = ({ data, origin }) => {
  if (origin !== window.location.origin) return;
  appendLog(`收到子页面消息：${JSON.stringify(data)}`);
};
</script>

<style scoped>
.iframe-demo__content {
  height: 240px;
  margin-top: 16px;
  border: 1px solid var(--el-border-color);
}

.iframe-demo__log {
  margin-top: 12px;
  color: var(--el-text-color-secondary);
  font-size: 13px;
}
</style>

Attributes

参数	说明	类型	可选值	默认值
src	页面地址	string	-	''
name	iframe 名称	string	-	-
title	iframe 标题	string	-	嵌入页面
width	容器宽度，数字会自动追加 px	string / number	-	100%
height	容器高度，数字会自动追加 px	string / number	-	100%
showLoading	是否显示加载态	boolean	true / false	true
loadingText	加载提示文本	string	-	页面加载中...
timeout	加载超时时间，单位 ms；0 表示不启用	number	-	0
timeoutText	超时提示文本	string	-	页面加载超时
errorText	加载失败提示文本	string	-	页面加载失败

Events

事件名	说明	回调参数
before-load	开始加载或刷新前触发	{ src, iframe, window }
load	iframe 加载完成时触发	{ src, iframe, window }
ready	iframe 加载完成时触发，与 load 同时触发	{ src, iframe, window }
error	iframe 加载失败时触发	{ src, iframe, window, error }
timeout	达到 timeout 后仍未加载完成时触发	{ src, iframe, window, timeout }
reload	调用 reload 后触发	{ src, iframe, window }
message	收到当前 iframe 窗口发出的消息时触发	{ data, origin, source }

Slots

插槽名	说明	插槽参数
empty	src 为空时的内容	-
error	加载失败或超时时的内容	{ error, timedOut, reload }

Methods

通过组件 ref 调用。

方法名	说明	参数
reload	重新创建并加载 iframe	返回 boolean
focus	聚焦 iframe 窗口	返回 boolean
postMessage	向 iframe 发送消息；无可用窗口时返回 false，成功调用后返回 true	data, targetOrigin = '*', transfer?
getIframe	获取当前 iframe DOM；未挂载时为 null	无
getWindow	获取 iframe 的 contentWindow；未挂载时为 null	无

通信安全

跨窗口通信时请传入明确的 targetOrigin，不要在生产环境使用默认的 '*'。在 message 回调中还应校验 origin 和消息数据结构，避免处理来自非受信页面的消息。

加载与布局说明

height="100%" 需要父容器具有明确高度，也可直接传 :height="300"。src 为空时显示空状态，reload() 返回 false。

before-load 在开始加载时触发，此时 DOM 或窗口可能尚未就绪；刷新期间也可能仍引用旧 iframe。需要操作新窗口时，在 load 或 ready 后取实例。ready 与原生加载事件同步，不代表子页面内的业务数据已经加载完成；业务就绪可由子页面通过消息主动通知。

服务端渲染项目请把启用超时的 iframe 放在客户端渲染边界内，例如 VuePress 的 ClientOnly。跨域页面受浏览器同源策略约束，组件不会绕过该限制，也不会把所有外部属性自动转发给内部 iframe。