导入方式指南

mumu2025/11/23大约 4 分钟开发指南使用方法导入ES ModuleCommonJSTree-shaking

GMKit 导入方式示例

GMKit 支持多种灵活的导入方式，满足不同场景的需求。

1. 算法模块导入（推荐）

这是最推荐的导入方式，可以清晰地组织代码，并且支持 tree-shaking。

import { sm2, sm3, sm4, zuc } from 'gmkitx';

// 使用 SM2
const keyPair = sm2.generateKeyPair();
const encrypted = sm2.encrypt(keyPair.publicKey, 'Hello');
const decrypted = sm2.decrypt(keyPair.privateKey, encrypted);

// 使用 SM3
const hash = sm3.digest('Hello, World!');
const mac = sm3.hmac('secret', 'data');

// 使用 SM4
const key = '0123456789abcdeffedcba9876543210';
const cipher = sm4.encrypt(key, 'Hello', { mode: 'ecb', padding: 'pkcs7' });
const plain = sm4.decrypt(key, cipher, { mode: 'ecb', padding: 'pkcs7' });

// 使用 ZUC
const zucKey = '00112233445566778899aabbccddeeff';
const zucIv = 'ffeeddccbbaa99887766554433221100';
const zucCipher = zuc.encrypt(zucKey, zucIv, 'Hello');
const zucPlain = zuc.decrypt(zucKey, zucIv, zucCipher);

2. 具名函数导入（向后兼容）

这种方式导入特定的函数，适合只需要使用少量功能的场景。

import { 
  generateKeyPair, 
  sm2Encrypt, 
  sm2Decrypt,
  digest,
  hmac,
  sm4Encrypt,
  sm4Decrypt,
  zucEncrypt,
  zucDecrypt,
  CipherMode,
  PaddingMode
} from 'gmkitx';

// 直接使用函数
const keyPair = generateKeyPair();
const encrypted = sm2Encrypt(keyPair.publicKey, 'Hello');
const hash = digest('Hello');
const cipher = sm4Encrypt(key, 'Hello', { 
  mode: CipherMode.ECB, 
  padding: PaddingMode.PKCS7 
});

3. 命名空间导入

适合需要在运行时动态选择算法的场景。

import * as gmkitx from 'gmkitx';

// 通过命名空间访问
const keyPair = gmkit.sm2.generateKeyPair();
const hash = gmkit.sm3.digest('Hello');
const cipher = gmkit.sm4.encrypt(key, 'Hello', { mode: 'ecb' });
const zucCipher = gmkit.zuc.encrypt(zucKey, zucIv, 'Hello');

// 也可以访问具名导出
const hash2 = gmkit.digest('Hello');
const encrypted = gmkit.sm2Encrypt(keyPair.publicKey, 'Hello');

4. CommonJS 导入

在 Node.js 环境中使用 require 导入。

// 导入算法模块
const { sm2, sm3, sm4, zuc } = require('gmkitx');

const keyPair = sm2.generateKeyPair();
const hash = sm3.digest('Hello');

// 或者导入具名函数
const { digest, sm4Encrypt } = require('gmkitx');
const hash2 = digest('Hello');

5. UMD（浏览器直接引入）

<script src="https://unpkg.com/gmkitx@latest/dist/index.global.js"></script>
<script>
  // GMKit 会被注册为全局变量
  
  // 方式 1: 使用算法模块
  const keyPair = GMKit.sm2.generateKeyPair();
  const hash = GMKit.sm3.digest('Hello, World!');
  
  // 方式 2: 使用具名函数（通过 default 访问）
  const hash2 = GMKit.default.digest('Hello');
  const encrypted = GMKit.default.sm2Encrypt(keyPair.publicKey, 'Hello');
</script>

6. 动态导入

适合代码分割和按需加载的场景。

// 只在需要时加载 SM2
async function useSM2() {
  const { sm2 } = await import('gmkit');
  const keyPair = sm2.generateKeyPair();
  return keyPair;
}

// 按需加载特定功能
async function hashData(data: string) {
  const { digest } = await import('gmkit');
  return digest(data);
}