使用Rangy 1.3.2序列化选区时遇Range类型无效错误求助

问题背景 #

使用Rangy 1.3.2版本序列化DOM文本选区时，触发错误：Error: Highlighter type 'Range' is not valid。追踪源码发现，该版本的Highlighter仅支持textContent和TextRange两种类型，但无法确定当前代码中Range类型的来源，相关核心代码如下：

const textHighlighter = ContentViewerBaseClass.getTextHighlighter()
const thisSelection = rangy.getSelection()
const highlightedText = thisSelection.text()
serializedData: textHighlighter.serialize(thisSelection),

public onAddHighlightToSelectedText(highlight: { color, fontColor }) {
    const textHighlighter = ContentViewerBaseClass.getTextHighlighter()

    const thisSelection = rangy.getSelection()
    const highlightedText = thisSelection.text()

    // 检查搜索高亮重叠部分
    const allSearchMatchesMarkup =
        this.$refs.contentContainer.querySelectorAll(`.${this.searchMarkupClassName}`)

    const overlappingSearchMarkup = []
    if (allSearchMatchesMarkup) {
        for (const i of allSearchMatchesMarkup) {
            if (thisSelection.containsNode(i, true)) {
                overlappingSearchMarkup.push(i.id)
            }
        }
    }

    let highlightTarget = null
    if (this.currentContentType === ContentType.PDF) {
        highlightTarget = thisSelection.anchorNode.parentElement.closest(`[id^=page-]`)
    } else {
        highlightTarget = this.$refs.contentContainer
    }

    textHighlighter.highlightSelection(this.highlightClassName, {
        selection: thisSelection,
        containerElementId: highlightTarget.id,
    })

    const thisHighlightId = `s${String(Date.now())}`

    thisSelection.getRangeAt(0).getNodes([1], (el) => {
        if (el && el.classList.contains(this.highlightClassName)) {
            if (el.classList.contains(this.searchMarkupClassName)) {
                el = this.addOverlappingHighlightSearchTextIdToNode(el, thisHighlightId)
            }
            el.id = thisHighlightId

            el.style.backgroundColor = highlight.color

            if (this.currentContentType === ContentType.PDF) {
                el.style.color = 'transparent'
            }

            el.setAttribute('data-note', '')

            this.annotatedElementClicked = el
            return el
        }
    })

    if (this.currentContentType === ContentType.PDF) {
        const pageDomElement =
            this.$refs.contentContainer.querySelector(`#${thisHighlightId}`).closest(`[id^=page-]`)

        if (pageDomElement) {
            if (!this.isPdfContentInArrayFormat) {
                this.currentPageId = pageDomElement.id.substring(pageDomElement.id.indexOf('-') + 1)
            }
        }
    }

    this.saveHighlight({
        id: thisHighlightId,
        type: EnrichmentType.HIGHLIGHT,
        highlightColor: highlight.color,
        highlightedText,
        noteAdded: '',
        contentId: this.currentPageId || '',
        pageId: this.currentContentType === ContentType.PDF ? String(this.currentPageIndex + 1) :
            this.currentPageId,

        pageTitle: this.currentContentType === ContentType.PDF ? `Page ${this.currentPageIndex + 1}` :
            this.currentPageTitle,

        pageIndex: this.currentPageIndex,
        contentType: this.currentContentType,
        timeAdded: String(Date.now()),
        serializedData: textHighlighter.serialize(thisSelection),
    } as IEnrichmentItem)

    thisSelection.removeAllRanges()
}

排查方向 #

1. Highlighter初始化问题：检查ContentViewerBaseClass.getTextHighlighter()是否正确初始化Highlighter，是否指定了TextRange类型，以及是否加载了Rangy的TextRange模块。
2. DOM修改导致选区失效：调用highlightSelection()会修改DOM结构，可能导致原选区对象从Rangy的TextRange变为原生Range，后续序列化时触发错误。
3. 浏览器环境兼容性：部分浏览器的原生Selection返回的Range对象与Rangy封装的TextRange不兼容，导致类型识别错误。

解决建议 #

1. 确保Highlighter正确初始化 #

Rangy 1.3.2的Highlighter需要依赖TextRange模块，初始化时需明确指定类型。检查ContentViewerBaseClass.getTextHighlighter()内部实现，确保类似以下代码：

// 正确初始化Highlighter
export function getTextHighlighter() {
    // 确保已加载TextRange模块
    if (!rangy.modules.TextRange) {
        throw new Error("Rangy TextRange module is not loaded");
    }
    return rangy.createHighlighter({
        type: "TextRange"
    });
}

2. 提前序列化选区，避免DOM修改后失效 #

将序列化操作移到highlightSelection()之前，因为高亮操作会改变DOM结构，导致原选区对象类型变化：

public onAddHighlightToSelectedText(highlight: { color, fontColor }) {
    const textHighlighter = ContentViewerBaseClass.getTextHighlighter()
    const thisSelection = rangy.getSelection()
    const highlightedText = thisSelection.text()

    // --- 提前序列化选区 ---
    const serializedData = textHighlighter.serialize(thisSelection);

    // 检查搜索高亮重叠部分（原代码保留）
    const allSearchMatchesMarkup =
        this.$refs.contentContainer.querySelectorAll(`.${this.searchMarkupClassName}`)
    // ...（原代码中重叠检查逻辑保留）

    let highlightTarget = null
    // ...（原代码中highlightTarget逻辑保留）

    // 执行高亮操作
    textHighlighter.highlightSelection(this.highlightClassName, {
        selection: thisSelection,
        containerElementId: highlightTarget.id,
    })

    // ...（原代码中设置高亮元素ID、样式等逻辑保留）

    // 保存时使用提前序列化好的数据
    this.saveHighlight({
        // ...其他字段保留
        serializedData: serializedData, // 替换为提前序列化的值
    } as IEnrichmentItem)

    thisSelection.removeAllRanges()
}

3. 手动转换原生Range为Rangy TextRange #

如果确认选区是原生Range对象，可手动转换为Rangy兼容的TextRange：

// 获取原生Range并转换
const nativeRange = thisSelection.getRangeAt(0);
const rangyRange = rangy.createRange();
rangyRange.setStart(nativeRange.startContainer, nativeRange.startOffset);
rangyRange.setEnd(nativeRange.endContainer, nativeRange.endOffset);
// 序列化转换后的Range
const serializedData = textHighlighter.serialize(rangyRange);

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