单体签章 JS SDK

Appearance

Return to top
文档目录

快速上手

1. 安装

当前 SDK 提供 umd 与 commjs 格式的方案，您可以通过以下方式进行快速安装：

1.1 script 标签直接导入

umd 格式的 js 文件需要通过客服或联系相应技术人员获取。

  • 通过 script 标签导入 sdk

    html
    <script src="./UKeySdk.min.js"></script>

  • 导入后 sdk 会在 window 上挂载 QysUKeySdk 全局变量，该变量为创建 sdk 实例的类，通过浏览器控制台查看 QysUKeySdk 以及 QysUKeySdk.version 可以正常打印 sdk 版本即引入成功。image-20230209165905233

1.2 作为 npm 包导入

由于暂未发布至 npm 仓库，当前方案仅支持内网 git 方式使用。

  • 在 package.json 文件中添加依赖

    json
    // package.json
{
  ...
  "dependencies": {
    ...
    "ukey-sign-sdk": "git+https://git.qiyuesuo.me/scm/~yishuai.wang/ukey-sign-sdk.git",
    ...
  }
  ...
}

  • 在项目中通过 npm 包导入

    typescript
    import { QysUKeySdk } from 'ukey-sign-sdk'

console.log("QysUKeySdk", QysUKeySdk)
console.log("version", QysUKeySdk.version)

2. 快速集成电子签章应用

2.1 原生版本

html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Qys UKey SDK</title>
  <style>
    .App {
      width: 100vw;
      height: 100vh;
      overflow: hidden;
      display: flex;
      flex-direction: column;
    }

    .header {
      flex-shrink: 0;
    }

    .body {
      flex: 1;
      overflow: hidden;
    }
		/* 注意：实例挂载的 dom 元素需要保证设置宽高，否则可能出现无法滚动的现象 */
    .container {
      width: 100%;
      height: 100%;
    }
  </style>
</head>
<body>
  <div class="App">
    <div class='header'>
      <label for="addFile">添加文件</label>
      <input id="addFile" type="file" multiple />
      <button id="close">关闭</button>
    </div>
    <div class='body'>
      <div id='container' class="container"></div>
    </div>
  </div>
  <!-- 1. 加载 sdk 文件 -->
  <script src="./sdk.js"></script>
  <script>
    window.addEventListener('load', () => {
      /** 创建 sdk 实例 */
      const uKeySdkInstance = new QysUKeySdk({})
      /** 必要的 dom 元素获取 */
      const container = document.getElementById('container');
      const addFileEl = document.getElementById('addFile');
      const closeEl = document.getElementById('close');

      /** 向签章系统中添加 pdf 文件 */
      const handleAddFile = (event) => {
        const fileList = event.target.files;
        if (!fileList.length) return;

        /** uKeySdkInstance.container 可用于判断当前是否已经渲染，组件渲染后会将根 dom 元素保存在 sdk 实例中 */
        if (!uKeySdkInstance.container) {
          /** 将应用渲染至指定的 dom 元素中 */
          uKeySdkInstance.render(container)
        }

        /** 向签章系统中添加 pdf 文件 */
        uKeySdkInstance.addFile(fileList);
      }

      /** 卸载当前签章应用实例 */
      const handleCloseApp = () => {
        uKeySdkInstance.close();
      }

      /** 监听文件改变，进行文件上传 */
      addFileEl.addEventListener('change', handleAddFile)
      /** 监听关闭按钮点击，卸载当前实例 */
      closeEl.addEventListener('click', handleCloseApp)
      
    })
  </script>
</body>
</html>

2.2 React 版本

tsx
import { useEffect, useRef } from 'react';
// 引入 sdk
import { QysUKeySdk } from 'ukey-sign-sdk'
import './App.css';

function App() {
  const container = useRef<HTMLDivElement>(null)
  const ukeySdk = useRef<QysUKeySdk|null>(null)

  /** 创建 sdk 实例 */
  useEffect(() => {
    if (container.current) {
      ukeySdk.current = new QysUKeySdk({})
    }
  }, [])

  /** 向签章系统中添加 pdf 文件 */
  const handleAddFile = (event: React.ChangeEvent<HTMLInputElement>) => {
    const files = event.target.files;
    if (!files || !files.length || !ukeySdk.current) return;
    /** ukeySdk.current.container 可用于判断当前是否已经渲染，组件渲染后会将根 dom 元素保存在 sdk 实例中 */
    if (!ukeySdk.current.container) {
      ukeySdk.current.render(container.current!)
    }
    /** 向签章系统中添加 pdf 文件 */
    ukeySdk.current!.addFile(files)
  }

  /** 卸载当前签章应用实例 */
  const handleCloseApp = () => {
    if (!ukeySdk.current) return;
    ukeySdk.current.close()
  }


  return (
    <div className='App'>
      <div className='header'>
        <label htmlFor='addFile'>添加文件</label>
        <input id='addFile' type="file" multiple onChange={handleAddFile}/>
        <button onClick={handleCloseApp}>close</button>
      </div>
      <div className='body'>
        <div ref={container} className='container'></div>
      </div>
    </div>
  );
}

export default App;
css
/* App.css */
.App {
  width: 100vw;
  height: 100vh;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.header {
  flex-shrink: 0;
}

.body {
  flex: 1;
  overflow: hidden;
}
/* 注意：实例挂载的 dom 元素需要保证设置宽高，否则可能出现无法滚动的现象 */
.container {
  width: 100%;
  height: 100%;
}

2.3 Vue3 / Vue2.7 版本

vue
<!-- App.vue -->
<script lang="ts">
// 引入 sdk
import { QysUKeySdk } from 'ukey-sign-sdk';
import { ref } from 'vue'
</script>
<script setup lang="ts">
  const ukeySdk = new QysUKeySdk({})
  const container = ref<HTMLDivElement|null>(null)

  const handleAddFile = (event: any) => {
    const files = event.target.files;
    if (!files || !files.length || !ukeySdk) return;
    /** ukeySdk.container 可用于判断当前是否已经渲染，组件渲染后会将根 dom 元素保存在 sdk 实例中 */
    if (!ukeySdk.container) {
      ukeySdk.render(container.value!)
    }
    /** 向签章系统中添加 pdf 文件 */
    ukeySdk.addFile(files)
  }

  /** 卸载当前签章应用实例 */
  const handleCloseApp = () => {
    if (!ukeySdk) return;
    ukeySdk.close()
  }

</script>

<template>
  <div class='App'>
    <div class='header'>
      <label htmlFor='addFile'>添加文件</label>
      <input id='addFile' type="file" multiple @change="handleAddFile"/>
      <button @click="handleCloseApp">close</button>
    </div>
    <div class='body'>
      <div ref="container" class='container'></div>
    </div>
  </div>
</template>

<style scoped>
.App {
  width: 100vw;
  height: 100vh;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.header {
  flex-shrink: 0;
}

.body {
  flex: 1;
  overflow: hidden;
}

.container {
  width: 100%;
  height: 100%;
}
</style>

2.4 集成效果展示

2023-02-09 17.42.25

🎉🎉🎉 Congratulations!

恭喜，您已经成功将单体签章系统集成至您的应用。