@univerjs-pro/engine-shape 0.18.0 → 0.19.0-insiders.20260403-3e0e122

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,8 +1,8 @@
1
1
  export { BasicShapeModel as ShapeModel } from '../src/model/shape-model';
2
2
  export { LineShapeRenderModel } from '../src/render-engine/line-shape-render-model';
3
3
  export { BaseShapeRenderModel } from '../src/render-engine/shape-render-model';
4
- export { BasicShapeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeTypeEnum } from '../src/shape-enum';
5
- 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';
4
+ export { BasicShapeEnum, ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from '../src/shape-enum';
5
+ 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';
6
6
  export { AccentBorderCallout1Shape } from '../src/shapes/accent-border-callout1-shape';
7
7
  export { AccentBorderCallout2Shape } from '../src/shapes/accent-border-callout2-shape';
8
8
  export { AccentBorderCallout3Shape } from '../src/shapes/accent-border-callout3-shape';
@@ -1,11 +1,11 @@
1
1
  import type { ShapeTypeEnum } from '../shape-enum';
2
- import type { IBasicShapeData, ICustomShapeTextData, IGdContext, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeContextOptions, IShapeJSONData, IShapeModel, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeText } from '../shape-type';
2
+ import type { ICustomShapeTextData, IGdContext, IPresetShapeConfig, IShapeAdjustItemResolved, IShapeContextOptions, IShapeData, IShapeJSONData, IShapeModel, IShapePoint, IShapePointWithAdjName, IShapeRect, IShapeRelation, IShapeRelationItem, IShapeRenderParameters, IShapeText } from '../shape-type';
3
3
  import { BasicShapeEnum } from '../shape-enum';
4
4
  export declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
5
5
  export declare class BasicShapeModel implements IShapeModel {
6
6
  protected _shapeType: ShapeTypeEnum;
7
7
  private readonly _id;
8
- protected _shapeData: IBasicShapeData;
8
+ protected _shapeData: IShapeData;
9
9
  /**
10
10
  * this property is only used for LineShapeRenderModel to indicate whether to render line points for routing
11
11
  */
@@ -13,8 +13,8 @@ export declare class BasicShapeModel implements IShapeModel {
13
13
  private _context;
14
14
  private _renderModel;
15
15
  private _adjustNameMap;
16
- constructor(shapeType: ShapeTypeEnum, id: string, shapeData?: IBasicShapeData);
17
- changeShapeType(shapeType: ShapeTypeEnum, shapeData?: IBasicShapeData): void;
16
+ constructor(shapeType: ShapeTypeEnum, id: string, shapeData?: IShapeData);
17
+ changeShapeType(shapeType: ShapeTypeEnum, shapeData?: IShapeData): void;
18
18
  getShapeType(): ShapeTypeEnum;
19
19
  getShapeRelation(): IShapeRelation | undefined;
20
20
  getBasicShapeType(): BasicShapeEnum;
@@ -35,9 +35,9 @@ export declare class BasicShapeModel implements IShapeModel {
35
35
  * @returns {IShapeRect} The shape text rect, the position is relative to the shape rect
36
36
  */
37
37
  getShapeTextRect(rect: IShapeRect): IShapeRect;
38
- setShapeType(shapeType: ShapeTypeEnum, shapeData?: IBasicShapeData): void;
39
- getShapeData(): IBasicShapeData;
40
- setShapeData(shapeData: IBasicShapeData, merge?: boolean): void;
38
+ setShapeType(shapeType: ShapeTypeEnum): void;
39
+ getShapeData(): IShapeData;
40
+ setShapeData(shapeData: IShapeData, merge?: boolean): void;
41
41
  getPresetShapeConfig(): IPresetShapeConfig;
42
42
  getAdjustNames(): string[];
43
43
  /**
@@ -105,6 +105,13 @@ export declare class BasicShapeModel implements IShapeModel {
105
105
  */
106
106
  isHitLine(pointX: number, pointY: number, width: number, height: number, tolerance?: number): boolean;
107
107
  render(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, renderOption: IShapeRenderParameters): void;
108
+ /**
109
+ * Build the shape outline path on the canvas context and clip.
110
+ * This only builds paths and clips — no fill or stroke is applied.
111
+ * Coordinate system: (0,0) is at the top-left of the rect.
112
+ * @returns The actual bounding rect of the clip region, or false if no clip was built
113
+ */
114
+ buildClipPath(canvasContext: CanvasRenderingContext2D, rect: IShapeRect): IShapeRect | false;
108
115
  getDrawingPoints(): IShapePointWithAdjName[];
109
116
  calcAdjValue(rect: IShapeRect, point: IShapePoint, adjustInfo: IShapeAdjustItemResolved, isFlipH: boolean, isFlipV: boolean): number;
110
117
  dispose(): void;
@@ -24,14 +24,51 @@ export declare abstract class BaseShapeRenderModel {
24
24
  * @returns {IShapeRect} The text rectangle within the shape
25
25
  */
26
26
  getTextRect(rect: IShapeRect, gdRecord: Partial<IGdContext>): IShapeRect;
27
+ /**
28
+ * Compute the actual bounding box of all fillable paths (fill !== 'none').
29
+ * For multi-path shapes (e.g. cloudCallout), sub-paths may extend beyond the
30
+ * drawing rect. This method returns the real bounding box so that image/gradient
31
+ * fills can cover the complete shape area.
32
+ *
33
+ * Coordinate system: same as render() after translate(-width/2, -height/2),
34
+ * i.e. (0,0) is at the top-left of the drawing rect.
35
+ */
36
+ computeFillableBounds(rect: IShapeRect, shapeContext: BaseShapeContext): IShapeRect;
27
37
  /**
28
38
  * 使用 Canvas API 渲染形状
29
39
  */
30
40
  render(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, shapeContext: BaseShapeContext, shapeData: IShapeData, renderOption: IShapeRenderParameters): void;
41
+ /**
42
+ * Build just the shape outline path on the canvas context and clip.
43
+ * Unlike render(), this does NOT fill or stroke — only builds the path and calls clip().
44
+ * Coordinate system: (0,0) is at the top-left, (width,height) at the bottom-right.
45
+ *
46
+ * Only fillable paths (fill !== 'none') participate in the clip region.
47
+ * For multi-path shapes (e.g. cloudCallout), some sub-paths may extend beyond the
48
+ * drawing rect. The returned IShapeRect reports the actual bounding box of the clip
49
+ * so the caller can size the image fill accordingly.
50
+ *
51
+ * @returns The actual bounding rect of the clip region, or false if no clip was built
52
+ */
53
+ buildClipPath(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, shapeContext: BaseShapeContext): IShapeRect | false;
31
54
  private _getDashType;
32
55
  private _getCapType;
33
56
  private _getJoinType;
34
57
  private _getStrokeWidth;
58
+ /**
59
+ * Fill the current path with an image, replicating Excel's picture-fill pipeline:
60
+ * image → srcRect (crop) → Stretch / Tile → clip to shape path
61
+ *
62
+ * Coordinate system: we are already inside a `save/translate(-w/2, -h/2)` block,
63
+ * so (0,0) is the top-left of the shape bounding box.
64
+ *
65
+ * @param canvasContext Active 2D context
66
+ * @param rect Shape bounding rect (width/height in display pixels)
67
+ * @param shapeData IBasicShapeData carrying fill configuration
68
+ * @param image Pre-loaded HTMLImageElement
69
+ * @param fillRule Current path fill rule flag from IShapePath
70
+ */
71
+ private _fillPicture;
35
72
  /**
36
73
  * Create a gradient based on the shape's fill configuration
37
74
  * @param canvasContext The canvas rendering context
@@ -65,9 +102,30 @@ export declare abstract class BaseShapeRenderModel {
65
102
  private _addGradientStops;
66
103
  private _getFillStyle;
67
104
  private _getStrokeStyle;
105
+ /**
106
+ * For modifier fill paths (darkenLess, darken, lighten, lightenLess),
107
+ * overlay a semi-transparent black or white fill on top of the current path
108
+ * to simulate the OOXML brightness adjustment.
109
+ *
110
+ * This matches what solid fill does via ColorUtil._adjust:
111
+ * darken → -30% brightness → overlay black at 30% opacity
112
+ * darkenLess → -12% → overlay black at 12% opacity
113
+ * lighten → +30% → overlay white at 30% opacity
114
+ * lightenLess → +12% → overlay white at 12% opacity
115
+ */
116
+ private _applyFillModifierOverlay;
68
117
  private _renderTextBox;
69
118
  private _renderCxnPoints;
70
119
  private _getValueFromGdRecord;
120
+ /**
121
+ * Walk a single path's commands, scaling coordinates and accumulating
122
+ * into the provided bounding-box tracker.
123
+ */
124
+ private _accumulatePathBounds;
125
+ /**
126
+ * Apply coordinate scaling to resolved path points in-place.
127
+ */
128
+ private _scalePathPoints;
71
129
  /**
72
130
  * Check if the adjust handle at the given index has an inverse relationship.
73
131
  * Uses cache to avoid recalculating.
@@ -0,0 +1,79 @@
1
+ import { ShapeSketchTypeEnum } from '../shape-enum';
2
+ /**
3
+ * Resolved (numeric) path command after gd evaluation and scaling.
4
+ * Used by SketchStrokeRenderer to draw sketch-style strokes.
5
+ */
6
+ export type IResolvedPathCommand = {
7
+ cmd: 'M';
8
+ x: number;
9
+ y: number;
10
+ } | {
11
+ cmd: 'L';
12
+ x: number;
13
+ y: number;
14
+ } | {
15
+ cmd: 'C';
16
+ cp1x: number;
17
+ cp1y: number;
18
+ cp2x: number;
19
+ cp2y: number;
20
+ x: number;
21
+ y: number;
22
+ } | {
23
+ cmd: 'Q';
24
+ cpx: number;
25
+ cpy: number;
26
+ x: number;
27
+ y: number;
28
+ } | {
29
+ cmd: 'A';
30
+ centerX: number;
31
+ centerY: number;
32
+ wR: number;
33
+ hR: number;
34
+ startAngle: number;
35
+ endAngle: number;
36
+ anticlockwise: boolean;
37
+ } | {
38
+ cmd: 'z';
39
+ };
40
+ /**
41
+ * Renders shape stroke with a hand-drawn / sketch visual effect.
42
+ *
43
+ * All sketch-related rendering logic lives here. The caller is responsible
44
+ * for setting strokeStyle, lineWidth, lineDash, lineJoin, lineCap on the
45
+ * canvas context *before* calling render().
46
+ */
47
+ export declare class SketchStrokeRenderer {
48
+ /**
49
+ * Build and stroke a sketch-style path on `ctx`.
50
+ *
51
+ * @param ctx Canvas rendering context (strokeStyle etc. should already be configured)
52
+ * @param commands The resolved (numeric) path commands that describe the original shape outline
53
+ * @param sketchType Which sketch mode to apply
54
+ * @param seed Integer seed for the seeded RNG – same seed produces identical output
55
+ */
56
+ static render(ctx: CanvasRenderingContext2D, commands: IResolvedPathCommand[], sketchType: ShapeSketchTypeEnum, seed: number): void;
57
+ private static _renderPass;
58
+ /**
59
+ * Draw a sketchy straight line from (x0,y0) to (x1,y1).
60
+ *
61
+ * The line is split into sub-segments. Each interior split point is
62
+ * displaced perpendicularly by a seeded-random amount. The resulting
63
+ * noisy chain is smoothed with a chain of quadratic bezier curves so the
64
+ * output looks like a natural hand-drawn stroke rather than a polygon.
65
+ */
66
+ private static _sketchLine;
67
+ /**
68
+ * Draw a sketchy cubic bezier by perturbing the control points.
69
+ */
70
+ private static _sketchCubic;
71
+ /**
72
+ * Draw a sketchy quadratic bezier by perturbing the control point.
73
+ */
74
+ private static _sketchQuadratic;
75
+ /**
76
+ * Draw a sketchy ellipse arc by applying slight noise to the center and radii.
77
+ */
78
+ private static _sketchArc;
79
+ }
@@ -319,3 +319,45 @@ export declare enum ShapeArrowSizeEnum {
319
319
  Medium = 2,
320
320
  Large = 3
321
321
  }
322
+ /**
323
+ * Shape sketch (hand-drawn) style enum.
324
+ * Controls how strongly the stroke is perturbed to look like a hand-drawn line.
325
+ *
326
+ * - None – regular vector stroke, no perturbation
327
+ * - Curved – very slight smooth waviness
328
+ * - Freehand – moderate irregular deformation
329
+ * - HandDrawn – heavy rough deformation rendered in two overlapping passes
330
+ */
331
+ export declare enum ShapeSketchTypeEnum {
332
+ None = 1,
333
+ Curved = 2,
334
+ Freehand = 3,
335
+ HandDrawn = 4
336
+ }
337
+ /**
338
+ * The type of image data source
339
+ */
340
+ export declare enum ImageSourceTypeEnum {
341
+ /**
342
+ * The image source is a URL, for example: https://avatars.githubusercontent.com/u/61444807?s=48&v=4
343
+ */
344
+ URL = "URL",
345
+ /**
346
+ * 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.
347
+ */
348
+ UUID = "UUID",
349
+ /**
350
+ * The image source is BASE64, for example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAALCAYAAAB7ZJ...
351
+ */
352
+ BASE64 = "BASE64"
353
+ }
354
+ /**
355
+ * The image fill mode when ShapeFillEnum is PictureFill
356
+ */
357
+ export declare enum ImageFillModeEnum {
358
+ Stretch = 1,
359
+ /**
360
+ * Tile: The image is repeated (tiled) to fill the shape's area.
361
+ */
362
+ Tile = 2
363
+ }
@@ -1,4 +1,4 @@
1
- import type { BasicShapeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeTypeEnum } from './shape-enum';
1
+ import type { BasicShapeEnum, ImageFillModeEnum, ImageSourceTypeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeSketchTypeEnum, ShapeTypeEnum } from './shape-enum';
2
2
  /**
3
3
  * GdContext 用来计算 OOXML Shape 的 Geometry Definitions (gd)
4
4
  * 包含:
@@ -581,6 +581,52 @@ export interface IBasicShapeData {
581
581
  position: number;
582
582
  color: string;
583
583
  }>;
584
+ /**
585
+ * 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.
586
+ */
587
+ fillImageSource?: string;
588
+ /**
589
+ * Image source type for fillImageSource
590
+ */
591
+ fillImageSourceType?: ImageSourceTypeEnum;
592
+ /**
593
+ * Image fill mode, defines how the image is applied to the shape. The options include:Stretch & Tile.
594
+ * Defaults to Stretch when not specified.
595
+ */
596
+ imageFillMode?: ImageFillModeEnum;
597
+ /**
598
+ * 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.
599
+ */
600
+ stretchFillRect?: {
601
+ left: number;
602
+ top: number;
603
+ bottom: number;
604
+ right: number;
605
+ };
606
+ /**
607
+ * The crop rect of image, the unit of value is percentage.
608
+ */
609
+ srcRect?: {
610
+ left: number;
611
+ top: number;
612
+ bottom: number;
613
+ right: number;
614
+ };
615
+ imageTile?: {
616
+ scaleX?: number;
617
+ scaleY?: number;
618
+ offsetX?: number;
619
+ offsetY?: number;
620
+ alignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br';
621
+ };
622
+ /**
623
+ * The opacity of the fill image, ranging from 0 (completely transparent) to 1 (completely opaque).
624
+ */
625
+ imageOpacity?: number;
626
+ /**
627
+ * 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.
628
+ */
629
+ imageRotateWithShape?: boolean;
584
630
  };
585
631
  stroke?: IShapeLineStyle;
586
632
  adjustValues?: Record<string, number>;
@@ -746,6 +792,8 @@ export interface IShapeRenderParameters {
746
792
  flipH?: boolean;
747
793
  flipV?: boolean;
748
794
  angle?: number;
795
+ oKey: string;
796
+ image?: HTMLImageElement;
749
797
  }
750
798
  export interface IShapeRelationItem {
751
799
  shapeId: string;
@@ -768,6 +816,10 @@ export interface IShapeLineStyle {
768
816
  capType?: ShapeLineCapEnum;
769
817
  lineJoinType?: ShapeLineJoinEnum;
770
818
  lineStrokeType?: ShapeLineTypeEnum;
819
+ /**
820
+ * Hand-drawn / sketch style. Defaults to `ShapeSketchTypeEnum.None`.
821
+ */
822
+ sketchType?: ShapeSketchTypeEnum;
771
823
  }
772
824
  export interface IShapeModel {
773
825
  getBasicShapeType(): BasicShapeEnum;
@@ -6,3 +6,4 @@ import { ShapeTypeEnum } from '../shape-enum';
6
6
  */
7
7
  export declare function isConnectorShape(shapeType: ShapeTypeEnum): boolean;
8
8
  export declare function isCurvedConnectorShape(shapeType: ShapeTypeEnum): boolean;
9
+ export declare function getSketchSeed(shapeId: string): number;