@openlee/virtual-parcel-widget

数字包裹系统 UI 集成 SDK，提供开箱即用的核销界面。

安装

npm install @openlee/virtual-parcel-widget

快速开始

方式 1：Script 标签（CDN）

<!DOCTYPE html>
<html>
<head>
  <title>我的应用</title>
  <script src="https://cdn.jsdelivr.net/npm/@openlee/virtual-parcel-widget@latest/dist/index.global.js"></script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@openlee/virtual-parcel-widget@latest/dist/style.css">
</head>
<body>
  <div id="widget-container"></div>
  
  <script>
    const widget = new VirtualParcelWidget({
      backendUrl: 'https://api.virtual-parcel.com',
      container: '#widget-container',
      onSuccess: (result) => {
        console.log('激活成功！', result);
        // 解锁功能
      }
    });
    
    widget.show();
  </script>
</body>
</html>

方式 2：NPM 包

import { VirtualParcelWidget } from '@openlee/virtual-parcel-widget';
import '@openlee/virtual-parcel-widget/style.css';

const widget = new VirtualParcelWidget({
  backendUrl: 'https://api.virtual-parcel.com',
  container: '#widget-container',
  theme: 'light',
  locale: 'zh-CN',
  onSuccess: (result) => {
    console.log('激活成功！', result);
  },
  onFail: (error) => {
    console.error('激活失败：', error.message);
  }
});

widget.show();

方式 3：React 组件

import { useEffect, useRef } from 'react';
import { VirtualParcelWidget } from '@openlee/virtual-parcel-widget';

function ActivationWidget() {
  const containerRef = useRef<HTMLDivElement>(null);
  
  useEffect(() => {
    const widget = new VirtualParcelWidget({
      backendUrl: 'https://api.virtual-parcel.com',
      container: containerRef.current!,
      onSuccess: (result) => {
        console.log('激活成功！');
      }
    });
    
    return () => widget.destroy();
  }, []);
  
  return <div ref={containerRef} />;
}

配置选项

interface WidgetConfig {
  /** 后端 URL */
  backendUrl?: string;
  /** 挂载容器（CSS 选择器或 HTMLElement） */
  container?: string | HTMLElement;
  /** 主题：light | dark | auto */
  theme?: 'light' | 'dark' | 'auto';
  /** 语言：zh-CN | en-US */
  locale?: 'zh-CN' | 'en-US';
  /** 主色调（十六进制） */
  primaryColor?: string;
  /** 验证成功回调 */
  onSuccess?: (result: VerifyResult) => void;
  /** 验证失败回调 */
  onFail?: (error: { message: string }) => void;
  /** 关闭回调 */
  onClose?: () => void;
}

API

new VirtualParcelWidget(config)

创建 Widget 实例。

widget.show()

显示 Widget。

widget.hide()

隐藏 Widget。

widget.destroy()

销毁 Widget，清理资源。

widget.on(event, callback)

监听事件。

• success: 验证成功
• fail: 验证失败
• close: 关闭 Widget

widget.off(event, callback)

取消监听事件。

自定义样式

方式 1：配置项

const widget = new VirtualParcelWidget({
  // ...
  primaryColor: '#6366f1', // 自定义主色调
});

方式 2：覆盖 CSS

.widget-container {
  /* 自定义容器样式 */
}

.btn-primary {
  /* 自定义按钮样式 */
}

.input-code {
  /* 自定义输入框样式 */
}

界面预览

默认状态

┌─────────────────────────────────────────┐
│  🔓 激活服务                             │
│                                         │
│  请输入取件码以激活本服务                 │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │         XXXX-XXXX                │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │         立即激活                 │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

验证成功

┌─────────────────────────────────────────┐
│            ✅                            │
│         激活成功                         │
│                                         │
│      您已成功激活本服务！                │
└─────────────────────────────────────────┘

验证失败

┌─────────────────────────────────────────┐
│            ❌                            │
│         激活失败                         │
│                                         │
│      取件码无效或已被使用                │
│                                         │
│      ┌─────────────────────┐           │
│      │       重试          │           │
│      └─────────────────────┘           │
└─────────────────────────────────────────┘

License

MIT