@univerjs-pro/engine-shape 0.19.0 → 0.20.0

package/lib/types/index.d.ts

@@ -1,8 +1,8 @@
 export { BasicShapeModel as ShapeModel } from '../src/model/shape-model';
 export { LineShapeRenderModel } from '../src/render-engine/line-shape-render-model';
 export { BaseShapeRenderModel } from '../src/render-engine/shape-render-model';
-export { BasicShapeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from '../src/shape-enum';
-export type { IConnectorLayoutResult, IConnectorRouteLayoutResult, IConnectPointInfo, ICustomShapeTextData, ICxnShapeData, IDrawingRect, IGdContext, IGdContextBase, ILineType, IPathCommand, IPresetShapeConfig, IShapeAdjustItem, IShapeAdjustItemResolved, IShapeContextOptions, IBasicShapeData as IShapeData, IShapeHitTestResult, IShapeJSONData, IShapeLineStyle, IShapeModel, IShapePath, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeText, ShapeAdjustHandleTypeEnum, ShapeHitTestHitTypeEnum, } from '../src/shape-type';
+export { BasicShapeEnum, ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from '../src/shape-enum';
+export type { IBasicShapeData, IConnectorLayoutResult, IConnectorRouteLayoutResult, IConnectPointInfo, ICustomShapeTextData, ICxnShapeData, IDrawingRect, IGdContext, IGdContextBase, ILineType, IPathCommand, IPresetShapeConfig, IShapeAdjustItem, IShapeAdjustItemResolved, IShapeContextOptions, IShapeData, IShapeHitTestResult, IShapeJSONData, IShapeLineStyle, IShapeModel, IShapePath, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeText, ShapeAdjustHandleTypeEnum, ShapeHitTestHitTypeEnum, } from '../src/shape-type';
 export { AccentBorderCallout1Shape } from '../src/shapes/accent-border-callout1-shape';
 export { AccentBorderCallout2Shape } from '../src/shapes/accent-border-callout2-shape';
 export { AccentBorderCallout3Shape } from '../src/shapes/accent-border-callout3-shape';

package/lib/types/model/shape-model.d.ts

@@ -1,11 +1,11 @@
 import type { ShapeTypeEnum } from '../shape-enum';
-import type { IBasicShapeData, ICustomShapeTextData, IGdContext, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeContextOptions, IShapeJSONData, IShapeModel, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeText } from '../shape-type';
+import type { ICustomShapeTextData, IGdContext, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeContextOptions, IShapeData, IShapeJSONData, IShapeModel, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeText } from '../shape-type';
 import { BasicShapeEnum } from '../shape-enum';
 export declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
 export declare class BasicShapeModel implements IShapeModel {
     protected _shapeType: ShapeTypeEnum;
     private readonly _id;
-    protected _shapeData: IBasicShapeData;
+    protected _shapeData: IShapeData;
     /**
      * this property is only used for LineShapeRenderModel to indicate whether to render line points for routing
      */
@@ -13,8 +13,8 @@ export declare class BasicShapeModel implements IShapeModel {
     private _context;
     private _renderModel;
     private _adjustNameMap;
-    constructor(shapeType: ShapeTypeEnum, id: string, shapeData?: IBasicShapeData);
-    changeShapeType(shapeType: ShapeTypeEnum, shapeData?: IBasicShapeData): void;
+    constructor(shapeType: ShapeTypeEnum, id: string, shapeData?: IShapeData);
+    changeShapeType(shapeType: ShapeTypeEnum, shapeData?: IShapeData): void;
     getShapeType(): ShapeTypeEnum;
     getShapeRelation(): IShapeRelation | undefined;
     getBasicShapeType(): BasicShapeEnum;
@@ -35,9 +35,9 @@ export declare class BasicShapeModel implements IShapeModel {
      * @returns {IShapeRect} The shape text rect, the position is relative to the shape rect
      */
     getShapeTextRect(rect: IShapeRect): IShapeRect;
-    setShapeType(shapeType: ShapeTypeEnum, shapeData?: IBasicShapeData): void;
-    getShapeData(): IBasicShapeData;
-    setShapeData(shapeData: IBasicShapeData, merge?: boolean): void;
+    setShapeType(shapeType: ShapeTypeEnum): void;
+    getShapeData(): IShapeData;
+    setShapeData(shapeData: IShapeData, merge?: boolean): void;
     getPresetShapeConfig(): IPresetShapeConfig;
     getAdjustNames(): string[];
     /**
@@ -105,6 +105,13 @@ export declare class BasicShapeModel implements IShapeModel {
      */
     isHitLine(pointX: number, pointY: number, width: number, height: number, tolerance?: number): boolean;
     render(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, renderOption: IShapeRenderParameters): void;
+    /**
+     * Build the shape outline path on the canvas context and clip.
+     * This only builds paths and clips — no fill or stroke is applied.
+     * Coordinate system: (0,0) is at the top-left of the rect.
+     * @returns The actual bounding rect of the clip region, or false if no clip was built
+     */
+    buildClipPath(canvasContext: CanvasRenderingContext2D, rect: IShapeRect): IShapeRect | false;
     getDrawingPoints(): IShapePointWithAdjName[];
     calcAdjValue(rect: IShapeRect, point: IShapePoint, adjustInfo: IShapeAdjustItemResolved, isFlipH: boolean, isFlipV: boolean): number;
     dispose(): void;

package/lib/types/render-engine/shape-render-model.d.ts

@@ -24,14 +24,51 @@ export declare abstract class BaseShapeRenderModel {
      * @returns {IShapeRect} The text rectangle within the shape
      */
     getTextRect(rect: IShapeRect, gdRecord: Partial<IGdContext>): IShapeRect;
+    /**
+     * Compute the actual bounding box of all fillable paths (fill !== 'none').
+     * For multi-path shapes (e.g. cloudCallout), sub-paths may extend beyond the
+     * drawing rect. This method returns the real bounding box so that image/gradient
+     * fills can cover the complete shape area.
+     *
+     * Coordinate system: same as render() after translate(-width/2, -height/2),
+     * i.e. (0,0) is at the top-left of the drawing rect.
+     */
+    computeFillableBounds(rect: IShapeRect, shapeContext: BaseShapeContext): IShapeRect;
     /**
      * 使用 Canvas API 渲染形状
      */
     render(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, shapeContext: BaseShapeContext, shapeData: IShapeData, renderOption: IShapeRenderParameters): void;
+    /**
+     * Build just the shape outline path on the canvas context and clip.
+     * Unlike render(), this does NOT fill or stroke — only builds the path and calls clip().
+     * Coordinate system: (0,0) is at the top-left, (width,height) at the bottom-right.
+     *
+     * Only fillable paths (fill !== 'none') participate in the clip region.
+     * For multi-path shapes (e.g. cloudCallout), some sub-paths may extend beyond the
+     * drawing rect. The returned IShapeRect reports the actual bounding box of the clip
+     * so the caller can size the image fill accordingly.
+     *
+     * @returns The actual bounding rect of the clip region, or false if no clip was built
+     */
+    buildClipPath(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, shapeContext: BaseShapeContext): IShapeRect | false;
     private _getDashType;
     private _getCapType;
     private _getJoinType;
     private _getStrokeWidth;
+    /**
+     * Fill the current path with an image, replicating Excel's picture-fill pipeline:
+     *   image → srcRect (crop) → Stretch / Tile → clip to shape path
+     *
+     * Coordinate system: we are already inside a `save/translate(-w/2, -h/2)` block,
+     * so (0,0) is the top-left of the shape bounding box.
+     *
+     * @param canvasContext  Active 2D context
+     * @param rect           Shape bounding rect (width/height in display pixels)
+     * @param shapeData      IBasicShapeData carrying fill configuration
+     * @param image          Pre-loaded HTMLImageElement
+     * @param fillRule       Current path fill rule flag from IShapePath
+     */
+    private _fillPicture;
     /**
      * Create a gradient based on the shape's fill configuration
      * @param canvasContext The canvas rendering context
@@ -65,9 +102,30 @@ export declare abstract class BaseShapeRenderModel {
     private _addGradientStops;
     private _getFillStyle;
     private _getStrokeStyle;
+    /**
+     * For modifier fill paths (darkenLess, darken, lighten, lightenLess),
+     * overlay a semi-transparent black or white fill on top of the current path
+     * to simulate the OOXML brightness adjustment.
+     *
+     * This matches what solid fill does via ColorUtil._adjust:
+     *   darken   → -30% brightness  →  overlay black at 30% opacity
+     *   darkenLess → -12%           →  overlay black at 12% opacity
+     *   lighten  → +30%             →  overlay white at 30% opacity
+     *   lightenLess → +12%          →  overlay white at 12% opacity
+     */
+    private _applyFillModifierOverlay;
     private _renderTextBox;
     private _renderCxnPoints;
     private _getValueFromGdRecord;
+    /**
+     * Walk a single path's commands, scaling coordinates and accumulating
+     * into the provided bounding-box tracker.
+     */
+    private _accumulatePathBounds;
+    /**
+     * Apply coordinate scaling to resolved path points in-place.
+     */
+    private _scalePathPoints;
     /**
      * Check if the adjust handle at the given index has an inverse relationship.
      * Uses cache to avoid recalculating.

package/lib/types/shape-enum.d.ts

@@ -329,8 +329,35 @@ export declare enum ShapeArrowSizeEnum {
  * - HandDrawn – heavy rough deformation rendered in two overlapping passes
  */
 export declare enum ShapeSketchTypeEnum {
-    None = 0,
-    Curved = 1,
-    Freehand = 2,
-    HandDrawn = 3
+    None = 1,
+    Curved = 2,
+    Freehand = 3,
+    HandDrawn = 4
+}
+/**
+ * The type of image data source
+ */
+export declare enum ImageSourceTypeEnum {
+    /**
+     * The image source is a URL, for example: https://avatars.githubusercontent.com/u/61444807?s=48&v=4
+     */
+    URL = "URL",
+    /**
+     * The image source is a UUID, this ID is generated by the Univer image hosting service. For specific generation rules, please refer to the Univer image hosting service API documentation.
+     */
+    UUID = "UUID",
+    /**
+     * The image source is BASE64, for example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAALCAYAAAB7ZJ...
+     */
+    BASE64 = "BASE64"
+}
+/**
+ * The image fill mode when ShapeFillEnum is PictureFill
+ */
+export declare enum ImageFillModeEnum {
+    Stretch = 1,
+    /**
+     * Tile: The image is repeated (tiled) to fill the shape's area.
+     */
+    Tile = 2
 }

package/lib/types/shape-type.d.ts

@@ -1,4 +1,4 @@
-import type { BasicShapeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from './shape-enum';
+import type { BasicShapeEnum, ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from './shape-enum';
 /**
  * GdContext 用来计算 OOXML Shape 的 Geometry Definitions (gd)
  * 包含：
@@ -581,6 +581,52 @@ export interface IBasicShapeData {
             position: number;
             color: string;
         }>;
+        /**
+         * Image fill source, can be a URL or base64 data URI. When fillType is 'image', this specifies the image to use for filling the shape.
+         */
+        fillImageSource?: string;
+        /**
+         * Image source type for fillImageSource
+         */
+        fillImageSourceType?: ImageSourceTypeEnum;
+        /**
+         * Image fill mode, defines how the image is applied to the shape. The options include:Stretch & Tile.
+         * Defaults to Stretch when not specified.
+         */
+        imageFillMode?: ImageFillModeEnum;
+        /**
+         * The stretch fill rect defines the portion of the shape's bounding box that the image should be stretched to fill. This is used when imageFillMode is set to Stretch. The values are typically in percentage (0-100%) of the shape's dimensions, allowing for flexible scaling of the fill image within the shape.
+         */
+        stretchFillRect?: {
+            left: number;
+            top: number;
+            bottom: number;
+            right: number;
+        };
+        /**
+         * The crop rect of image, the unit of value is percentage.
+         */
+        srcRect?: {
+            left: number;
+            top: number;
+            bottom: number;
+            right: number;
+        };
+        imageTile?: {
+            scaleX?: number;
+            scaleY?: number;
+            offsetX?: number;
+            offsetY?: number;
+            alignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
+        };
+        /**
+         * The opacity of the fill image, ranging from 0 (completely transparent) to 1 (completely opaque).
+         */
+        imageOpacity?: number;
+        /**
+         * Whether the fill image should rotate with the shape. The default value is false, meaning the image will maintain its orientation regardless of the shape's rotation.
+         */
+        imageRotateWithShape?: boolean;
     };
     stroke?: IShapeLineStyle;
     adjustValues?: Record<string, number>;
@@ -747,6 +793,7 @@ export interface IShapeRenderParameters {
     flipV?: boolean;
     angle?: number;
     oKey: string;
+    image?: HTMLImageElement;
 }
 export interface IShapeRelationItem {
     shapeId: string;