组件

把内容放进组件，控制 v-model 来进入和退出全屏。退出全屏时，绑定的状态会自动变回 false。

演练场

编辑此示例

正在加载示例…

<script setup>
import { ref } from 'vue'
import { Fullscreen } from 'vue-fullscreen'

const isFullscreen = ref(false)

function report(error) {
  isFullscreen.value = false
  console.error(error)
}
</script>

<template>
  <div>
    <button :disabled="isFullscreen" @click="isFullscreen = true">
      进入全屏
    </button>
    <Fullscreen
      v-model="isFullscreen"
      :page-only="false"
      :teleport="true"
      @error="report"
    >
      <button v-if="isFullscreen" @click="isFullscreen = false">
        退出全屏
      </button>
      <!-- 需要全屏的内容 -->
    </Fullscreen>
  </div>
</template>

组件属性（Props）

属性	类型	默认值	说明
modelValue	boolean	false	v-model 绑定值
pageOnly	boolean	false	仅填满网页；不支持原生 API 时自动启用
teleport	boolean	false	全屏期间将元素移动到 body
fullscreenClass	string	'fullscreen'	激活期间的 class
exitOnClickWrapper	boolean	true	点击容器背景退出；点击子元素不会触发

实例属性

通过组件 ref 读取。

属性	类型	作用
isFullscreen	boolean	当前全屏状态
isSupported	boolean	原生全屏是否可用

事件

事件	参数	时机
change	boolean	全屏状态改变
update:modelValue	boolean	同步 v-model
error	错误对象	模型变化或容器点击触发的操作失败

方法

<script setup>
import { ref } from 'vue'
import { Fullscreen } from 'vue-fullscreen'

const panel = ref()
const error = ref('')
async function enter() {
  try {
    await panel.value.enter()
  } catch (reason) {
    error.value = reason.message
  }
}
</script>

<template>
  <button @click="enter">进入全屏</button>
  <Fullscreen ref="panel" page-only>内容</Fullscreen>
  <p v-if="error" role="alert">{{ error }}</p>
</template>

方法	签名	作用
enter	(): Promise<void>	请求全屏
exit	(): Promise<void>	退出全屏
toggle	(force?: boolean): Promise<void>	切换或指定状态

旧版本迁移

使用 enter() 替代 request()，使用 isSupported 替代 isEnabled。旧名称作为兼容入口保留。

旧版的 fullscreen 属性和 update:fullscreen 事件仅作为兼容接口保留，新代码使用 v-model。

// 旧写法
import VueFullscreen from 'vue-fullscreen'
app.use(VueFullscreen)

// 新写法
import { Fullscreen } from 'vue-fullscreen'

<!-- 旧写法 -->
<fullscreen
  :fullscreen="isFullscreen"
  @update:fullscreen="isFullscreen = $event"
/>

<!-- 新写法 -->
<Fullscreen v-model="isFullscreen" />