Vue3全屏切换组件vue-fullscreen

vue-fullscreen

一个用于将任意页面元素进行全屏切换的vue组件，基于 screenfull.js

有任何问题请到github项目页提交issue，博客的留言我可能无法及时看到，谢谢各位支持👍。

vue-fullscreen for vue2

在线演示

使用示例

• 组件形式调用
• api形式调用
• iPhone兼容处理 & 全屏下弹窗
• 跳转到新页面且不退出全屏

支持

浏览器支持

注意: 在IE浏览器下使用需要先实现Promise的polyfill.

注意: Safari浏览器在桌面和iPad下支持，但iPhone不支持.

注意: 当处在全屏模式中，浏览其他页面，切换标签页，或者切换到其他应用（例如使用 Alt-Tab）也会导致退出全屏模式。

了解更多

安装

使用npm命令安装

npm install vue-fullscreen@next

使用

引入vue-fullscreen，并使用app.use()注册插件，之后即可使用。

组件和api会被一起安装到app全局。

import { createApp } from 'vue'
import VueFullscreen from 'vue-fullscreen'
import App from './App.vue'

export const app = createApp(App)
app.use(VueFullscreen)
app.mount('#app')

<template>
<div ref="root">
  <fullscreen v-model:fullscreen="fullscreen" :teleport="teleport" :page-only="pageOnly" >
    content
  </fullscreen>
  <button type="button" @click="toggle" >Fullscreen</button>
  <div class="fullscreen-wrapper">
    content
  </div>
  <button type="button" @click="toggleApi" >FullscreenApi</button>
  </div>
</template>
<script lang="ts">
  import {
    ref,
    defineComponent,
    toRefs,
    reactive,
  } from 'vue'
  export default defineComponent({
    setup() {
      const root = ref()
      const state = reactive({
        fullscreen: false,
        teleport: true,
        pageOnly: false,
      })
      function toggle() {
        state.fullscreen = !state.fullscreen
      }
      function toggleApi() {
        this.$fullscreen.toggle(root.value.querySelector('.fullscreen-wrapper'), {
          teleport: state.teleport,
          callback: (isFullscreen) => {
            state.fullscreen = isFullscreen
          },
        })
      }

      return {
        root,
        ...toRefs(state),
        toggle,
        toggleApi,
      }
    },
  })
</script>

注意: 由于浏览器的安全限制，全屏切换必须由一个用户操作事件发起，比如click或keypress。

以api形式使用

在Vue组件实例中，可以直接调用this.$fullscreen来获取全屏api。

或者你可以单独引入api然后执行它。

<template>
<div ref="root">
  <div class="fullscreen-wrapper">
    Content
  </div>
  <button type="button" @click="toggle" >Fullscreen</button>
  </div>
</template>
<script lang="ts">
  import {
    ref,
    defineComponent,
    toRefs,
    reactive,
  } from 'vue'
  import { api as fullscreen } from 'vue-fullscreen'
  export default defineComponent({
    setup() {
      const root = ref()
      const state = reactive({
        fullscreen: false,
        teleport: true,
      })

      async function toggle () {
        fullscreen.toggle(root.value.querySelector('.fullscreen-wrapper'), {
          teleport: state.teleport,
          callback: (isFullscreen) => {
            state.fullscreen = isFullscreen
          },
        })
      }

      return {
        root,
        ...toRefs(state),
        toggle,
      }
    },
  })
</script>

方法 & 属性

toggle([target, options, force])

切换全屏模式。

• target:
  • 类型: Element
  • 默认值: document.body
  • 全屏操作的目标元素。
• options (可选):
  • 类型: Object
  • 配置项，详见下文。
• force (可选):
  • 类型: Boolean
  • 默认值: undefined
  • 传入true可以指定进入全屏模式，效果与request方法相同，false反之。

request([target, options])

进入全屏模式。

• target:
  • 类型: Element
  • 默认值: document.body
  • 全屏操作的目标元素。
• options (optional):
  • 默认值: Object
  • 配置项，详见下文。

exit()

退出全屏模式。

isFullscreen

判断是否处于全屏状态。

• 类型: Boolean

注意: 唤起全屏的动作是异步的,在调用方法后你无法立即获取预期的结果。

isEnabled

判断环境是否支持全屏API。

• 类型: Boolean

element

获取当前全屏的元素

• 类型: Element | null

Options

callback

• 类型: Function
• 默认值: null

当全屏状态变更时执行。

fullscreenClass

• 类型: String
• 默认值: fullscreen

这个样式会在进入全屏状态时被添加到目标元素上。

pageOnly

• 类型: Boolean
• 默认值: false

如果为true，不调用全屏API，而是将当前元素撑满网页。

注意: 如果浏览器不支持全屏API，这个选项默认值为true.

teleport

• 类型: Boolean
• 默认值: true

如果为true， 进入全屏时目标元素会被移动到document.body下。

这可以避免一些弹窗在全屏模式下看不到的问题。

以组件形式使用

你可以单独引入全屏组件并局部注册它。

<template>
<div>
  <fullscreen v-model:fullscreen="fullscreen" :teleport="teleport" :page-only="pageOnly" >
    Content
  </fullscreen>
  <button type="button" @click="toggle" >Fullscreen</button>
  </div>
</template>

<script lang="ts">
  import {
    defineComponent,
    toRefs,
    reactive,
  } from 'vue'
  import { component } from 'vue-fullscreen'

  export default defineComponent({
    name: 'ComponentExample',
    components: {
      fullscreen: component,
    },
    setup() {
      const state = reactive({
        fullscreen: false,
        teleport: true,
        pageOnly: false,
      })
      function toggle() {
        state.fullscreen = !state.fullscreen
      }

      return {
        ...toRefs(state),
        toggle,
      }
    },
  })
</script>

Props属性

fullscreen-class

• 类型: String
• 默认值: fullscreen

全屏组件的样式类，只有全屏时才生效。

exit-on-click-wrapper

• 类型: Boolean
• 默认值: true

如果为true， 点击全屏组件的空白部分会退出全屏。

page-only

• 类型: Boolean
• 默认值: false

如果为true，不调用全屏API，而是将当前组件撑满网页。

注意: 如果浏览器不支持全屏API，这个选项默认值为true.

teleport

• 类型: Boolean
• 默认值: true

如果为true, 进入全屏时当前组件会被移动到document.body下。

这可以避免一些弹窗在全屏模式下看不到的问题。

事件

change

• isFullscreen: 当前的全屏状态。

在全屏状态改变时触发。

插件配置项

name

• 类型: String
• 默认值: fullscreen

如果你需要避免重名冲突，可以像这样引入:

import { createApp } from 'vue'
import VueFullscreen from 'vue-fullscreen'
import App from './App.vue'

export const app = createApp(App)
app.use(VueFullscreen, {
  name: 'fs',
})
app.mount('#app')

<template>
<div ref="root">
  <fs v-model:fullscreen="fullscreen" :teleport="teleport" :page-only="pageOnly" >
    <div class="fullscreen-wrapper">
      <div>
        <button type="button" class="button" @click="toggle">
          {{ fullscreen ? 'exit fullscreen' : 'request fullscreen' }}
  </button>
        <button type="button" @click="toggleApi" >FullscreenApi</button>
  </div>
      <img v-show="!fullscreen" :src="'//picsum.photos/640/360?random=1'">
      <img v-show="fullscreen" :src="'//picsum.photos/1280/720?random=1'">
  </div>
  </fs>
  </div>
</template>
<script lang="ts">
  import {
    ref,
    defineComponent,
    toRefs,
    reactive
  } from 'vue'
  export default defineComponent({
    methods: {
      toggleApi () {
        this.$fs.toggle(this.$el.querySelector('.fullscreen-wrapper'), {
          teleport: this.teleport,
          callback: (isFullscreen) => {
            this.fullscreen = isFullscreen
          }
        })
      }
    },
    setup () {
      const root = ref()
      const state = reactive({
        fullscreen: false,
        teleport: true,
        pageOnly: false
      })
      function toggle () {
        state.fullscreen = !state.fullscreen
      }

      return {
        root,
        ...toRefs(state),
        toggle
      }
    }
  })
</script>