Skip to content

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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,