DocuSign嵌入式签名default视图加载器左对齐问题求助

问题描述 #

使用DocuSign嵌入式签名流程的default视图时，文档加载阶段的嵌入式加载器显示在屏幕左侧；切换为focused视图时，加载器能正常居中对齐。目前无法通过常规方式修改该布局，想确认是否可通过参数调整，或是容器布局存在问题。

截图 #

关联代码 #

<script lang="ts">
    import { goto } from '$app/navigation';
    import { PUBLIC_DOCUSIGN_INTEGRATION_KEY } from '$env/static/public';
    import Loader from '$lib/components/Loader.svelte';
    import formStore from '../store/index';
    import Alert from '$lib/components/Alert.svelte';

    const infoMessage =
        '为确保签名流程安全可靠，我们使用DocuSign让您在线查看并签署合同。点击下方按钮访问合同，安心完成签名。';

    export let signingUrl: string;
    let isLoading = false;
    let loaded = false;
    let policyAgreed = false;

    // 跳转到下一步
    const redirect = () => {
        formStore.updateContractSigning({ accepted: true });
        goto('/thank-you');
    };

    // 异步加载DocuSign脚本
    const loadDocuSignScriptAsync = () => {
        return new Promise<void>((resolve, reject) => {
            const script = document.createElement('script');
            script.src = 'https://js-d.docusign.com/bundle.js';
            script.async = true;
            script.onload = () => resolve();
            script.onerror = () => reject(new Error('加载DocuSign脚本失败'));
            document.head.appendChild(script);
        });
    };

    // 初始化DocuSign并配置签名选项
    const handleViewContract = async () => {
        try {
            loaded = true;
            isLoading = true;
            await loadDocuSignScriptAsync(); // 确保脚本加载完成后再访问DocuSign对象
            const docusign = await window.DocuSign.loadDocuSign(PUBLIC_DOCUSIGN_INTEGRATION_KEY);
            const signing = docusign.signing({
                url: signingUrl,
                displayFormat: 'default',
                style: {
                    branding: {
                        primaryButton: {
                            backgroundColor: '#FF6B00', // 主按钮背景色
                            color: '#fff' // 主按钮文字颜色
                        }
                    },
                    signingNavigationButton: {
                        finishText: '完成', // 完成按钮自定义文字
                        position: 'bottom-center' // 完成按钮位置
                    }
                }
            });

            // DocuSign UI就绪时触发
            signing.on('ready', (event: any) => {
                console.log('UI已渲染', event);
                policyAgreed = true;
                const agreementDiv = document.getElementById('agreement');
                if (agreementDiv) {
                    agreementDiv.style.backgroundColor = 'white'; // 设置纯白背景
                }
            });

            // 签名会话结束时触发
            signing.on('sessionEnd', (event: any) => {
                console.log('会话已结束', event);
                document.body.classList.remove('overflow-hidden'); // 恢复页面滚动
                const agreementDiv = document.getElementById('agreement');
                if (agreementDiv) {
                    agreementDiv.style.backgroundColor = ''; // 重置背景
                }
                if (event.sessionEndType === 'signing_complete') {
                    agreementDiv?.remove();
                    redirect(); // 跳转到下一步
                }
            });

            signing.mount('#agreement');
        } catch (error) {
            console.log('初始化DocuSign出错:', error);
        } finally {
            isLoading = false;
        }
    };
</script>

<div class="flex flex-col items-center justify-center">
    {#if isLoading}
        <Loader message="正在加载合同详情..." />
    {/if}

    {#if !loaded}
        <div>
            <Alert type="info" message={infoMessage} />
        </div>
        <button
            class="mt-6 w-full md:w-auto py-3 px-6 text-lg font-semibold rounded-md text-white bg-secondary hover:bg-secondary-dark transition duration-300 ease-in-out"
            on:click={handleViewContract}
        >
            查看合同
        </button>
    {:else}
        <p class="text-gray-200 mb-6">
            请花点时间查看您的订阅摘要，并仔细签署条款和条件以完成流程。
        </p>
    {/if}
</div>

<!-- DocuSign签仪式容器 -->
<div
    id="agreement"
    class={`w-full ${policyAgreed ? 'absolute top-0 left-0 z-50 h-full' : ''}`}
    style="box-sizing: border-box;"
></div>

排查与解决方法 #

1. 容器布局问题修复 #

从代码可见，#agreement容器在初始状态（policyAgreed为false）仅设置了w-full，没有明确的高度和内容居中规则。DocuSign的default视图会继承容器的布局上下文，导致加载器无法正确居中。

修改容器初始样式，确保加载阶段容器占满视口并居中内容：

<div
    id="agreement"
    class={`w-full min-h-screen flex items-center justify-center ${policyAgreed ? 'absolute top-0 left-0 z-50 h-full' : ''}`}
    style="box-sizing: border-box;"
></div>

2. 尝试DocuSign配置参数调整 #

虽然DocuSign官方文档中default视图的加载器没有公开的直接配置项，但可以尝试添加style.loading自定义配置（需确认当前API版本支持）：

const signing = docusign.signing({
    url: signingUrl,
    displayFormat: 'default',
    style: {
        // 尝试添加加载器居中配置
        loading: {
            align: 'center',
            justify: 'center'
        },
        branding: {
            primaryButton: {
                backgroundColor: '#FF6B00',
                color: '#fff'
            }
        },
        signingNavigationButton: {
            finishText: '完成',
            position: 'bottom-center'
        }
    }
});

3. CSS强制覆盖加载器样式 #

如果上述方法无效，可通过CSS强制修改DocuSign加载器的位置：

/* 在全局样式或组件内添加 */
#agreement .ds-loading-container {
    display: flex !important;
    justify-content: center !important;
    align-items: center !important;
    width: 100% !important;
    height: 100% !important;
}

4. 检查DocuSign版本兼容性 #

当前使用的https://js-d.docusign.com/bundle.js可能存在版本bug，建议替换为最新版本的脚本链接测试，确认是否是版本导致的布局异常。

内容的提问来源于stack exchange，提问作者Kinara Nyakaru