0%

vue-fullscreen

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

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

npm version language

npm version language

npm download license

vue-fullscreen for vue3

在线演示

使用示例

支持

浏览器支持

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

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

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

了解更多

从<=2.3.5版本迁移

组件

一般情况下你可以直接使用双向绑定来修改组件全屏状态了,无需直接调用组件的内部方法。

background属性已移除,你可以直接在组件上设置样式。

Api

wrapperbackground等与它相关的配置项已移除,它们使用场景有限,可定制性不强,而且你可以自己简单地实现它。

方法名更改如下:

enter request
support isEnabled
getState() isFullscreen

安装

使用npm命令安装

1
npm install vue-fullscreen

使用

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

组件和api会被一起安装到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
<template>
<div>
<fullscreen :fullscreen.sync="fullscreen">
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>
import VueFullscreen from 'vue-fullscreen'
import Vue from 'vue'
Vue.use(VueFullscreen)
export default {
methods: {
toggle () {
this.fullscreen = !this.fullscreen
},
toggleApi () {
this.$fullscreen.toggle(this.$el.querySelector('.fullscreen-wrapper'), {
teleport: this.teleport,
callback: (isFullscreen) => {
this.fullscreen = isFullscreen
},
})
},
},
data() {
return {
fullscreen: false,
teleport: true,
pageOnly: false,
}
}
}
</script>

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

以api形式使用

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

或者你可以单独引入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
<template>
<div>
<div class="fullscreen-wrapper">
Content
</div>
<button type="button" @click="toggle" >Fullscreen</button>
</div>
</template>
<script>
import { api as fullscreen } from 'vue-fullscreen'
export default {
methods: {
toggle () {
fullscreen.toggle(this.$el.querySelector('.fullscreen-wrapper'), {
teleport: this.teleport,
callback: (isFullscreen) => {
this.fullscreen = isFullscreen
},
})
},
},
data() {
return {
fullscreen: false,
teleport: true,
}
}
}
</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下。

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

以组件形式使用

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

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
<template>
<div>
<fullscreen :fullscreen.sync="fullscreen" :teleport="teleport" :page-only="pageOnly" >
Content
</fullscreen>
<button type="button" @click="toggle" >Fullscreen</button>
</div>
</template>
<script>
import { component } from 'vue-fullscreen'
export default {
components: {
fullscreen: component,
},
methods: {
toggle () {
this.fullscreen = !this.fullscreen
},
},
data() {
return {
fullscreen: false,
teleport: true,
pageOnly: false,
}
}
}
</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

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

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>
<fs :fullscreen.sync="fullscreen" :teleport="teleport" :page-only="pageOnly" >
content
</fs>
<button type="button" @click="toggle" >Fullscreen</button>
<div class="fullscreen-wrapper">
content
</div>
<button type="button" @click="toggleApi" >FullscreenApi</button>
</div>
</template>
<script>
import VueFullscreen from 'vue-fullscreen'
import Vue from 'vue'
Vue.use(VueFullscreen, {name: 'fs'})
export default {
methods: {
toggle () {
this.fullscreen = !this.fullscreen
},
toggleApi() {
this.$fs.toggle(this.$el.querySelector('.fullscreen-wrapper'), {
teleport: this.teleport,
callback: (isFullscreen) => {
this.fullscreen = isFullscreen
},
})
},
},
data() {
return {
fullscreen: false,
teleport: true,
pageOnly: false,
}
}
}
</script>

如果有一组标题-内容形式的数据需要展现,用table感觉太笨重了一些,最符合语义化的做法应该是使用dl元素。
比如下面这个例子,展现了一个水平列表,样式定义来自bootstrap:

可以看到一个问题,当某些数据没有值时,它所在的dd元素高度会变成0,结果下面行的数据会顶上来,造成串行。

一种笨办法是在数据渲染时强制给所有dd元素一个&nbsp;,利用空格强行撑开元素高度。但是这种做法会影响页面处理逻辑,既麻烦又不整洁。

另一种做法是修改对齐方式:

表面上看是解决了问题,但是当缩小浏览器,使内容过长超出页面宽度导致换行时,就可以发现内容的文字跑到了标题那边,对强迫症来说很难受。

最完美的做法是使用CSS伪类为元素添加内容:

伪类的content属性如果填的是''或者&nbsp;都会被忽略,无法生效。所以这里用的是Unicode的零宽无连接符。\200c\200d分别是零宽无连接符和零宽连接符,分别用于阻止本来会连接的前后两个字符和强行合并本来不会连接的前后两个字符。它们的附加特性非常适合用在这种需要有字符但又希望它看不到的场合。