@univerjs-pro/engine-shape 0.15.3-insiders.20260131-cbd5fac

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

@@ -0,0 +1,836 @@
+import { BasicShapeEnum, ShapeArrowSizeEnum, ShapeArrowTypeEnum, ShapeFillEnum, ShapeGradientTypeEnum, ShapeLineCapEnum, ShapeLineDashEnum, ShapeLineJoinEnum, ShapeLineTypeEnum, ShapeOperatorEnum, ShapeRenderModeEnum, ShapeTypeEnum } from './shape-enum';
+/**
+ * GdContext 用来计算 OOXML Shape 的 Geometry Definitions (gd)
+ * 包含：
+ *  - 基本绘制尺寸（宽 w、高 h）
+ *  - 固定点位（左 l、右 r、顶 t、底 b、中心等）
+ *  - 调整值（adjust values）
+ *  - 临时计算缓存
+ *  - gd 公式系统需要的数学方法
+ *
+ * 所有值都按 Office 的规则：1000 = 1px 的 EMU 转换前坐标系。
+ * 公式计算遵循 OOXML 的 ST_AdjCoordinate 体系。
+ */
+export interface IGdContextBase {
+    /**
+     * shape 的最终显示宽度（OOXML 使用的坐标值，非 CSS 像素）
+     * 例如：Excel 中 w = 100000 表示宽度 100%。
+     */
+    w: number;
+    /**
+     * shape 的最终显示高度
+     */
+    h: number;
+    /**
+     * w / 2，OOXML 常用
+     */
+    wd2: number;
+    /**
+     * h / 2，常用
+     */
+    hd2: number;
+    /**
+     * 左侧（一般为 0）
+     */
+    l: number;
+    /**
+     * 顶部（一般为 0）
+     */
+    t: number;
+    /**
+     * 右侧 = w
+     */
+    r: number;
+    /**
+     * 底部 = h
+     */
+    b: number;
+    /**
+     * 垂直中心 = h / 2
+     */
+    vc: number;
+    /**
+     * 水平中心 = w / 2
+     */
+    hc: number;
+    wd3: number;
+    wd4: number;
+    wd5: number;
+    wd6: number;
+    wd8: number;
+    wd10: number;
+    hd3: number;
+    hd4: number;
+    hd5: number;
+    hd6: number;
+    hd8: number;
+    hd10: number;
+    wd32: number;
+    hd32: number;
+    /**
+     * circle division by 2 (180° in DrawingML angle unit)
+     */
+    cd2: number;
+    /**
+     * circle division by 4 (90° in DrawingML angle unit)
+     */
+    cd4: number;
+    /**
+     * circle division by 8 (45° in DrawingML angle unit)
+     */
+    cd8: number;
+    /**
+     * circle division by 16 (22.5° in DrawingML angle unit)
+     */
+    cd16: number;
+    /**
+     * shortest side of the shape (w and h)
+     */
+    ss: number;
+    /**
+     * longest side of the shape (w and h)
+     */
+    ls: number;
+    ssd2: number;
+    ssd4: number;
+    ssd6: number;
+    ssd8: number;
+    ssd16: number;
+    ssd32: number;
+    lsd2: number;
+    lsd4: number;
+    lsd8: number;
+    lsd16: number;
+    lsd32: number;
+}
+export interface IGdContext extends IGdContextBase {
+    x0?: number;
+    x1?: number;
+    x2?: number;
+    x3?: number;
+    x4?: number;
+    x5?: number;
+    x6?: number;
+    x7?: number;
+    x8?: number;
+    x9?: number;
+    x10?: number;
+    x11?: number;
+    x12?: number;
+    x13?: number;
+    x14?: number;
+    x15?: number;
+    x16?: number;
+    x17?: number;
+    x18?: number;
+    x23?: number;
+    x24?: number;
+    x25?: number;
+    y1?: number;
+    y2?: number;
+    y3?: number;
+    y4?: number;
+    y5?: number;
+    y6?: number;
+    y7?: number;
+    y8?: number;
+    y9?: number;
+    y10?: number;
+    y11?: number;
+    y12?: number;
+    y13?: number;
+    y14?: number;
+    y15?: number;
+    y16?: number;
+    y17?: number;
+    y18?: number;
+    y24?: number;
+    sx1?: number;
+    sx2?: number;
+    sx3?: number;
+    sx4?: number;
+    sx5?: number;
+    sx6?: number;
+    sx7?: number;
+    sx8?: number;
+    sx9?: number;
+    sx10?: number;
+    sx11?: number;
+    sx12?: number;
+    sx13?: number;
+    sx14?: number;
+    sx15?: number;
+    sx16?: number;
+    /**
+     * g5–g8 are vertically symmetric guideline values used in many preset shapes.
+     * They represent positions above/below the vertical center (vc) using offsets.
+     *
+     * g5：vc 上方 g3 距离
+     * g6：vc 下方 g3 距离
+     * g7：vc 上方 g4 距离
+     * g8：vc 下方 g4 距离
+     *
+     * These are commonly used to build arcs, eyes, mouth curves, or rounded corners
+     * in shapes such as smileyFace, cloud, heart, blockArrows.
+     *
+     * g5–g8用于构造图形的上下对称控制点，例如笑脸的眼睛位置、嘴巴曲线、
+     * 或者箭头、云朵等的圆角结构。
+     */
+    g2?: number;
+    g3?: number;
+    g4?: number;
+    g5?: number;
+    g6?: number;
+    g7?: number;
+    g8?: number;
+    g9?: number;
+    g10?: number;
+    g11?: number;
+    g12?: number;
+    g13?: number;
+    g14?: number;
+    g15?: number;
+    g16?: number;
+    g17?: number;
+    g18?: number;
+    g19?: number;
+    g20?: number;
+    g21?: number;
+    g22?: number;
+    g23?: number;
+    g24?: number;
+    g25?: number;
+    g26?: number;
+    sy1?: number;
+    sy2?: number;
+    sy3?: number;
+    sy4?: number;
+    sy5?: number;
+    sy6?: number;
+    sy7?: number;
+    sy8?: number;
+    sy9?: number;
+    sy10?: number;
+    sy11?: number;
+    sy12?: number;
+    sy13?: number;
+    sy14?: number;
+    sy15?: number;
+    sy16?: number;
+    dx?: number;
+    dx1?: number;
+    dx2?: number;
+    dx3?: number;
+    dx4?: number;
+    dx5?: number;
+    dx6?: number;
+    dy?: number;
+    dy1?: number;
+    dy2?: number;
+    dy3?: number;
+    idx?: number;
+    il?: number;
+    ir?: number;
+    idy?: number;
+    it?: number;
+    ib?: number;
+    wR?: number;
+    hR?: number;
+    tx1?: number;
+    tx2?: number;
+    bx1?: number;
+    bx2?: number;
+    by1?: number;
+    d?: number;
+    tdx?: number;
+    bdx?: number;
+    ilx?: number;
+    irx?: number;
+    lx?: number;
+    lx1: number;
+    ly1: number;
+    lx2: number;
+    ly2: number;
+    rx?: number;
+    rx1: number;
+    rx2: number;
+    rx3: number;
+    rx4: number;
+    rx5: number;
+    rx6: number;
+    ry: number;
+    ry1: number;
+    ry2: number;
+    ly?: number;
+    ly3?: number;
+    ly4?: number;
+    ry3?: number;
+    ry4?: number;
+    a: number;
+    a1: number;
+    a2: number;
+    a3?: number;
+    ang1?: number;
+    maxAdj1?: number;
+    maxAdj2?: number;
+    maxAdj3?: number;
+    q1?: number;
+    stAng: number;
+    swAng: number;
+    dxI: number;
+    dyI: number;
+    xE: number;
+    yE: number;
+    xD: number;
+    yD: number;
+    rw2: number;
+    rh2: number;
+    istAng: number;
+    iswAng: number;
+    xBp: number;
+    yBp: number;
+    xA: number;
+    yA: number;
+    xGp: number;
+    yGp: number;
+    xF: number;
+    yF: number;
+    rw1: number;
+    rh1: number;
+    stAng0: number;
+    swAng0: number;
+    xL: number;
+    yL: number;
+    xKp: number;
+    yKp: number;
+    st2: number;
+    xC: number;
+    yC: number;
+    xJp: number;
+    yJp: number;
+    aI?: number;
+    _dxI?: number;
+    _dyI?: number;
+    th?: number;
+    aw2?: number;
+    th2?: number;
+    dh2?: number;
+    ah?: number;
+    bw?: number;
+    bh?: number;
+    bs?: number;
+    maxAdj4?: number;
+    a4?: number;
+    bd?: number;
+    bd3?: number;
+    bd2?: number;
+    q2?: number;
+    q3?: number;
+    minAdj5?: number;
+    a5?: number;
+    cx?: number;
+    cx1?: number;
+    cy1?: number;
+    aw?: number;
+    dh?: number;
+    mswAng?: number;
+    ix?: number;
+    iy?: number;
+    dang2?: number;
+    swAng2?: number;
+    swAng3?: number;
+    stAng3?: number;
+    q4?: number;
+    q5?: number;
+    q6?: number;
+    q7?: number;
+    q8?: number;
+    q9?: number;
+    q10?: number;
+    q11?: number;
+    q12?: number;
+    q13?: number;
+    q14?: number;
+    mswAng2?: number;
+    stAng2?: number;
+    hf?: number;
+    vf?: number;
+    swd2?: number;
+    shd2?: number;
+    svc?: number;
+    xB?: number;
+    yB?: number;
+    yG?: number;
+    yI?: number;
+    yH?: number;
+    rad?: number;
+    drx?: number;
+    dry?: number;
+    dlx?: number;
+    dly?: number;
+    yWave1?: number;
+    yWave2?: number;
+    yWave3?: number;
+    yWave4?: number;
+    yWave5?: number;
+    yWave6?: number;
+    xWave1?: number;
+    xWave2?: number;
+    xOff1?: number;
+    xOff2?: number;
+    xOff3?: number;
+    yOff1?: number;
+    xt?: number;
+    yt?: number;
+    xr?: number;
+    yr?: number;
+    xb?: number;
+    yb?: number;
+    xl?: number;
+    yl?: number;
+    u1?: number;
+    u2?: number;
+    v2?: number;
+    xPos?: number;
+    yPos?: number;
+    stAng1?: number;
+    cy3?: number;
+    cx2?: number;
+    rh?: number;
+    cx5?: number;
+    cy4?: number;
+    cy6?: number;
+    cx4?: number;
+    cy7?: number;
+    ch?: number;
+    ch2?: number;
+    ch4?: number;
+    ox1?: number;
+    oy1?: number;
+    ox2?: number;
+    oy2?: number;
+    x19?: number;
+    g18w?: number;
+    swAng1?: number;
+    swAng4?: number;
+    swAng5?: number;
+    iwd2?: number;
+    ihd2?: number;
+    dr?: number;
+    g27?: number;
+    g28?: number;
+    g29?: number;
+    g30?: number;
+    g31?: number;
+    g32?: number;
+    g33?: number;
+    g34?: number;
+    g35?: number;
+    g36?: number;
+    g37?: number;
+    g38?: number;
+    g39?: number;
+    g40?: number;
+    g41?: number;
+    g42?: number;
+    g43?: number;
+    g44?: number;
+    g45?: number;
+    g46?: number;
+    g47?: number;
+    g48?: number;
+    rh3?: number;
+    rw3?: number;
+    da?: number;
+    rw?: number;
+    xA1?: number;
+    yA1?: number;
+    xB1?: number;
+    yB1?: number;
+    xC1?: number;
+    yC1?: number;
+    xD1?: number;
+    yD1?: number;
+    bD1?: number;
+    yD2?: number;
+    bD2?: number;
+    yB3?: number;
+    xA6?: number;
+    yD3?: number;
+    bD3?: number;
+    xB4?: number;
+    yC2?: number;
+    xC4?: number;
+    yB2?: number;
+    xD4?: number;
+    yA2?: number;
+    bD4?: number;
+    xB5?: number;
+    xC5?: number;
+    xD5?: number;
+    bD5?: number;
+    xE6?: number;
+    xF6?: number;
+    yC6?: number;
+    xD6?: number;
+    yD6?: number;
+    bD6?: number;
+    xB2?: number;
+    xC2?: number;
+    xD2?: number;
+    xB3?: number;
+    xC3?: number;
+    xD3?: number;
+    yB4?: number;
+    yC4?: number;
+    yD4?: number;
+    yA4?: number;
+    xB6?: number;
+    yC3?: number;
+    xC6?: number;
+    yA3?: number;
+    xB7?: number;
+    xC7?: number;
+    xD7?: number;
+    bD7?: number;
+    xB8?: number;
+    xC8?: number;
+    xD8?: number;
+    bD8?: number;
+    xE9?: number;
+    yC9?: number;
+    xF9?: number;
+    xD9?: number;
+    yD9?: number;
+    bD9?: number;
+    xP1?: number;
+    yP1?: number;
+    xP2?: number;
+    yP2?: number;
+    g0w?: number;
+    _cd4?: number;
+    _cd2?: number;
+}
+export type IGdContextKey = keyof IGdContext;
+export type ShapeOperatorValue = [ShapeOperatorEnum, ...Array<string | number>];
+type PathCommandType = 'M' | 'L' | 'C' | 'Q' | 'A' | 'z';
+/** Individual path command with its parameters */
+export interface IPathCommand {
+    /** Command type */
+    command: PathCommandType;
+    /** Command points/parameters */
+    points: Array<IGdContextKey | number>;
+    center?: [IGdContextKey | number, IGdContextKey | number, boolean];
+    /** Start position of this command segment */
+    start?: {
+        x: number;
+        y: number;
+    };
+    /** Calculated length of this path segment */
+    pathLength?: number;
+}
+/** Single path definition for shape rendering */
+export interface IShapePath {
+    /** Virtual canvas width (default: shape width) - used for coordinate system scaling */
+    w?: number;
+    /** Virtual canvas height (default: shape height) - used for coordinate system scaling */
+    h?: number;
+    /** Fill mode */
+    fill?: 'none' | 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess' | 'evenodd';
+    /** Stroke mode */
+    stroke?: boolean;
+    /** Whether extrusion is allowed (3D) */
+    extrusionOk?: boolean;
+    /**
+     * Path data - can be either:
+     * 1. SVG path string (e.g., "M 0 0 L 100 100")
+     * 2. Parsed data array for direct rendering
+     */
+    data?: string;
+    /** Parsed path data array (alternative to data string) */
+    dataArray?: IPathCommand[];
+}
+export interface IShapeTextAlign {
+    isHorizontal: boolean;
+}
+export interface IShapeText extends IShapeTextAlign {
+    isRichText: false;
+    text?: string;
+    color?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+}
+export interface ICustomShapeTextData extends IShapeTextAlign {
+    dataModel?: unknown;
+}
+/**
+ * This interface defines the shape data structure , and this part will save in json
+ */
+export interface IBasicShapeData {
+    shapeType?: ShapeTypeEnum;
+    fill?: {
+        color?: string;
+        fillType?: ShapeFillEnum;
+        opacity?: number;
+        gradientType?: ShapeGradientTypeEnum;
+        gradientAngle?: number;
+        gradientStops?: Array<{
+            position: number;
+            color: string;
+        }>;
+    };
+    stroke?: IShapeLineStyle;
+    adjustValues?: Record<string, number>;
+    shapeText?: IShapeText | ICustomShapeTextData;
+}
+export interface ICxnShapeData extends IBasicShapeData {
+    points?: Array<{
+        x: number;
+        y: number;
+    }>;
+    relation?: IShapeRelation;
+    ln?: IShapeLineStyle & {
+        startArrow?: {
+            type?: ShapeArrowTypeEnum;
+            size?: ShapeArrowSizeEnum;
+        };
+        endArrow?: {
+            type?: ShapeArrowTypeEnum;
+            size?: ShapeArrowSizeEnum;
+        };
+    };
+}
+export interface IGroupShapeData {
+    childShapeIds: string[];
+    shapeData?: Record<string, IShapeData>;
+}
+export type IShapeData = IBasicShapeData | ICxnShapeData;
+export interface IShapeJSONData {
+    id: string;
+    shapeData: IShapeData;
+    shapeType: ShapeTypeEnum;
+}
+export declare enum ShapeHitTestHitTypeEnum {
+    None = 0,
+    Body = 1,
+    ConnectionSite = 2,
+    AdjustHandle = 3,
+    TextBox = 4
+}
+export declare enum ShapeAdjustHandleTypeEnum {
+    AH_XY = 1,
+    AH_Polar = 2
+}
+export interface IShapeHitTestResult {
+    adjustHandleIndex?: number;
+    connectionSiteIndex?: number;
+    hitType: ShapeHitTestHitTypeEnum;
+}
+export interface IPresetShapeConfig {
+    /** Adjustment values for shape parameters, each value typically ranges from 0 to 100000 */
+    adjustValues?: Record<string, ShapeOperatorValue>;
+    /** Guide definitions - formulas for calculating shape geometry */
+    gd?: Record<string, ShapeOperatorValue>;
+    gdKeyList?: string[];
+    /** Adjustment handles - defines how users can modify the shape */
+    ahLst?: Array<IShapeAdjustItem>;
+    /** Connection sites for connecting lines to the shape */
+    cxnLst?: Array<{
+        /** Angle in degrees (cd4 = 90°, cd2 = 180°, 3cd4 = 270°) */
+        ang: string | number;
+        /** X coordinate */
+        x?: string | number;
+        /** Y coordinate */
+        y?: string | number;
+    }>;
+    /** Text rectangle definition */
+    rect?: {
+        /** Left position */
+        l: string | number;
+        /** Top position */
+        t: string | number;
+        /** Right position */
+        r: string | number;
+        /** Bottom position */
+        b: string | number;
+    };
+    /**
+     * Path list - can have multiple paths for complex shapes
+     * For example: one for fill, one for stroke, one for shadow
+     */
+    pathLst?: IShapePath[];
+}
+export type IPresetShapeConfigMap = Record<string, IPresetShapeConfig>;
+export interface IShapeContextOptions {
+    width: number;
+    height: number;
+    adjustValues?: Record<string, number>;
+    presetShapeConfig?: IPresetShapeConfig;
+}
+export interface IShapeRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface IShapePoint {
+    x: number;
+    y: number;
+}
+export interface IShapeGdContextKeyPoint {
+    x: IGdContextKey | number;
+    y: IGdContextKey | number;
+}
+export interface IShapePointWithAdjName extends IShapePoint {
+    adjName: string;
+}
+export interface IShapeAdjustItem {
+    /** Handle type: XY or polar */
+    type: 'ahXY' | 'ahPolar';
+    /** Guide reference for X or radius */
+    gdRefX?: string;
+    /** Guide reference for radius ， 控制半径*/
+    gdRefR?: string;
+    /** Min/Max values for X or radius */
+    minX?: string | number;
+    maxX?: string | number;
+    minR?: string | number;
+    maxR?: string | number;
+    /** Guide reference for Y or angle */
+    gdRefY?: string;
+    /** Guide reference for angle， 控制角度 */
+    gdRefAng?: string;
+    /** Min/Max values for Y or angle */
+    minY?: string | number;
+    maxY?: string | number;
+    minAng?: string | number;
+    maxAng?: string | number;
+    /** Position (for ahXY) or polar coordinates (for ahPolar) */
+    pos: {
+        x: string | number;
+        y: string | number;
+    };
+}
+export interface IShapeAdjustItemResolved extends IShapeAdjustItem {
+    resolvedMinX?: number;
+    resolvedMaxX?: number;
+    resolvedMinY?: number;
+    resolvedMaxY?: number;
+    resolvedMinR?: number;
+    resolvedMaxR?: number;
+    resolvedMinAng?: number;
+    resolvedMaxAng?: number;
+    resolvedPos?: {
+        x: number;
+        y: number;
+    };
+    /** Center point for polar coordinates (hc, vc) */
+    resolvedCenter?: {
+        x: number;
+        y: number;
+    };
+    /** Current value of the adj parameter being controlled */
+    currentAdjValue?: number;
+    /**
+     * Indicates inverse relationship between adj value and position.
+     * Calculated at runtime by analyzing gd formulas.
+     * When true, increasing adj value will decrease the position value.
+     */
+    inverse?: boolean;
+}
+export interface IShapeRenderParameters {
+    renderMode?: ShapeRenderModeEnum;
+    flipH?: boolean;
+    flipV?: boolean;
+    angle?: number;
+}
+export interface IShapeRelationItem {
+    shapeId: string;
+    cxnIndex: number;
+}
+/**
+ * Shape relation interface for connecting shapes
+ * from: starting shape and connection point index
+ * to: ending shape and connection point index
+ */
+export interface IShapeRelation {
+    from?: IShapeRelationItem;
+    to?: IShapeRelationItem;
+}
+export interface IShapeLineStyle {
+    color?: string;
+    width?: number;
+    opacity?: number;
+    dashType?: ShapeLineDashEnum;
+    capType?: ShapeLineCapEnum;
+    lineJoinType?: ShapeLineJoinEnum;
+    lineStrokeType?: ShapeLineTypeEnum;
+}
+export interface IShapeModel {
+    getBasicShapeType(): BasicShapeEnum;
+    getId(): string;
+    dispose(): void;
+    getShapeData(): IShapeData;
+}
+export interface IBentConnectorRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface IBentConnectorResult {
+    points: IShapePoint[];
+    rect: IBentConnectorRect;
+    flipH: boolean;
+    flipV: boolean;
+}
+export interface IConnectPointInfo {
+    point: IShapePoint;
+    /**
+     * Angle in degrees, 0 is to the right, 90 is down, 180 is left, 270 is up
+     */
+    angle: number;
+    bounds: IShapeRect;
+}
+export interface IConnectorRouteLayoutResult {
+    /** Local points in normalized space (0,0 to width,height, no flip) */
+    localPoints: IShapePoint[];
+    /** World rect including position, size, and flip flags */
+    worldRect: IDrawingRect;
+    adjustValues: Record<string, number>;
+    lineType: ILineType;
+    /**
+     * Rotation angle in degrees (0, 90, 180, 270).
+     * Used when the connector is rotated to account for flip + rotation scenarios.
+     * For example, when width > height becomes height > width after flip.
+     */
+    rotation: number;
+}
+/**
+ * Represents the drawing rect in world coordinates.
+ */
+export interface IDrawingRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    angle?: number;
+}
+/**
+ * Result from computing a new connector line layout.
+ * Contains both the normalized local points and the world rect.
+ */
+export interface IConnectorLayoutResult {
+    /** Local points in normalized space (0,0 to width,height, no flip) */
+    localPoints: IShapePoint[];
+    /** World rect including position, size, and flip flags */
+    worldRect: IDrawingRect;
+    worldPoints: IShapePoint[];
+}
+export type ILineType = ShapeTypeEnum.Line | ShapeTypeEnum.StraightConnector1 | ShapeTypeEnum.BentConnector2 | ShapeTypeEnum.BentConnector3 | ShapeTypeEnum.BentConnector4 | ShapeTypeEnum.BentConnector5 | ShapeTypeEnum.CurvedConnector2 | ShapeTypeEnum.CurvedConnector3 | ShapeTypeEnum.CurvedConnector4 | ShapeTypeEnum.CurvedConnector5;
+export {};