luthe-futian / js-screen-shot

web端自定义截屏插件(原生JS版)

js-web-screen-shot ·

web端自定义截屏插件(原生JS版)，运行视频：实现web端自定义截屏功能 ,效果图如下：

写在前面

关于此插件的更多介绍以及实现原理请移步：

• 实现Web端自定义截屏
• 实现Web端自定义截屏(JS版)

插件安装

yarn add js-web-screen-shot

# or

npm install js-web-screen-shot --save

插件使用

由于插件采用原生js编写且不依赖任何第三方库，因此它可以在任意一台支持js的设备上运行。

注意⚠️： 如果需要使用插件的webrtc模式或者截图写入剪切板功能，需要你的网站运行在https环境或者localhost环境。

import形式使用插件

• 在需要使用截屏插件的业务代码中导入插件

import ScreenShot from "js-web-screen-shot";

• 在业务代码中使用时实例化插件即可

new ScreenShot();

⚠️注意：实例化插件时一定要等dom加载完成，否则插件无法正常工作。

cdn形式使用插件

• 将插件的dist文件夹复制到你的项目中
• 使用script标签引入dist目录下的screenShotPlugin.umd.js文件

<script src="./screenShotPlugin.umd.js"></script>

• 在业务代码中使用时实例化插件即可

    // 截图确认按钮回调函数
    const callback = (base64) =>{
      console.log(base64);
    }
    // 截图取消时的回调函数
    const closeFn = ()=>{
      console.log("截图窗口关闭");
    }
    new screenShotPlugin({enableWebRtc: true, completeCallback: callback,closeCallback: closeFn});

⚠️注意：实例化插件时一定要等dom加载完成，否则插件无法正常工作。

electron环境下使用插件

由于electron环境下无法直接调用webrtc来获取屏幕流，因此需要调用者自己稍作处理，具体做法如下所示：

• 直接获取设备的窗口，主线程发送一个IPC消息handle

// electron主线程
import { desktopCapturer } from "electron";
// 获取设备窗口信息
ipcMain.handle("IPC消息名称", async (_event, _args) => {
  return await desktopCapturer.getSources({ types: ['window', 'screen'] });
});

• 渲染线程(前端)发送消息封装处理(相应写法自己调整)

// xxx.ts
export const getDesktopCapturerSource = async () => {
  return await window.electron.ipcRenderer.invoke<Electron.DesktopCapturerSource[]>("IPC消息名称", []);
}

• 获取指定窗口的媒体流

// yyy.ts
export function getInitStream(source: any): Promise<MediaStream | null> {
    return new Promise((resolve, _reject) => {
        // 获取指定窗口的媒体流
        // 此处遵循的是webRTC的接口类型  暂时TS类型没有支持  只能断言成any
        (navigator.mediaDevices as any).getUserMedia({
            audio: false,
            video: {
                mandatory: {
                    chromeMediaSource: 'desktop',
                    chromeMediaSourceId: source.id
                },
            }
        }).then((stream: MediaStream) => {
            resolve(stream);
        }).catch((error: any) => {
            console.log(error);
            resolve(null);
        })
    });
}

• 前端调用设备窗口信息

import { getDesktopCapturerSource } from "xxx.ts";
import { getInitStream } from "yyy.ts";
import ScreenShot from "js-web-screen-shot";

export const doScreenShot = async ()=>{
  // 下面这两块自己考虑  
  const sources = await getDesktopCapturerSource(); // 这里返回的是设备上的所有窗口信息
  // 这里可以对`sources`数组下面id进行判断  找到当前的electron窗口  这里为了简单直接拿了第一个
  const stream = await getInitStream(sources[0]);

  new ScreenShot({
    enableWebRtc: true, // 启用webrtc
    screenFlow: stream!, // 传入屏幕流数据
    level: 999,
  });
}

感谢 @Vanisper 提供的在electron环境下使用本插件的兼容思路。

参数说明

截图插件有一个可选参数，它接受一个对象，对象每个key的作用如下:

• enableWebRtc 是否启用webrtc，值为boolean类型，值为false则使用html2canvas来截图
• screenFlow 设备提供的屏幕流数据(用于electron环境下自己传入的视频流数据)，需要将enableWebRtc属性设为true
• completeCallback 截图完成回调函数，值为Function类型，最右侧的对号图标点击后会将图片的base64地址回传给你定义的函数，如果不传的话则会将图片的base64地址放到sessionStorage中，你可以通过下述方式拿到他：

sessionStorage.getItem("screenShotImg");

• closeCallback 截图关闭回调函数，值为Function类型。
• triggerCallback 截图响应回调函数，值为Function类型，使用html2canvas截屏时，页面图片过多时响应会较慢；使用webrtc截屏时用户点了分享，该函数为响应完成后触发的事件。回调函数返回一个对象，类型为: {code: number,msg: string}，code为0时代表截图加载完成。
• cancelCallback 取消分享回到函数，值为Function类型，使用webrtc模式截屏时，用户点了取消或者浏览器不支持时所触发的事件。回调函数返回一个对象，类型为：{code: number,msg: string}，code为-1时代表用户未授权或者浏览器不支持webrtc。
• level 截图容器层级，值为number类型。
• canvasWidth 画布宽度，值为number类型，必须与高度一起设置，单独设置无效。
• canvasHeight 画布高度，值为number类型，必须与宽度一起设置，单独设置无效。
• position 截图容器位置，值为{left?: number, top?: number}类型
• clickCutFullScreen 单击截全屏启用状态,值为boolean类型， 默认为false
• hiddenToolIco 需要隐藏的截图工具栏图标，值为{ save?: boolean; undo?: boolean; confirm?: boolean }类型，默认为{}。传你需要隐藏的图标名称，将值设为true即可。
• showScreenData 截图组件加载完毕后，是否显示截图内容至canvas画布内，值为boolean类型，默认为false。
• imgSrc 截图内容，如果你已经通过其他方式获取到了屏幕内容（例如electron环境），那么可以将获取到的内容传入，此时插件将使用你传进来的图片，值为string类型（可以为图片url地址或者base64），默认为null。
• loadCrossImg 是否加载跨域图片，值为boolean类型，默认为false。
• screenShotDom 需要进行截图的容器，值为HTMLElement类型，默认使用的是body。
• cropBoxInfo 初始裁剪框，值为{ x: number; y: number; w: number; h: number }类型，默认不加载。
• wrcReplyTime webrtc模式捕捉屏幕时的响应时间，值为number类型，默认为500ms。
• noScroll 截图容器是否可滚动，值为boolean类型，默认为true。
• maskColor 蒙层颜色，值为{ r: number; g: number; b: number; a: number }类型,默认为:{ r: 0; g: 0; b: 0; a: 0.6 }

上述类型中的?:为ts中的可选类型，意思为：这个key是可选的，如果需要就传，不需要就不传。

imgSrc是url时，如果图片资源跨域了，必须让图片服务器允许跨域才能正常加载。同样的loadCrossImg设置为true时，图片资源跨域了也需要让图片服务器允许跨域。

快捷键监听

插件容器监听了三个快捷键，如下所示：

• Esc，按下键盘上的esc键时，等同于点了工具栏的关闭图标。
• Enter，按下键盘上的enter键时，等同于点了截图工具栏的确认图标。
• Ctrl/Command + z，按下这两个组合键时，等同于点了截图工具栏的撤销图标。

额外提供的API

插件暴露了一些内部变量出来，便于调用者根据自己的需求进行修改。

getCanvasController

该函数用于获取截图容器的DOM，返回值为HTMLCanvasElement类型。

示例代码：

import ScreenShot from "js-web-screen-shot";

const screenShotHandler = new ScreenShot();
const canvasDom = screenShotHandler.getCanvasController();

注意：如果截图容器尚未加载完毕，获取到的内容可能为null。

destroyComponents

该函数用于销毁截图容器，无返回值。

示例代码：

import ScreenShot from "js-web-screen-shot";

const screenShotHandler = new ScreenShot();
screenShotHandler.destroyComponents()

工具栏图标定制

如果你需要修改截图工具栏的图标，可以通过覆盖元素css类名的方式实现，插件内所有图标的css类名如下所示：

• square 矩形绘制图标
• round 圆型绘制图标
• right-top 箭头绘制图标
• brush 画笔工具
• mosaicPen 马赛克工具
• text 文本工具
• save 保存
• close 关闭
• undo 撤销
• confirm 确认

以square为例，要修改它的图标，只需要将下述代码添加进你项目代码的样式中即可。

  .square {
    background-image: url("你的图标路径") !important;
    
    &:hover {
      background-image: url("你的图标路径") !important;
    }
    
    &:active {
      background-image: url("你的图标路径") !important;
    }
 }

写在最后

至此，插件的所有使用方法就介绍完了，该插件的Vue3版本，请移步：vue-web-screen-shot