福昕开发者文档中心

进度条组件 ​

概述 ​

福昕 PDF SDK Web 版从 9.1 版本开始提供了用于控制和自定义进度条的相关 API。具体接口描述信息，请参阅 接口文档 。

API 说明 ​

PDFUI 构造参数 ​

通过 customs.progress 参数可以自定义进度条实现：

typescript
interface ProgressComponent {
    // 更新进度
    updateProgress(progress: number | { current: number, total: number }, status: string): void;

    // 显示进度条
    show(coverOn: HTMLElement): void;

    // 隐藏进度条
    hide(): void;
}

PDFViewer 监听器 ​

使用 registerProgressListener 方法注册进度条监听器：

typescript
interface ProgressListener {
    (type: string, value: number, status: string): void;
}

ProgressComponent 类 ​

通过 PDFViewCtrl.viewerui.ProgressComponent 获取进度条组件类。

应用场景 ​

触发时机

以下操作会触发默认进度条显示：

  1. PDFDoc.sign - 签名操作
  2. PDFDoc.addWatermark - 添加水印
  3. Action: Run Form Recognition - 表单识别
  4. PDFViewer.print - 打印操作
  5. PDFViewer.printEx - 扩展打印
  6. PDFDoc.addPagingSealSignature - 添加骑缝章

使用示例 ​

方式一：自定义 PDFUI 进度条 ​

html

<div id="pdf-ui"></div>
<div id="progress-bar"></div>

<style>
    #progress-bar {
        display: none;
        position: absolute;
        inset: 0;
        text-align: center;
        line-height: 100vh;
        z-index: 9999;
        background: rgba(255, 255, 255, 0.6);
        font-size: 24px;
    }
</style>

<script>
    const progressBar = document.getElementById('progress-bar');
    const pdfui = new PDFUI({
        customs: {
            progress: class Progress {
                updateProgress(progress, status) {
                    progressBar.innerText = `${progress}%`;
                }

                show(coverOn) {
                    progressBar.style.display = 'block';
                    progressBar.innerText = '0%';
                }

                hide() {
                    progressBar.style.display = 'none';
                }
            }
        }
    });
</script>

方式二：使用 PDFViewer 监听器 ​

html

<div id="pdf-viewer"></div>
<div id="progress-bar"></div>

<script>
    const pdfViewer = new PDFViewer({
        // 基础配置
    });
    pdfViewer.init('#pdf-viewer');

    const progressBar = document.getElementById('progress-bar');
    pdfViewer.registerProgressHandler((type, value, status) => {
        if (status === PDFViewCtrl.constants.PROGRESS_STATUS.PROGRESSING) {
            progressBar.style.display = 'block';
            progressBar.innerHTML = value + '%';
        } else {
            progressBar.style.display = 'none';
        }
    });
</script>

方式三：使用 ProgressComponent ​

javascript
// 示例 1：基础进度显示
const progressComponent = new PDFViewCtrl.viewerui.ProgressComponent();
progressComponent.show(document.body);
progressComponent.updateProgress(20, PDFViewCtrl.constants.PROGRESS_STATUS.PROGRESSING);

// 结束处理
// 成功：progressComponent.updateProgress(null, PDFViewCtrl.constants.PROGRESS_STATUS.SUCCESS);
// 失败：progressComponent.updateProgress(null, PDFViewCtrl.constants.PROGRESS_STATUS.FAIL);

// 示例 2：显示当前进度/总进度
const progressComponent = new PDFViewCtrl.viewerui.ProgressComponent();
progressComponent.show(document.body);
progressComponent.updateProgress(
    {current: 1, total: 4},
    PDFViewCtrl.constants.PROGRESS_STATUS.PROGRESSING
);

提示

  • 三种实现方式可以根据具体需求选择使用
  • ProgressComponent 提供了最灵活的自定义能力
  • 建议在长时间操作中添加进度提示，提升用户体验