vue-fullscreen
一个用于将任意页面元素进行全屏切换的vue组件,基于 screenfull.js
有任何问题请到github项目页提交issue,博客的留言我可能无法及时看到,谢谢各位支持👍。



使用示例
支持
浏览器支持
注意: 在IE浏览器下使用需要先实现Promise的polyfill.
注意: Safari浏览器在桌面和iPad下支持,但iPhone不支持.
注意: 当处在全屏模式中,浏览其他页面,切换标签页,或者切换到其他应用(例如使用 Alt-Tab)也会导致退出全屏模式。
了解更多
安装
使用npm命令安装
1
| npm install vue-fullscreen@next
|
使用
引入vue-fullscreen
,并使用app.use()
注册插件,之后即可使用。
组件、指令和api会被一起安装到app全局。
1 2 3 4 5 6 7
| 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')
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
| <template> <div ref="root"> <!-- Component --> <fullscreen v-model="fullscreen"> content </fullscreen> <!-- Api --> <button type="button" @click="toggleApi" >FullscreenApi</button> <!-- Directive --> <button type="button" v-fullscreen >FullscreenDirective</button> </div> </template> <script lang="ts"> import { ref, defineComponent, toRefs, reactive } from 'vue' export default defineComponent({ methods: { toggleApi () { this.$fullscreen.toggle() } }, setup () { const root = ref() const state = reactive({ fullscreen: false, }) function toggle () { state.fullscreen = !state.fullscreen } return { root, ...toRefs(state), toggle } } }) </script>
|
注意: 由于浏览器的安全限制,全屏切换必须由一个用户操作事件发起,比如click
或keypress
。
以api形式使用
在Vue组件实例中,可以直接调用this.$fullscreen
来获取全屏api。
1
| this.$fullscreen.toggle()
|
或者你可以单独引入api然后执行它。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
| <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 (可选):
- force (可选):
- 类型:
Boolean
- 默认值:
undefined
- 传入
true
可以指定进入全屏模式,效果与request
方法相同,false
反之。
request([target, options])
进入全屏模式。
- target:
- 类型:
Element
- 默认值:
document.body
- 全屏操作的目标元素。
- options (optional):
exit()
退出全屏模式。
注意: 这些方法都会返回一个Promise对象,你可以在Promise执行完成后获取状态,或者在options中传入一个回调函数来获取。
1 2 3 4
| async toggle () { await this.$fullscreen.toggle() this.fullscreen = this.$fullscreen.isFullscreen }
|
isFullscreen
判断是否处于全屏状态。
注意: 唤起全屏的动作是异步的,在调用方法后你无法立即获取预期的结果。
isEnabled
判断环境是否支持全屏API。
element
获取当前全屏的元素
Options
callback
当全屏状态变更时执行。
fullscreenClass
- 类型:
String
- 默认值:
fullscreen
这个样式会在进入全屏状态时被添加到目标元素上。
pageOnly
如果为true
,不调用全屏API,而是将当前元素撑满网页。
注意: 如果浏览器不支持全屏API,这个选项默认值为true.
teleport
如果为true
, 进入全屏时目标元素会被移动到document.body
下。
这可以避免一些弹窗在全屏模式下看不到的问题。
以指令形式使用
你可以使用v-fullscreen
使任意元素拥有点击切换全屏的效果
1
| <button v-fullscreen>FullScreen</button>
|
或者你可以单独引入指令并安装它。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
| <template> <div> <div class="fullscreen-wrapper"> Content </div> <button type="button" v-fullscreen.teleport="options" >Fullscreen</button> </div> </template> <script lang="ts"> import { ref, defineComponent, toRefs, reactive } from 'vue' import { directive as fullscreen } from 'vue-fullscreen' export default defineComponent({ directives: { fullscreen }, setup () { const root = ref() const state = reactive({ options: { target: ".fullscreen-wrapper", callback (isFullscreen) { console.log(isFullscreen) }, }, }) return { root, ...toRefs(state), toggle } } }) </script>
|
修饰符
pageOnly
不调用全屏API,而是将当前元素撑满网页。
teleport
进入全屏时目标元素会被移动到document.body
下。
这可以避免一些弹窗在全屏模式下看不到的问题。
配置项
target
- 类型:
String | Element
- 默认值:
document.body
全屏操作的目标元素。可以使用样式选择器字符串来指定元素,相当于document.querySelector(target)
。注意直接传递元素对象时,需要确保该元素已存在。指令被初始化时,当前组件的内部元素可能尚未初始化。
callback
当全屏状态变更时执行。
fullscreenClass
- 类型:
String
- 默认值:
fullscreen
这个样式会在进入全屏状态时被添加到目标元素上。
以组件形式使用
你可以单独引入全屏组件并局部注册它。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
| <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
如果为true
, 点击全屏组件的空白部分会退出全屏。
page-only
如果为true
,不调用全屏API,而是将当前组件撑满网页。
注意: 如果浏览器不支持全屏API,这个选项默认值为true.
teleport
如果为true
, 进入全屏时当前组件会被移动到document.body
下。
这可以避免一些弹窗在全屏模式下看不到的问题。
事件
change
在全屏状态改变时触发。
插件配置项
name
- 类型:
String
- 默认值:
fullscreen
如果你需要避免重名冲突,可以像这样引入:
1 2 3 4 5 6 7 8 9
| 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')
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
| <template> <div ref="root"> <!-- Component --> <fs v-model="fullscreen"> content </fs> <!-- Api --> <button type="button" @click="toggleApi" >FullscreenApi</button> <!-- Directive --> <button type="button" v-fs >FullscreenDirective</button> </div> </template> <script lang="ts"> import { ref, defineComponent, toRefs, reactive } from 'vue' export default defineComponent({ methods: { toggleApi () { this.$fs.toggle() } }, setup () { const root = ref() const state = reactive({ fullscreen: false, }) function toggle () { state.fullscreen = !state.fullscreen } return { root, ...toRefs(state), toggle } } }) </script>
|