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
docs(drawing): clarify document wrapping behavior (#7330)
Univere7ecb0f6ad3f
diff --git a/packages/core/src/types/interfaces/i-document-data.ts b/packages/core/src/types/interfaces/i-document-data.tsindex 95ee126681..123709d473 100644--- a/packages/core/src/types/interfaces/i-document-data.ts+++ b/packages/core/src/types/interfaces/i-document-data.ts@@ -727,15 +727,25 @@ export enum WrapTextType {}/**- * The possible layouts of a [PositionedObject]+ * Controls how a positioned object participates in document text layout.+ *+ * `WRAP_NONE` does not by itself determine whether the object is in front of or behind text. Drawing data uses+ * `behindDoc` for that stacking choice.*/export enum PositionedObjectLayoutType {+ /** Places the object in the text flow like a character and lets it affect the containing line's metrics. */INLINE,+ /** Floats the object without reflowing text. The object and text can overlap. */WRAP_NONE,+ /** Floats the object and wraps text around the custom polygon defined by its wrap path. */WRAP_POLYGON,+ /** Floats the object and wraps text around its rectangular bounds. */WRAP_SQUARE,+ /** Floats the object and allows text to flow through eligible open regions in its wrap contour. */WRAP_THROUGH,+ /** Floats the object and wraps text closely around its contour instead of its rectangular bounds. */WRAP_TIGHT,+ /** Floats the object in a horizontal band, leaving text only above and below it. */WRAP_TOP_AND_BOTTOM,}diff --git a/packages/docs-drawing/src/commands/commands/update-doc-drawing-wrapping-style.command.ts b/packages/docs-drawing/src/commands/commands/update-doc-drawing-wrapping-style.command.tsindex a4eb204fcd..830db9517b 100644--- a/packages/docs-drawing/src/commands/commands/update-doc-drawing-wrapping-style.command.ts+++ b/packages/docs-drawing/src/commands/commands/update-doc-drawing-wrapping-style.command.ts@@ -29,11 +29,43 @@ import {} from '@univerjs/core';import { RichTextEditingMutation } from '@univerjs/docs';+/**+ * Controls how a document drawing participates in text layout.+ *+ * `INLINE`, `WRAP_SQUARE`, and `WRAP_TOP_AND_BOTTOM` participate in text layout and can cause text to reflow.+ * `BEHIND_TEXT` and `IN_FRONT_OF_TEXT` are overlay styles and do not cause text to reflow.+ */export enum TextWrappingStyle {+ /**+ * Places the drawing in the text flow like a character.+ *+ * The drawing occupies layout space and does not overlap surrounding text. Its position is determined by its+ * document range, so floating position settings have no visible effect.+ */INLINE = 'inline',+ /**+ * Floats the drawing behind document text without causing the text to reflow.+ *+ * Use this style for backgrounds or watermarks. Text can overlap the drawing, so ensure that it remains readable.+ */BEHIND_TEXT = 'behindText',+ /**+ * Floats the drawing in front of document text without causing the text to reflow.+ *+ * The drawing can cover overlapping text. Use this style only when an overlay is intentional.+ */IN_FRONT_OF_TEXT = 'inFrontOfText',+ /**+ * Floats the drawing and wraps text around its rectangular bounds.+ *+ * Use this style for images that should appear beside body text, such as portraits or illustrations.+ */WRAP_SQUARE = 'wrapSquare',+ /**+ * Floats the drawing in a horizontal band, with text only above and below it.+ *+ * Use this style for wide figures or standalone illustrations that should not have text beside them.+ */WRAP_TOP_AND_BOTTOM = 'wrapTopAndBottom',}diff --git a/packages/docs-drawing/src/facade/f-document-image.ts b/packages/docs-drawing/src/facade/f-document-image.tsindex 1f671eb28e..df90e4c61e 100644--- a/packages/docs-drawing/src/facade/f-document-image.ts+++ b/packages/docs-drawing/src/facade/f-document-image.ts@@ -286,6 +286,11 @@ export class FDocumentImage {/*** Sets the image wrapping style.+ *+ * Use `INLINE` to place the image in the text flow, `WRAP_SQUARE` to flow text beside it, or+ * `WRAP_TOP_AND_BOTTOM` to keep text above and below it. `BEHIND_TEXT` and `IN_FRONT_OF_TEXT` do not reserve space+ * in the text layout and can overlap text.+ ** When switching from inline to a floating style in a UI environment, the current visual position is preserved.* @param {TextWrappingStyle} wrappingStyle The wrapping style to apply.* @returns {boolean} `true` when the update command succeeds; otherwise, `false`.@@ -295,6 +300,7 @@ export class FDocumentImage {* const image = fDocument.getImages()[0];** if (image) {+ * // Float the image beside body text without covering it.* const success = image.setWrappingStyle(univerAPI.Enum.DocsImageWrappingStyle.WRAP_SQUARE);* console.log(success);* }diff --git a/packages/docs-drawing/src/facade/f-document.ts b/packages/docs-drawing/src/facade/f-document.tsindex 9c77fbeabd..f48c1b2eb0 100644--- a/packages/docs-drawing/src/facade/f-document.ts+++ b/packages/docs-drawing/src/facade/f-document.ts@@ -58,7 +58,13 @@ export interface IFDocumentInsertImageOptions {* It has a visible positioning effect only when `wrappingStyle` is not `INLINE`.*/positionV?: IObjectPositionV;- /** The image wrapping style. Defaults to `TextWrappingStyle.INLINE`. */+ /**+ * The image wrapping style. Defaults to `TextWrappingStyle.INLINE`.+ *+ * Use `INLINE` to place the image in the text flow, `WRAP_SQUARE` to flow text beside it, or+ * `WRAP_TOP_AND_BOTTOM` to keep text above and below it. `BEHIND_TEXT` and `IN_FRONT_OF_TEXT` are overlay styles:+ * they do not reserve space in the text layout, so text and the image can overlap.+ */wrappingStyle?: TextWrappingStyle;/** The document range at which to insert the image. The current selection is used when omitted. */textRange?: ITextRangeParam;@@ -70,6 +76,9 @@ export interface IFDocumentImageMixin {* Inserts an image into the document.** When width and height are both omitted, the intrinsic size is proportionally limited to 500 by 500 pixels.+ * For ordinary content, prefer `INLINE`, `WRAP_SQUARE`, or `WRAP_TOP_AND_BOTTOM`. Use `BEHIND_TEXT` for+ * backgrounds or watermarks and `IN_FRONT_OF_TEXT` only for intentional overlays, because these two styles do not+ * cause text to reflow.** @param {IFDocumentInsertImageOptions} options The image source, optional transform, and insertion range.* @returns {Promise<FDocumentImage | null>} The inserted image facade, or `null` when the insertion command fails.@@ -80,6 +89,8 @@ export interface IFDocumentImageMixin {* source: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',* imageSourceType: univerAPI.Enum.ImageSourceType.URL,* width: 320,+ * // Keep the image in the text flow so it cannot cover surrounding text.+ * wrappingStyle: univerAPI.Enum.DocsImageWrappingStyle.INLINE,* textRange: {* startOffset: 30,* },@@ -94,6 +105,7 @@ export interface IFDocumentImageMixin {* source: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',* imageSourceType: univerAPI.Enum.ImageSourceType.URL,* width: 320,+ * // Float the image and let body text flow beside its rectangular bounds.* wrappingStyle: univerAPI.Enum.DocsImageWrappingStyle.WRAP_SQUARE,* textRange: {* startOffset: 30,diff --git a/packages/docs-drawing/src/facade/f-enum.ts b/packages/docs-drawing/src/facade/f-enum.tsindex 519edfbb35..67e67a3a78 100644--- a/packages/docs-drawing/src/facade/f-enum.ts+++ b/packages/docs-drawing/src/facade/f-enum.ts@@ -24,6 +24,9 @@ import { TextWrappingStyle } from '@univerjs/docs-drawing';export interface IFDocumentImageEnumMixin {/*** Represents the wrapping styles used by docs image operations.+ *+ * Prefer `INLINE`, `WRAP_SQUARE`, or `WRAP_TOP_AND_BOTTOM` for ordinary document content.+ * `BEHIND_TEXT` and `IN_FRONT_OF_TEXT` are overlay styles that do not cause text to reflow.* @example* ```ts* const fDocument = univerAPI.getActiveDocument();@@ -31,6 +34,7 @@ export interface IFDocumentImageEnumMixin {* source: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',* imageSourceType: univerAPI.Enum.ImageSourceType.URL,* width: 320,+ * // Float the image and wrap body text around its rectangular bounds.* wrappingStyle: univerAPI.Enum.DocsImageWrappingStyle.WRAP_SQUARE,* textRange: {* startOffset: 30,