Unpkg集成Mirador Viewer在existDB应用中异常问题排查求助

我正在将XSLT生成HTML的应用迁移至existDB，需要集成Mirador Viewer。示例代码在静态HTML页面、existDB导出的静态HTML文件中均能正常运行，但在existDB应用内使用时，Viewer极不稳定：

• 加载阶段抛出TypeError: this.gridRef.current is null错误
• 和画布交互时触发“too much recursion”无限递归错误

混淆后的代码难以排查，求可行的解决方案。

相关代码 #

<div id="viewer" allowfullscreen="allowfullscreen">
<script src="https://unpkg.com/mirador@latest/dist/mirador.min.js"></script>
<div id="mirador"></div>
<script type="text/javascript">
  const mirador = Mirador.viewer({
    "id": "mirador",
    "manifests": {
      "https://iiif.lib.harvard.edu/manifests/drs:48309543": {
        "provider": "Harvard University"
      }
    },
    "windows": [
      {
        "loadedManifest": "https://iiif.lib.harvard.edu/manifests/drs:48309543",
        "canvasIndex": 2,
        "thumbnailNavigationPosition": 'far-bottom'
      }
    ]
  });
</script>
</div>

加载时错误日志 #

TypeError: this.gridRef.current is null
    value ThumbnailNavigation.js:35
    React 2
    unstable_runWithPriority scheduler.production.min.js:19
    React 4
    unstable_runWithPriority scheduler.production.min.js:19
    React 4
    Redux 68
    Ks createPluggableStore.js:22
    e MiradorViewer.js:20
    viewer init.js:15
    <anonymous> index:15
react-dom.production.min.js:209:194
    React 9
    unstable_runWithPriority scheduler.production.min.js:19
    React 4
    Redux 68
    Ks createPluggableStore.js:22
    e MiradorViewer.js:20
    viewer init.js:15
    <anonymous> index:15

画布交互错误日志 #

InternalError: too much recursion
    c getScrollParent.js:27
    G setupEventListeners.js:11
    G mirador.min.js:2  -- THIS REPEATS 123 TIMES --
react-dom.production.min.js:209:194
    React 9
        os
        payload
        gi
        Fa
        Es
        vc
        gc
        sc
        Xo
    unstable_runWithPriority scheduler.production.min.js:19
    React 5
        qo
        Xo
        Yo
        nc
        ya
    o useControlled.js:38
    we Tooltip.js:273
    current Tooltip.js:306
    (Async: setTimeout handler)
    Oe Tooltip.js:305
    React 12
        s
        p
        v
        v
        st
        it
        ct
        ht
        L
        F
        Jt
        Qt
    unstable_runWithPriority scheduler.production.min.js:19
    React 11
        Xt
        Zt
        Kt
        gt
        un
        es
        bc
        vc
        gc
        sc
        Xo
    unstable_runWithPriority scheduler.production.min.js:19
    React 2
        qo
        Xo
    W scheduler.production.min.js:17
    onmessage scheduler.production.min.js:14
    (Async: EventHandlerNonNull)
    <anonymous> scheduler.production.min.js:13
    Webpack 15
        o
        <anonymous>
        o
        <anonymous>
        o
        <anonymous>
        o
        <anonymous>
        o
        <anonymous>
        o
        <anonymous>
        <anonymous>
        <anonymous>
        <anonymous>

可行解决方案 #

1. 等待DOM完全加载后初始化Mirador #

existDB动态渲染页面时，可能目标DOM节点还未生成就执行了Mirador初始化，导致Ref绑定失败。把初始化代码放到DOM加载完成事件中：

document.addEventListener('DOMContentLoaded', function() {
  const mirador = Mirador.viewer({
    "id": "mirador",
    "manifests": {
      "https://iiif.lib.harvard.edu/manifests/drs:48309543": {
        "provider": "Harvard University"
      }
    },
    "windows": [
      {
        "loadedManifest": "https://iiif.lib.harvard.edu/manifests/drs:48309543",
        "canvasIndex": 2,
        "thumbnailNavigationPosition": 'far-bottom'
      }
    ]
  });
});

2. 替换为指定稳定版Mirador #

latest标签可能指向不稳定的开发版本，换成官方标记的稳定版（比如3.3.0）：

<script src="https://unpkg.com/mirador@3.3.0/dist/mirador.min.js"></script>

3. 检查XSLT输出的DOM结构 #

existDB的XSLT转换可能意外修改HTML结构：

• 自动添加嵌套元素导致#mirador容器被隐藏或未正确渲染
• 输出未闭合标签破坏DOM完整性
  在浏览器开发者工具中对比静态HTML和existDB生成页面的DOM结构，定位差异。

4. 临时禁用缩略图导航排查 #

加载错误指向ThumbnailNavigation.js，先禁用缩略图导航验证问题根源：

"windows": [
  {
    "loadedManifest": "https://iiif.lib.harvard.edu/manifests/drs:48309543",
    "canvasIndex": 2,
    "thumbnailNavigationPosition": null // 禁用缩略图导航
  }
]

如果问题消失，说明是缩略图组件与existDB环境兼容性问题，可尝试升级Mirador或自定义样式修复。

5. 调整existDB的内容安全策略（CSP） #

existDB可能启用了严格的CSP，限制了Mirador的脚本执行或资源加载。查看浏览器控制台的CSP报错，调整existDB配置，允许Mirador所需的资源加载和内联脚本执行。

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