Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.
TypeScript boardcollaborationdocdocxexceloffce365officepdfpptpptxpresentationsdksheetslidesspreadsheetuniverwordwordprocessorworkspacexlsx
feat(docs): add agent-friendly text range lookup (#7329)
Univerb273f475e176
diff --git a/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts b/packages/docs/src/facade/__tests__/f-document-paragraph.spec.tsindex 53beef0416..6579bcc1b8 100644--- a/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts+++ b/packages/docs/src/facade/__tests__/f-document-paragraph.spec.ts@@ -166,6 +166,82 @@ describe('FDocumentParagraph', () => {});});+ it('finds literal text ranges inside a paragraph', () => {+ createDocumentFacade(createSimpleDocument());++ const paragraph = document.getParagraphs()[0];++ expect(paragraph.findText('pha')?.describe()).toMatchObject({+ startOffset: 2,+ endOffset: 5,+ segmentId: '',+ text: 'pha',+ });+ expect(paragraph.findText('PHA')).toBeNull();+ expect(paragraph.findText('PHA', { matchCase: false })?.getText()).toBe('pha');+ expect(paragraph.findAllText('a').map((range) => range.getRange())).toEqual([+ { startOffset: 4, endOffset: 5, segmentId: '' },+ ]);+ expect(paragraph.findText('missing')).toBeNull();+ expect(() => paragraph.findText('', { occurrence: 0 })).toThrow(TypeError);+ expect(() => paragraph.findText('a', { occurrence: -1 })).toThrow(RangeError);+ });++ it('resolves repeated text occurrences and keeps header matches scoped to their segment', () => {+ const headerId = 'header-find';+ createDocumentFacade({+ ...createDocumentData('doc-find-repeated', {+ dataStream: 'x plus x\r\n',+ paragraphs: [{ startIndex: 8, paragraphId: 'para_body_repeated' }],+ sectionBreaks: [{ sectionId: 'section_body_repeated', startIndex: 9 }],+ }),+ headers: {+ [headerId]: {+ headerId,+ body: {+ dataStream: 'X and x\r\n',+ paragraphs: [{ startIndex: 7, paragraphId: 'para_header_repeated' }],+ sectionBreaks: [{ sectionId: 'section_header_repeated', startIndex: 8 }],+ },+ },+ },+ });++ const bodyParagraph = document.getParagraphs()[0];+ const headerParagraph = document.getParagraphs(headerId)[0];++ expect(bodyParagraph.findAllText('x').map((range) => range.getRange())).toEqual([+ { startOffset: 0, endOffset: 1, segmentId: '' },+ { startOffset: 7, endOffset: 8, segmentId: '' },+ ]);+ expect(bodyParagraph.findText('x', { occurrence: 1 })?.getText()).toBe('x');+ expect(headerParagraph.findAllText('x', { matchCase: false }).map((range) => range.getRange())).toEqual([+ { startOffset: 0, endOffset: 1, segmentId: headerId },+ { startOffset: 6, endOffset: 7, segmentId: headerId },+ ]);+ });++ it('keeps original document offsets when case folding changes string length', () => {+ createDocumentFacade(createDocumentData('doc-find-unicode', {+ dataStream: 'İx and a.b\r\n',+ paragraphs: [{ startIndex: 10, paragraphId: 'para_unicode' }],+ sectionBreaks: [{ sectionId: 'section_unicode', startIndex: 11 }],+ }));++ const paragraph = document.getParagraphs()[0];++ expect(paragraph.findText('x', { matchCase: false })?.describe()).toMatchObject({+ startOffset: 1,+ endOffset: 2,+ text: 'x',+ });+ expect(paragraph.findText('A.B', { matchCase: false })?.describe()).toMatchObject({+ startOffset: 7,+ endOffset: 10,+ text: 'a.b',+ });+ });+it('rejects invalid document text ranges', () => {createDocumentFacade(createSimpleDocument());diff --git a/packages/docs/src/facade/f-document-paragraph.ts b/packages/docs/src/facade/f-document-paragraph.tsindex f86859dc83..df7e607c6d 100644--- a/packages/docs/src/facade/f-document-paragraph.ts+++ b/packages/docs/src/facade/f-document-paragraph.ts@@ -17,7 +17,8 @@import type { IDocumentBody, Injector, IParagraph, IParagraphStyle } from '@univerjs/core';import type { FDocument } from './f-document';import type { IFDocumentTextRange } from './utils';-import { getParagraphContentStartOffset, PresetListType, RESTORE_INSERTED_PARAGRAPH_IDS, UpdateDocsAttributeType } from '@univerjs/core';+import { getParagraphContentStartOffset, PresetListType, regexp, RESTORE_INSERTED_PARAGRAPH_IDS, UpdateDocsAttributeType } from '@univerjs/core';+import { FBaseInitialable } from '@univerjs/core/facade';import { FDocumentTextRange } from './f-document-text-range';import { buildPlainTextInsertBody, replaceBodyRange, retainBodyRange } from './utils';@@ -35,6 +36,23 @@ export interface IFDocumentParagraphInfo {endOffset: number;}+/**+ * Options for locating text inside a document paragraph.+ */+export interface IFDocumentFindTextOptions {+ /**+ * Whether matching is case-sensitive.+ * @default true+ */+ matchCase?: boolean;++ /**+ * Zero-based occurrence to return from {@link FDocumentParagraph.findText}.+ * @default 0+ */+ occurrence?: number;+}+/*** A paragraph facade wrapper.*@@ -44,13 +62,15 @@ export interface IFDocumentParagraphInfo {** @hideconstructor*/-export class FDocumentParagraph {+export class FDocumentParagraph extends FBaseInitialable {constructor(- private readonly _document: FDocument,- private readonly _paragraphId: string,- private readonly _segmentId = '',- private readonly _injector: Injector- ) {}+ protected readonly _document: FDocument,+ protected readonly _paragraphId: string,+ protected readonly _segmentId = '',+ protected override readonly _injector: Injector+ ) {+ super(_injector);+ }/*** Get the persisted paragraph id.@@ -149,6 +169,91 @@ export class FDocumentParagraph {return this._injector.createInstance(FDocumentTextRange, this._document, startOffset, endOffset, this._segmentId, this._injector);}+ /**+ * Finds one literal text occurrence inside this paragraph.+ *+ * The returned text range is fixed when it is created. Resolve a new range+ * after edits that insert or remove content before the match.+ *+ * @param {string} text Literal text to find. It must not be empty.+ * @param {IFDocumentFindTextOptions} [options] Case sensitivity and zero-based occurrence.+ * @returns {FDocumentTextRange | null} The matching fixed text range, or `null` when no such occurrence exists.+ * @example+ * ```ts+ * const univerAPI = FUniver.newAPI(univer);+ * const document = univerAPI.getActiveDocument();+ * if (!document) throw new Error('No active document');+ *+ * const paragraph = document.findParagraphByText('Launch formula');+ * if (!paragraph) throw new Error('Target paragraph not found');+ *+ * const range = paragraph.findText('formula');+ * if (!range) throw new Error('Target text not found');+ *+ * console.log(range.describe());+ * ```+ */+ findText(text: string, options: IFDocumentFindTextOptions = {}): FDocumentTextRange | null {+ const occurrence = options.occurrence ?? 0;+ if (!Number.isInteger(occurrence) || occurrence < 0) {+ throw new RangeError('Text occurrence must be a non-negative integer.');+ }++ return this.findAllText(text, options)[occurrence] ?? null;+ }++ /**+ * Finds every non-overlapping literal text occurrence inside this paragraph.+ *+ * Results are ordered from the start of the paragraph. The returned ranges+ * are fixed when created; use them immediately and resolve new ranges after+ * edits that change earlier document content.+ *+ * @param {string} text Literal text to find. It must not be empty.+ * @param {Omit<IFDocumentFindTextOptions, 'occurrence'>} [options] Case-sensitivity option.+ * @returns {FDocumentTextRange[]} All matching fixed text ranges, or an empty array when no matches exist.+ * @example+ * ```ts+ * const univerAPI = FUniver.newAPI(univer);+ * const document = univerAPI.getActiveDocument();+ * if (!document) throw new Error('No active document');+ *+ * const paragraph = document.findParagraphByText('x plus x');+ * if (!paragraph) throw new Error('Target paragraph not found');+ *+ * const matches = paragraph.findAllText('x');+ * console.log(matches.map((range) => range.describe()));+ * ```+ */+ findAllText(+ text: string,+ options: Omit<IFDocumentFindTextOptions, 'occurrence'> = {}+ ): FDocumentTextRange[] {+ if (text.length === 0) {+ throw new TypeError('Text to find must not be empty.');+ }++ const matchCase = options.matchCase ?? true;+ const paragraphText = this.getText();+ const matcher = regexp.createLiteralRegExp(text, matchCase ? 'gu' : 'giu');+ const { startOffset } = this.getInfo();+ const matches: FDocumentTextRange[] = [];++ for (const match of paragraphText.matchAll(matcher)) {+ const matchStartOffset = startOffset + match.index;+ matches.push(this._injector.createInstance(+ FDocumentTextRange,+ this._document,+ matchStartOffset,+ matchStartOffset + match[0].length,+ this._segmentId,+ this._injector+ ));+ }++ return matches;+ }+/*** Get this paragraph's plain text.* @returns {string} The paragraph text without the trailing paragraph break.diff --git a/packages/docs/src/facade/f-document-text-range.ts b/packages/docs/src/facade/f-document-text-range.tsindex 9891299e10..7eddbba635 100644--- a/packages/docs/src/facade/f-document-text-range.ts+++ b/packages/docs/src/facade/f-document-text-range.ts@@ -18,6 +18,7 @@ import type { Injector, ITextStyle } from '@univerjs/core';import type { FDocument } from './f-document';import type { IFDocumentTextRange } from './utils';import { Tools, UpdateDocsAttributeType } from '@univerjs/core';+import { FBaseInitialable } from '@univerjs/core/facade';import { buildPlainTextInsertBody, replaceBodyRange, retainBodyRange } from './utils';/** A clipped text-style run in document offsets. */@@ -51,14 +52,15 @@ export interface IFDocumentTextRangeDescription extends IFDocumentTextRange {* that insert or remove content before it.* @hideconstructor*/-export class FDocumentTextRange {+export class FDocumentTextRange extends FBaseInitialable {constructor(- private readonly _document: FDocument,- private readonly _startOffset: number,- private readonly _endOffset: number,- private readonly _segmentId: string,- private readonly _injector: Injector+ protected readonly _document: FDocument,+ protected readonly _startOffset: number,+ protected readonly _endOffset: number,+ protected readonly _segmentId: string,+ protected override readonly _injector: Injector) {+ super(_injector);this._validateRange();}diff --git a/packages/docs/src/facade/index.ts b/packages/docs/src/facade/index.tsindex ce451b1091..f5364c879d 100644--- a/packages/docs/src/facade/index.ts+++ b/packages/docs/src/facade/index.ts@@ -19,7 +19,7 @@ import './f-enum';export { FDocument } from './f-document';export { FDocumentParagraph, isParagraphFacade } from './f-document-paragraph';-export type { IFDocumentParagraphInfo } from './f-document-paragraph';+export type { IFDocumentFindTextOptions, IFDocumentParagraphInfo } from './f-document-paragraph';export { DocsSectionUnsupportedDocumentFlavorError, FDocumentSection } from './f-document-section';export type { FDocumentSectionPageSetup, IFDocumentSectionColumnOptions, IFDocumentSectionDescription } from './f-document-section';export { FDocumentTextRange } from './f-document-text-range';diff --git a/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts b/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.tsindex d69f91b425..07ad9cdd1f 100644--- a/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts+++ b/packages/engine-render/src/components/docs/layout/block/paragraph/__tests__/shaping.spec.ts@@ -14,7 +14,8 @@* limitations under the License.*/-import { BooleanNumber, DataStreamTreeTokenType, PositionedObjectLayoutType } from '@univerjs/core';+import type { ICustomRangeForInterceptor } from '@univerjs/core';+import { BooleanNumber, CustomRangeType, DataStreamTreeTokenType, PositionedObjectLayoutType } from '@univerjs/core';import { describe, expect, it, vi } from 'vitest';import { Lang } from '../../../hyphenation/lang';import { createSkeletonLetterGlyph } from '../../../model/glyph';@@ -44,6 +45,138 @@ describe('shaping', () => {expect(allGlyphs.length).toBeGreaterThan(0);});+ it('shapes a hidden measured whole entity as one atomic glyph', () => {+ const source = String.raw`\sqrt{x^2 + 1}+\sum_{i=1}^{n} i^2`;+ const prefix = 'Formula: ';+ const content = `${prefix}${source} after`;+ const range: ICustomRangeForInterceptor = {+ startIndex: prefix.length,+ endIndex: prefix.length + source.length - 1,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ wholeEntity: true,+ show: false,+ glyphAscentEm: 1.75,+ glyphDescentEm: 1.25,+ glyphWidthEm: 7.25,+ };+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content, {+ body: { customRanges: [range] },+ });+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>+ index >= range.startIndex && index <= range.endIndex ? range : undefined+ );++ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);+ const allGlyphs = result.flatMap((item) => item.glyphs);+ const formulaGlyph = allGlyphs.find((glyph) => glyph.raw === source);+ let breakPosition = 0;+ const breakPositions = result.map((item) => {+ breakPosition += item.text.length;+ return breakPosition;+ });++ expect(formulaGlyph).toBeDefined();+ if (!formulaGlyph?.fontStyle) {+ throw new Error('Expected the measured whole entity to produce a font-backed glyph.');+ }+ const emSize = formulaGlyph.fontStyle.originFontSize / 0.75;+ expect(formulaGlyph.content).toBe('\u200B');+ expect(formulaGlyph.count).toBe(source.length);+ expect(formulaGlyph.width).toBeCloseTo(emSize * 7.25);+ expect(formulaGlyph.bBox.ba).toBeCloseTo(emSize * 1.75);+ expect(formulaGlyph.bBox.bd).toBeCloseTo(emSize * 1.25);+ expect(allGlyphs.filter((glyph) => glyph.raw === source)).toHaveLength(1);+ expect(breakPositions.some((position) =>+ position > range.startIndex && position <= range.endIndex+ )).toBe(false);+ });++ it('preserves the model text for a one-character measured whole entity', () => {+ const content = 'axb';+ const range: ICustomRangeForInterceptor = {+ startIndex: 1,+ endIndex: 1,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ wholeEntity: true,+ show: false,+ glyphAscentEm: 1,+ glyphDescentEm: 0,+ glyphWidthEm: 1,+ };+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content, {+ body: { customRanges: [range] },+ });+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>+ index === range.startIndex ? range : undefined+ );++ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);++ expect(result.map((item) => item.text).join('')).toBe(`${content}${DataStreamTreeTokenType.PARAGRAPH}`);+ expect(result.flatMap((item) => item.glyphs).filter((glyph) => glyph.raw === 'x')).toHaveLength(1);+ });++ it('keeps a hidden whole entity on the normal path until all glyph metrics are ready', () => {+ const source = 'abc';+ const range: ICustomRangeForInterceptor = {+ startIndex: 0,+ endIndex: source.length - 1,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ wholeEntity: true,+ show: false,+ glyphWidthEm: 3,+ };+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(source, {+ body: { customRanges: [range] },+ });+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>+ index >= range.startIndex && index <= range.endIndex ? range : undefined+ );++ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);+ const sourceGlyphs = result.flatMap((item) => item.glyphs).filter((glyph) => source.includes(glyph.raw));++ expect(sourceGlyphs.map((glyph) => glyph.raw).join('')).toBe(source);+ expect(sourceGlyphs).toHaveLength(source.length);+ });++ it('keeps visible whole-entity text on the normal shaping path', () => {+ const source = 'abc';+ const range: ICustomRangeForInterceptor = {+ startIndex: 0,+ endIndex: source.length - 1,+ rangeId: 'mention-1',+ rangeType: CustomRangeType.CUSTOM,+ wholeEntity: true,+ glyphWidthEm: 3,+ };+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(source, {+ body: { customRanges: [range] },+ });+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>+ index >= range.startIndex && index <= range.endIndex ? range : undefined+ );++ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);+ const sourceGlyphs = result.flatMap((item) => item.glyphs).filter((glyph) => source.includes(glyph.raw));++ expect(sourceGlyphs.map((glyph) => glyph.raw).join('')).toBe(source);+ expect(sourceGlyphs).toHaveLength(source.length);+ });++ it('does not add per-character custom-range discovery reads for plain text', () => {+ const content = 'a'.repeat(200);+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content);+ const getCustomRange = vi.spyOn(viewModel, 'getCustomRange');++ shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig);++ expect(getCustomRange.mock.calls.length).toBeLessThanOrEqual(paragraphNode.content!.length * 2);+ });+it('shapes text with tab characters', () => {const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed('Hello\tworld');@@ -314,6 +447,54 @@ describe('shaping', () => {}});+ it('shapes a measured whole entity atomically with useOpenType', () => {+ const source = String.raw`x+y`;+ const prefix = 'A ';+ const content = `${prefix}${source} B`;+ const range: ICustomRangeForInterceptor = {+ startIndex: prefix.length,+ endIndex: prefix.length + source.length - 1,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ wholeEntity: true,+ show: false,+ glyphAscentEm: 1,+ glyphDescentEm: 0.25,+ glyphWidthEm: 2,+ };+ const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed(content, {+ body: { customRanges: [range] },+ });+ vi.spyOn(viewModel, 'getCustomRange').mockImplementation((index) =>+ index >= range.startIndex && index <= range.endIndex ? range : undefined+ );+ const originalIsReady = fontLibrary.isReady;+ fontLibrary.isReady = true;+ const spy = vi.spyOn(textShapingModule, 'textShape').mockReturnValue(+ `${content}${DataStreamTreeTokenType.PARAGRAPH}`.split('').map((char, start) => ({+ char,+ start,+ end: start + 1,+ glyph: null,+ font: null,+ kerning: 0,+ boundingBox: null,+ }))+ );++ try {+ const result = shaping(ctx, paragraphNode.content!, viewModel, paragraphNode, sectionBreakConfig, true);+ const formulaGlyphs = result.flatMap((item) => item.glyphs).filter((glyph) => glyph.raw === source);++ expect(formulaGlyphs).toHaveLength(1);+ expect(formulaGlyphs[0].count).toBe(source.length);+ expect(formulaGlyphs[0].content).toBe('\u200B');+ } finally {+ spy.mockRestore();+ fontLibrary.isReady = originalIsReady;+ }+ });+it('shapes tab with useOpenType when font library is ready', () => {const { viewModel, ctx, paragraphNode, sectionBreakConfig } = createParagraphLayoutTestBed('Hello\tworld');const originalIsReady = fontLibrary.isReady;diff --git a/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts b/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.tsindex ef5934d9a0..841b1a6268 100644--- a/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts+++ b/packages/engine-render/src/components/docs/layout/block/paragraph/shaping.ts@@ -14,15 +14,17 @@* limitations under the License.*/-import type { IParagraphStyle, Nullable } from '@univerjs/core';+import type { ICustomRangeForInterceptor, IParagraph, IParagraphStyle, Nullable } from '@univerjs/core';import type { IDocumentSkeletonGlyph } from '../../../../../basics/i-document-skeleton-cached';import type { ISectionBreakConfig } from '../../../../../basics/interfaces';import type { DataStreamTreeNode } from '../../../view-model/data-stream-tree-node';import type { DocumentViewModel } from '../../../view-model/document-view-model';+import type { IBreakPoints } from '../../line-breaker/line-breaker';import type { IOpenTypeGlyphInfo } from '../../shaping-engine/text-shaping';import type { ILayoutContext } from '../../tools';import { BooleanNumber, DataStreamTreeTokenType, GridType, PositionedObjectLayoutType } from '@univerjs/core';import { cjk } from '../../../../../basics/cjk-regexp';+import { GlyphType } from '../../../../../basics/i-document-skeleton-cached';import {hasArabic,hasThai,@@ -35,12 +37,14 @@ import { LineBreaker } from '../../line-breaker';import { BreakPointType } from '../../line-breaker/break';import { LineBreakerHyphenEnhancer } from '../../line-breaker/enhancers/hyphen-enhancer';import { LineBreakerLinkEnhancer } from '../../line-breaker/enhancers/link-enhancer';+import { LineBreakerWholeEntityEnhancer } from '../../line-breaker/enhancers/whole-entity-enhancer';import { customBlockLineBreakExtension } from '../../line-breaker/extensions/custom-block-linebreak-extension';import { tabLineBreakExtension } from '../../line-breaker/extensions/tab-linebreak-extension';import {createSkeletonCustomBlockGlyph,createSkeletonLetterGlyph,createSkeletonTabGlyph,+ createSkeletonWholeEntityGlyph,glyphShrinkLeft,glyphShrinkRight,} from '../../model/glyph';@@ -48,7 +52,13 @@ import { getBoundingBox } from '../../model/line';import { fontLibrary } from '../../shaping-engine/font-library';import { textShape } from '../../shaping-engine/text-shaping';import { prepareParagraphBody } from '../../shaping-engine/utils';-import { getCharSpaceApply, getCustomRangeGlyphMetrics, getFontCreateConfig } from '../../tools';+import {+ getCharSpaceApply,+ getCustomRangeGlyphMetrics,+ getCustomRangeGlyphMetricsFromRange,+ getFontCreateConfig,+ isMeasuredWholeEntityRange,+} from '../../tools';import { ArabicHandler, emojiHandler, otherHandler, ThaiHandler, TibetanHandler } from './language-ruler';// Now we apply consecutive punctuation adjustment, specified in Chinese Layout@@ -119,6 +129,73 @@ export interface IShapedText {breakPointType: BreakPointType;}+function collectMeasuredWholeEntityRanges(+ content: string,+ viewModel: DocumentViewModel,+ paragraphNode: DataStreamTreeNode+): ICustomRangeForInterceptor[] {+ const ranges: ICustomRangeForInterceptor[] = [];+ const contentStartIndex = paragraphNode.startIndex;+ const contentEndIndex = contentStartIndex + content.length - 1;+ const customRanges = viewModel.getBody()?.customRanges ?? [];++ for (const customRange of customRanges) {+ if (+ !customRange.wholeEntity ||+ customRange.startIndex < contentStartIndex ||+ customRange.endIndex < customRange.startIndex ||+ customRange.endIndex > contentEndIndex+ ) {+ continue;+ }++ const interceptedRange = viewModel.getCustomRange(customRange.startIndex);+ if (+ interceptedRange?.rangeId === customRange.rangeId &&+ interceptedRange.startIndex === customRange.startIndex &&+ interceptedRange.endIndex === customRange.endIndex &&+ isMeasuredWholeEntityRange(interceptedRange)+ ) {+ ranges.push(interceptedRange);+ }+ }++ return ranges.sort((a, b) => a.startIndex - b.startIndex);+}++function createMeasuredWholeEntityGlyph(+ content: string,+ range: ICustomRangeForInterceptor,+ viewModel: DocumentViewModel,+ paragraphNode: DataStreamTreeNode,+ sectionBreakConfig: ISectionBreakConfig,+ paragraph: IParagraph+): IDocumentSkeletonGlyph | undefined {+ const relativeStartIndex = range.startIndex - paragraphNode.startIndex;+ const relativeEndIndex = range.endIndex - paragraphNode.startIndex + 1;+ const raw = content.slice(relativeStartIndex, relativeEndIndex);+ const config = getFontCreateConfig(relativeStartIndex, viewModel, paragraphNode, sectionBreakConfig, paragraph);+ const metrics = getCustomRangeGlyphMetricsFromRange(range, config);++ if (!raw || !metrics) {+ return undefined;+ }++ return createSkeletonWholeEntityGlyph(raw, config, metrics);+}++function getShapedGlyphText(glyph: IDocumentSkeletonGlyph): string {+ if (+ glyph.glyphType === GlyphType.PLACEHOLDER &&+ glyph.streamType === DataStreamTreeTokenType.LETTER &&+ glyph.raw !== glyph.content+ ) {+ return glyph.raw;+ }++ return glyph.content;+}+export function shaping(ctx: ILayoutContext,content: string,@@ -134,11 +211,20 @@ export function shaping(drawings = {},} = sectionBreakConfig;const shapedTextList: IShapedText[] = [];- let breaker = new LineBreaker(content);+ const lineBreaker = new LineBreaker(content);const { endIndex } = paragraphNode;const paragraph = viewModel.getParagraph(endIndex) || { startIndex: 0, paragraphId: 'para_render_fallback' };const { paragraphStyle = {} } = paragraph;const { snapToGrid = BooleanNumber.TRUE } = paragraphStyle;+ const measuredWholeEntityRanges = collectMeasuredWholeEntityRanges(content, viewModel, paragraphNode);+ const measuredWholeEntityRangeByStart = new Map(measuredWholeEntityRanges.map((range) => [+ range.startIndex - paragraphNode.startIndex,+ range,+ ]));+ const measuredWholeEntityRangeStarts = measuredWholeEntityRanges.map(+ (range) => range.startIndex - paragraphNode.startIndex+ );+ let measuredWholeEntityRangeIndex = 0;let last = 0;let bk;let lastGlyphIndex = 0;@@ -156,10 +242,10 @@ export function shaping(// console.log('Text Shaping Time:', +new Date() - now);// Add custom extension for linebreak.- tabLineBreakExtension(breaker);- customBlockLineBreakExtension(breaker);+ tabLineBreakExtension(lineBreaker);+ customBlockLineBreakExtension(lineBreaker);- breaker = new LineBreakerLinkEnhancer(breaker) as unknown as LineBreaker;+ let breaker: IBreakPoints = new LineBreakerLinkEnhancer(lineBreaker);const lang = languageDetector.detect(content);@@ -169,11 +255,16 @@ export function shaping(if (lang !== Lang.UNKNOWN && needHyphen) {// Use hyphen enhancer when the lang pattern is loaded.if (hyphen.hasPattern(lang)) {- breaker = new LineBreakerHyphenEnhancer(breaker, hyphen, lang, doNotHyphenateCaps) as unknown as LineBreaker;+ breaker = new LineBreakerHyphenEnhancer(breaker, hyphen, lang, doNotHyphenateCaps);} else {hyphen.loadPattern(lang);}}+ breaker = new LineBreakerWholeEntityEnhancer(+ breaker,+ measuredWholeEntityRanges,+ paragraphNode.startIndex+ );// eslint-disable-next-line no-cond-assignwhile ((bk = breaker.nextBreakPoint())) {@@ -197,8 +288,33 @@ export function shaping(}lastGlyphIndex = i;- for (const glyphInfo of glyphInfosInWord) {+ for (let glyphInfoIndex = 0; glyphInfoIndex < glyphInfosInWord.length; glyphInfoIndex++) {+ const glyphInfo = glyphInfosInWord[glyphInfoIndex];const { start, char } = glyphInfo;+ const measuredRange = measuredWholeEntityRangeByStart.get(start);++ if (measuredRange) {+ const glyph = createMeasuredWholeEntityGlyph(+ content,+ measuredRange,+ viewModel,+ paragraphNode,+ sectionBreakConfig,+ paragraph+ );+ if (glyph) {+ shapedGlyphs.push(glyph);+ const relativeEndIndex = measuredRange.endIndex - paragraphNode.startIndex + 1;+ while (+ glyphInfoIndex + 1 < glyphInfosInWord.length &&+ glyphInfosInWord[glyphInfoIndex + 1].start < relativeEndIndex+ ) {+ glyphInfoIndex++;+ }+ continue;+ }+ }+const config = getFontCreateConfig(start, viewModel, paragraphNode, sectionBreakConfig, paragraph);if (char === DataStreamTreeTokenType.TAB) {@@ -222,12 +338,40 @@ export function shaping(let src = word;let i = last;while (src.length > 0) {+ while (+ measuredWholeEntityRangeIndex < measuredWholeEntityRangeStarts.length &&+ measuredWholeEntityRangeStarts[measuredWholeEntityRangeIndex] < i+ ) {+ measuredWholeEntityRangeIndex++;+ }+const char = src.match(/^[\s\S]/gu)?.[0];if (char == null) {break;}+ const measuredRange = measuredWholeEntityRangeByStart.get(i);+ if (measuredRange) {+ const glyph = createMeasuredWholeEntityGlyph(+ content,+ measuredRange,+ viewModel,+ paragraphNode,+ sectionBreakConfig,+ paragraph+ );+ if (glyph) {+ shapedGlyphs.push(glyph);+ const count = measuredRange.endIndex - measuredRange.startIndex + 1;+ i += count;+ src = src.substring(count);+ measuredWholeEntityRangeIndex++;+ continue;+ }+ measuredWholeEntityRangeIndex++;+ }+if (char === DataStreamTreeTokenType.CUSTOM_BLOCK) {const config = getFontCreateConfig(i, viewModel, paragraphNode, sectionBreakConfig, paragraph);let newGlyph: Nullable<IDocumentSkeletonGlyph> = null;@@ -348,9 +492,13 @@ export function shaping(src = src.substring(step);} else {+ const nextMeasuredRangeStart = measuredWholeEntityRangeStarts[measuredWholeEntityRangeIndex];+ const sourceBeforeMeasuredRange = nextMeasuredRangeStart == null+ ? src+ : src.slice(0, nextMeasuredRangeStart - i);const { step, glyphGroup } = otherHandler(i,- src,+ sourceBeforeMeasuredRange,viewModel,paragraphNode,sectionBreakConfig,@@ -387,7 +535,7 @@ export function shaping(const lastShapedGlyphs = shapedGlyphsList[shapedGlyphsList.length - 1];for (const shapedGlyphs of shapedGlyphsList) {- const word = shapedGlyphs.map((g) => g.content).join('');+ const word = shapedGlyphs.map(getShapedGlyphText).join('');shapedTextList.push({text: word,diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/__tests__/whole-entity-enhancer.spec.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/__tests__/whole-entity-enhancer.spec.tsnew file mode 100644index 0000000000..cfdda5f591--- /dev/null+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/__tests__/whole-entity-enhancer.spec.ts@@ -0,0 +1,92 @@+/**+ * Copyright 2023-present DreamNum Co., Ltd.+ *+ * Licensed under the Apache License, Version 2.0 (the "License");+ * you may not use this file except in compliance with the License.+ * You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */++import type { ICustomRange } from '@univerjs/core';+import { CustomRangeType } from '@univerjs/core';+import { describe, expect, it } from 'vitest';+import { LineBreaker } from '../../line-breaker';+import { LineBreakerWholeEntityEnhancer } from '../whole-entity-enhancer';++function collectBreakPositions(content: string, ranges: readonly ICustomRange[], contentStartIndex = 0): number[] {+ const enhancer = new LineBreakerWholeEntityEnhancer(+ new LineBreaker(content),+ ranges,+ contentStartIndex+ );+ const positions: number[] = [];++ while (true) {+ const breakPoint = enhancer.nextBreakPoint();+ if (!breakPoint) {+ return positions;+ }+ positions.push(breakPoint.position);+ }+}++describe('LineBreakerWholeEntityEnhancer', () => {+ it('removes break opportunities inside a whole entity but preserves surrounding breaks', () => {+ const source = String.raw`\ce{Zn^2+ <=>[+ 2OH-] Zn(OH)2}`;+ const prefix = 'before ';+ const content = `${prefix}${source} after`;+ const startIndex = prefix.length;+ const endIndex = startIndex + source.length - 1;+ const positions = collectBreakPositions(content, [{+ startIndex,+ endIndex,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ }]);++ expect(positions.some((position) => position > startIndex && position <= endIndex)).toBe(false);+ expect(positions).toContain(content.length);+ });++ it('supports document offsets when shaping a paragraph segment', () => {+ const contentStartIndex = 20;+ const content = 'A B C';+ const positions = collectBreakPositions(content, [{+ startIndex: contentStartIndex + 2,+ endIndex: contentStartIndex + 4,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ }], contentStartIndex);++ expect(positions.some((position) => position > 2 && position <= 4)).toBe(false);+ });++ it('handles multiple ranges in model order even when the input is unsorted', () => {+ const content = 'A B C D E';+ const positions = collectBreakPositions(content, [+ {+ startIndex: 6,+ endIndex: 8,+ rangeId: 'formula-2',+ rangeType: CustomRangeType.CUSTOM,+ },+ {+ startIndex: 2,+ endIndex: 4,+ rangeId: 'formula-1',+ rangeType: CustomRangeType.CUSTOM,+ },+ ]);++ expect(positions.some((position) => position > 2 && position <= 4)).toBe(false);+ expect(positions.some((position) => position > 6 && position <= 8)).toBe(false);+ expect(positions).toContain(content.length);+ });+});diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.tsindex 682285e712..507bf5702c 100644--- a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/hyphen-enhancer.ts@@ -17,7 +17,7 @@import type { Nullable } from '@univerjs/core';import type { Hyphen } from '../../hyphenation/hyphen';import type { Lang } from '../../hyphenation/lang';-import type { IBreakPoints, LineBreaker } from '../line-breaker';+import type { IBreakPoints } from '../line-breaker';import { Break, BreakPointType } from '../break';import { getSlicePosition, getWord } from './utils';@@ -41,7 +41,7 @@ export class LineBreakerHyphenEnhancer implements IBreakPoints {public content = '';constructor(- private _lineBreaker: LineBreaker,+ private _lineBreaker: IBreakPoints,private _hyphen: Hyphen,private _lang: Lang,private _doNotHyphenateCaps = falsediff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.tsindex f96b1952db..6851a85712 100644--- a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/link-enhancer.ts@@ -15,7 +15,7 @@*/import type { Nullable } from '@univerjs/core';-import type { IBreakPoints, LineBreaker } from '../line-breaker';+import type { IBreakPoints } from '../line-breaker';import { Break, BreakPointType } from '../break';import { getSlicePosition } from './utils';@@ -114,7 +114,7 @@ export class LineBreakerLinkEnhancer implements IBreakPoints {public content = '';constructor(- private _lineBreaker: LineBreaker+ private _lineBreaker: IBreakPoints) {this.content = _lineBreaker.content;}diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/whole-entity-enhancer.ts b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/whole-entity-enhancer.tsnew file mode 100644index 0000000000..305ef24c00--- /dev/null+++ b/packages/engine-render/src/components/docs/layout/line-breaker/enhancers/whole-entity-enhancer.ts@@ -0,0 +1,64 @@+/**+ * Copyright 2023-present DreamNum Co., Ltd.+ *+ * Licensed under the Apache License, Version 2.0 (the "License");+ * you may not use this file except in compliance with the License.+ * You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */++import type { ICustomRange, Nullable } from '@univerjs/core';+import type { Break } from '../break';+import type { IBreakPoints } from '../line-breaker';++/**+ * Removes line-break opportunities from the interior of measured whole+ * entities. The model keeps the entity's complete source text, while shaping+ * treats the inclusive custom range as one unbreakable inline object.+ */+export class LineBreakerWholeEntityEnhancer implements IBreakPoints {+ readonly content: string;++ private readonly _ranges: readonly ICustomRange[];+ private _rangeIndex = 0;++ constructor(+ private readonly _lineBreaker: IBreakPoints,+ ranges: readonly ICustomRange[],+ private readonly _contentStartIndex: number+ ) {+ this.content = _lineBreaker.content;+ this._ranges = [...ranges].sort((a, b) => a.startIndex - b.startIndex);+ }++ nextBreakPoint(): Nullable<Break> {+ let breakPoint = this._lineBreaker.nextBreakPoint();++ while (breakPoint && this._isInsideWholeEntity(breakPoint.position)) {+ breakPoint = this._lineBreaker.nextBreakPoint();+ }++ return breakPoint;+ }++ private _isInsideWholeEntity(position: number): boolean {+ const absolutePosition = this._contentStartIndex + position;+ let range = this._ranges[this._rangeIndex];++ while (range && absolutePosition > range.endIndex) {+ this._rangeIndex++;+ range = this._ranges[this._rangeIndex];+ }++ return range != null &&+ absolutePosition > range.startIndex &&+ absolutePosition <= range.endIndex;+ }+}diff --git a/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts b/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.tsindex d78df91881..65dab9278d 100644--- a/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts+++ b/packages/engine-render/src/components/docs/layout/line-breaker/line-breaker.ts@@ -64,6 +64,7 @@ function mapFirst(c: number) {}export interface IBreakPoints {+ readonly content: string;nextBreakPoint(): Nullable<Break>;}diff --git a/packages/engine-render/src/components/docs/layout/model/glyph.ts b/packages/engine-render/src/components/docs/layout/model/glyph.tsindex 933d45c52d..4cdff65efa 100644--- a/packages/engine-render/src/components/docs/layout/model/glyph.ts+++ b/packages/engine-render/src/components/docs/layout/model/glyph.ts@@ -112,6 +112,35 @@ export function createSkeletonLetterGlyph(return glyph;}+const WHOLE_ENTITY_RENDER_MARKER = '\u200B';++/**+ * Creates one non-text skeleton glyph for a whole entity whose source spans+ * multiple model characters. `raw` and `count` retain the source mapping.+ *+ * The zero-width marker keeps the glyph in the document paint loop so a+ * component extension can render the entity, without painting its model+ * source as ordinary text.+ */+export function createSkeletonWholeEntityGlyph(+ raw: string,+ config: IFontCreateConfig,+ glyphMetrics: { ascent?: number; descent?: number; width?: number }+): IDocumentSkeletonGlyph {+ const glyph = createSkeletonLetterGlyph(raw, config, glyphMetrics);++ glyph.adjustability = baseAdjustability(WHOLE_ENTITY_RENDER_MARKER, glyph.width);+ glyph.bBox.width = glyph.width;+ glyph.content = WHOLE_ENTITY_RENDER_MARKER;+ glyph.count = raw.length;+ glyph.glyphType = GlyphType.PLACEHOLDER;+ glyph.isJustifiable = false;+ glyph.raw = raw;+ glyph.streamType = DataStreamTreeTokenType.LETTER;++ return glyph;+}+export function createSkeletonTabGlyph(config: IFontCreateConfig, glyphWidth?: number): IDocumentSkeletonGlyph {return _createSkeletonWordOrLetter(GlyphType.TAB, DataStreamTreeTokenType.TAB, config, glyphWidth);}diff --git a/packages/engine-render/src/components/docs/layout/tools.ts b/packages/engine-render/src/components/docs/layout/tools.tsindex fad2235e75..2f69ee8b80 100644--- a/packages/engine-render/src/components/docs/layout/tools.ts+++ b/packages/engine-render/src/components/docs/layout/tools.ts@@ -17,6 +17,7 @@import type {DocumentDataModel,IBullet,+ ICustomRangeForInterceptor,IDocumentStyle,INumberUnit,IObjectPositionH,@@ -1525,6 +1526,28 @@ export function getCustomRangeGlyphWidth(return getCustomRangeGlyphMetrics(index, viewModel, paragraphNode, config)?.width;}+/**+ * Returns whether a custom range should occupy one measured glyph in the+ * document skeleton while preserving its complete source text in the model.+ *+ * Visible whole-entity ranges such as mentions keep their existing shaping.+ * The atomic behavior is reserved for hidden ranges whose renderer provides+ * explicit glyph metrics, such as an inline formula.+ */+export function isMeasuredWholeEntityRange(+ customRange: Nullable<ICustomRangeForInterceptor>+): customRange is ICustomRangeForInterceptor {+ if (!customRange?.wholeEntity || customRange.show !== false) {+ return false;+ }++ return [+ customRange.glyphAscentEm,+ customRange.glyphDescentEm,+ customRange.glyphWidthEm,+ ].every((value) => typeof value === 'number' && Number.isFinite(value) && value >= 0);+}+export function getCustomRangeGlyphMetrics(index: number,viewModel: DocumentViewModel,@@ -1536,6 +1559,13 @@ export function getCustomRangeGlyphMetrics(return undefined;}+ return getCustomRangeGlyphMetricsFromRange(customRange, config);+}++export function getCustomRangeGlyphMetricsFromRange(+ customRange: ICustomRangeForInterceptor,+ config: IFontCreateConfig+): { ascent?: number; descent?: number; width?: number } | undefined {const fontSize = ptToPixel(config.fontStyle.originFontSize);const toPixels = (value: unknown) =>typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value * fontSize : undefined;