@univerjs-pro/engine-shape 0.20.0 → 0.20.1

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

@@ -25,13 +25,13 @@ export declare abstract class BaseShapeRenderModel {
      */
     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.
+     * 计算所有可填充路径（fill !== 'none'）的实际包围盒。
      *
-     * Coordinate system: same as render() after translate(-width/2, -height/2),
-     * i.e. (0,0) is at the top-left of the drawing rect.
+     * 对于多路径形状（如 cloudCallout 云朵标注），子路径可能超出 drawing rect，
+     * 因此需要返回真实的包围盒，使图片/渐变填充能覆盖完整的形状区域。
+     *
+     * 坐标系：与 render() 中 translate(-width/2, -height/2) 之后的坐标系一致，
+     * 即 (0,0) 为 drawing rect 的左上角。
      */
     computeFillableBounds(rect: IShapeRect, shapeContext: BaseShapeContext): IShapeRect;
     /**
@@ -39,16 +39,15 @@ export declare abstract class BaseShapeRenderModel {
      */
     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.
+     * 在 canvas 上构建形状轮廓路径并执行裁剪（clip）。
+     * 与 render() 不同，本方法**不做填充和描边**——仅构建路径并调用 clip()。
+     * 坐标系：(0,0) 为左上角，(width, height) 为右下角。
      *
-     * 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.
+     * 仅可填充路径（fill !== 'none'）参与裁剪区域。
+     * 对于多路径形状（如 cloudCallout），部分子路径可能超出 drawing rect，
+     * 返回的 IShapeRect 报告裁剪区域的实际包围盒，供调用方据此确定图片填充尺寸。
      *
-     * @returns The actual bounding rect of the clip region, or false if no clip was built
+     * @returns 裁剪区域的实际包围矩形，若无法构建裁剪路径则返回 false
      */
     buildClipPath(canvasContext: CanvasRenderingContext2D, rect: IShapeRect, shapeContext: BaseShapeContext): IShapeRect | false;
     private _getDashType;
@@ -56,19 +55,35 @@ export declare abstract class BaseShapeRenderModel {
     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
+     * 用图片填充当前路径，复现 Excel 的图片填充管线：
+     *   image → srcRect（裁剪源图区域）→ 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.
+     * 坐标系：已在 `save/translate(-w/2, -h/2)` 块内，(0,0) 为形状包围盒左上角。
      *
-     * @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
+     * @param canvasContext  当前 2D 画布上下文
+     * @param rect           形状包围矩形（display pixels 单位的宽高）
+     * @param shapeData      携带填充配置的 IBasicShapeData
+     * @param image          已加载的 HTMLImageElement
+     * @param fillRule       当前 path 的填充规则标志（来自 IShapePath.fill）
+     * @param angle          形状旋转角度（度），用于处理 imageRotateWithShape
+     * @param fillBounds     多路径形状的实际可填充包围盒，超出 drawing rect 的部分也需覆盖
      */
     private _fillPicture;
+    /**
+     * 将 OOXML 的"视觉角度"转换为 Canvas 椭圆的参数角度。
+     *
+     * OOXML 角度表示从中心到椭圆上某点的几何角度（即人眼看到的角度），
+     * 而 Canvas ellipse() 使用参数角度：point = (rx·cos(t), ry·sin(t))。
+     * 对于非正圆的椭圆，两者不同。OOXML 中 cat2/sat2 公式正是执行此转换来定位
+     * moveTo 点和调节手柄，因此传给 Canvas 时必须做同样的转换。
+     */
+    private _ooxmlAngleToParametric;
+    /**
+     * 将椭圆弧的基本方向极值点纳入包围盒追踪。
+     * 仅包含落在弧段扫过范围内的极值（0°、90°、180°、270° 方向）。
+     * 所有角度均为参数角度（Canvas 角度），而非 OOXML 视觉角度。
+     */
+    private _updateArcCardinalBounds;
     /**
      * Create a gradient based on the shape's fill configuration
      * @param canvasContext The canvas rendering context
@@ -92,10 +107,19 @@ export declare abstract class BaseShapeRenderModel {
      */
     private _createAngularGradient;
     /**
-     * Create a diamond gradient
-     * This is approximated using a radial gradient with adjusted parameters
+     * Fill the current shape path with a diamond gradient using 4 triangular linear gradients.
+     *
+     * The rectangle is divided into 4 triangles by its diagonals (top, right, bottom, left).
+     * Each triangle is filled with a linear gradient from the center to the corresponding
+     * edge midpoint, approximating the Manhattan-distance diamond pattern without any
+     * offscreen canvas or per-pixel manipulation.
+     *
+     * Uses Path2D for triangle clips to avoid destroying the main canvas path
+     * (Canvas save/restore does NOT preserve the current path).
+     * Triangles are extended by 1px at diagonal edges so they overlap slightly,
+     * hiding anti-aliasing seams at the boundaries.
      */
-    private _createDiamondGradient;
+    private _fillDiamondGradient;
     /**
      * Add color stops to a gradient
      */
@@ -103,23 +127,22 @@ export declare abstract class BaseShapeRenderModel {
     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.
+     * 对修饰符填充路径（darkenLess, darken, lighten, lightenLess），
+     * 在当前路径上方叠加一层半透明的黑色或白色填充，模拟 OOXML 的明暗调整效果。
      *
-     * 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
+     * 对齐纯色填充时 ColorUtil._adjust 的处理逻辑：
+     *   darken     → 亮度 -30%  → 叠加 30% 不透明度的黑色
+     *   darkenLess → 亮度 -12%  → 叠加 12% 不透明度的黑色
+     *   lighten    → 亮度 +30%  → 叠加 30% 不透明度的白色
+     *   lightenLess→ 亮度 +12%  → 叠加 12% 不透明度的白色
      */
     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;
     /**

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

@@ -121,8 +121,6 @@ export declare enum ShapeTypeEnum {
     LeftRightCircularArrow = "leftRightCircularArrow",
     SwooshArrow = "swooshArrow",
     LeftRightRibbon = "leftRightRibbon",
-    TextBox = "textBox",
-    Circle = "circle",// 特例 圆形其实是椭圆的一种，只不过限定了长宽相等 excel没有circle这个形状，只有ellipse
     Heptagon = "heptagon",
     HomePlate = "homePlate",
     RightArrow = "rightArrow",
@@ -219,7 +217,7 @@ export declare enum ShapeTypeEnum {
     SmileyFace = "smileyFace",
     IrregularSeal1 = "irregularSeal1",
     IrregularSeal2 = "irregularSeal2",
-    FoldedCorner = "folderCorner",
+    FoldedCorner = "foldedCorner",
     Bevel = "bevel",
     Donut = "donut",
     NoSmoking = "noSmoking",