diff --git a/packages/vrender-components/src/axis/type.ts b/packages/vrender-components/src/axis/type.ts index 52b816f19..c61919450 100644 --- a/packages/vrender-components/src/axis/type.ts +++ b/packages/vrender-components/src/axis/type.ts @@ -448,7 +448,13 @@ export interface AxisLabelOverlap { overflowLimitLength?: | number | { + /** + * 左侧扩充空间的大小 + */ left?: number; + /** + * 右侧扩充空间的大小 + */ right?: number; // top?: number; // bottom?: number; diff --git a/packages/vrender-components/src/core/type.ts b/packages/vrender-components/src/core/type.ts index d6cc9a13a..7f1c3a1bc 100644 --- a/packages/vrender-components/src/core/type.ts +++ b/packages/vrender-components/src/core/type.ts @@ -52,9 +52,21 @@ export type Padding = | number | number[] | { + /** + * 上边距 + */ top?: number; + /** + * 下边距 + */ bottom?: number; + /** + * 左边距 + */ left?: number; + /** + * 右边距 + */ right?: number; }; @@ -65,7 +77,13 @@ type CommonTextContent = { | number | number[] | { + /** + * 指定文本节点类型为'text' + */ type?: 'text'; + /** + * 设置文本的内容 + */ text: string | string[] | number | number[]; }; }; diff --git a/packages/vrender-components/src/label/type.ts b/packages/vrender-components/src/label/type.ts index 3c30021ff..fcef620ce 100644 --- a/packages/vrender-components/src/label/type.ts +++ b/packages/vrender-components/src/label/type.ts @@ -162,7 +162,16 @@ export interface OverlapAttrs { /** * 防重叠的区域大小 */ - size?: { width: number; height: number }; + size?: { + /** + * 防重叠区域的宽度 + */ + width: number; + /** + * 防重叠区域的高度 + */ + height: number; + }; /** * 发生重叠后，是否隐藏标签 @@ -274,6 +283,9 @@ export interface SmartInvertAttrs { } export type ShiftYStrategy = { + /** + * 将防重叠策略设置为 'shiftY' + */ type: 'shiftY'; /** * 布局迭代次数 @@ -294,10 +306,13 @@ export type ShiftYStrategy = { export type PositionStrategy = { /** - * 可选位置策略。 + * 将防重叠的策略设置为'position'，即可选位置策略。 * 若默认位置没有足够的空间放置标签，则考虑 position 内的备选位置。 */ type: 'position'; + /** + * 所有的备选位置 + */ position?: Functional; /** * 当 position 内的备选位置依然无法放下标签时，标签是否放回原位。 @@ -310,10 +325,13 @@ export type PositionStrategy = { export type BoundStrategy = { /** - * 标签配置在图形内部时使用。 + * 将防重叠策略设置为'bound'，当标签配置在图形内部时使用。 * 当图形大小不足以放下标签，则考虑 position 内的备选位置。 */ type: 'bound'; + /** + * 所有的备选位置 + */ position?: Functional; /** * 当 position 内的备选位置依然无法放下标签时，标签是否放回原位。 @@ -326,7 +344,7 @@ export type BoundStrategy = { export type MoveYStrategy = { /** - * 可选位置策略。 + * 将防重叠策略设置为'moveY' * 若默认位置没有足够的空间放置标签，则根据 offset 在Y方向上寻找位置。 */ type: 'moveY'; @@ -338,7 +356,7 @@ export type MoveYStrategy = { export type MoveXStrategy = { /** - * 可选位置策略。 + * 将防重叠策略设置为'moveX' * 若默认位置没有足够的空间放置标签，则根据 offset 在X方向上寻找位置。 */ type: 'moveX'; @@ -555,26 +573,65 @@ export interface DataLabelAttrs extends IGroupGraphicAttribute { export type Functional = T | ((data: any) => T); +/** + * 标签的离场动画配置 + */ export interface ILabelExitAnimation { + /** + * 动画执行的时长 + */ duration?: number; + /** + * 动画延迟的时长 + */ delay?: number; + /** + * 动画的缓动函数 + */ easing?: EasingType; } +/** + * 标签的入场动画配置 + */ export interface ILabelEnterAnimation extends ILabelExitAnimation { + /** + * 标签动画的模式，支持三种类型 + * - same-time：标签出现动画和关联图形的动画同时进行 + * - after：当关联动图的出场动画结束后，执行标签的出场动画 + * - after-all：当所有关联图元的出场动画结束后，执行标签的出场动画 + */ mode?: 'same-time' | 'after' | 'after-all'; } +/** + * 标签的更新动画配置 + */ export interface ILabelUpdateAnimation extends ILabelExitAnimation { - /** 是否开启 increaseCount 动画 + /** + * 是否开启 increaseCount 动画 * @default true */ increaseEffect?: boolean; } +/** + * 标签更新的时候，动画的通道配置 + */ export interface ILabelUpdateChannelAnimation extends ILabelUpdateAnimation { + /** + * 进行插值动画的视觉通道 + */ channel?: string[]; - options?: { excludeChannels?: string[] }; + /** + * 动画的配置 + */ + options?: { + /** + * 忽略的视觉通道 + */ + excludeChannels?: string[]; + }; } export interface ILabelAnimation extends ILabelEnterAnimation, ILabelExitAnimation, ILabelUpdateAnimation {} diff --git a/packages/vrender-components/src/legend/discrete/type.ts b/packages/vrender-components/src/legend/discrete/type.ts index ebe5df2d8..4ca0def55 100644 --- a/packages/vrender-components/src/legend/discrete/type.ts +++ b/packages/vrender-components/src/legend/discrete/type.ts @@ -52,6 +52,7 @@ export type LegendPagerAttributes = Omit & export type LegendScrollbarAttributes = Omit & LegendSwitchComponentAttributes & { /** + * 将翻页器的类型设置为 'scrollbar' * 申明图例组件使用滚动条进行翻页展示更多的图例项 */ type: 'scrollbar'; @@ -218,8 +219,8 @@ export type LegendItem = { */ align?: 'left' | 'right'; /** - * @since 0.21.3 * 水平方向时，一行中多个图例的垂直对齐方式 + * @since 0.21.3 */ verticalAlign?: 'top' | 'middle' | 'bottom'; }; diff --git a/packages/vrender-components/src/marker/type.ts b/packages/vrender-components/src/marker/type.ts index 45b09818e..55605d936 100644 --- a/packages/vrender-components/src/marker/type.ts +++ b/packages/vrender-components/src/marker/type.ts @@ -124,6 +124,9 @@ export type IMarkRef = { }; export type MarkerAttrs = IGroupGraphicAttribute & { + /** + * 设置标注的类型 + */ type?: 'line' | 'arc-line' | 'area' | 'arc-area' | 'point'; /** * 是否支持交互 @@ -154,23 +157,50 @@ export type MarkerAttrs = IGroupGraphicAttribute & { * 组件绘制范围配置 */ limitRect?: { + /** + * 绘制范围的起点x坐标 + */ x: number; + /** + * 绘制范围的起点y坐标 + */ y: number; + /** + * 绘制范围的宽度 + */ width: number; + /** + * 绘制范围的高度 + */ height: number; }; } & BaseMarkerAnimation; /** animation type */ export type BaseMarkerAnimation = { + /** + * 动画公共配置 + */ animation?: MarkerAnimation | boolean; + /** + * 入场动画配置 + */ animationEnter?: MarkerUpdateAnimation; + /** + * 更新动画配置 + */ animationUpdate?: MarkerUpdateAnimation; + /** + * 离场动画配置 + */ animationExit?: MarkerExitAnimation; }; export type MarkerAnimation = MarkerUpdateAnimation | MarkerUpdateAnimation; export type MarkerUpdateAnimation = { + /** + * 设置动画的类型 + */ type: T; } & MarkerExitAnimation; @@ -181,9 +211,21 @@ export type CommonMarkAreaAnimationType = 'fadeIn'; export type MarkPointAnimationType = 'callIn' | 'fadeIn'; export type MarkerExitAnimation = { + /** + * 设置离场动画的类型为fadeOut，即淡出 + */ type: 'fadeOut'; + /** + * 动画的时长 + */ duration?: number; + /** + * 动画延迟的时长 + */ delay?: number; + /** + * 动画的缓动函数 + */ easing?: EasingType; }; @@ -191,29 +233,83 @@ export type MarkerAnimationState = 'enter' | 'update' | 'exit'; /** state type */ export type MarkCommonLineState = { + /** + * 设置线图形的在特定状态下的样式 + */ line?: State; + /** + * 设置线的起点在特定状态下的样式 + */ lineStartSymbol?: State>; + /** + * 设置线的终点在特定状态下的样式 + */ lineEndSymbol?: State>; + /** + * 设置标签在特定状态下的样式 + */ label?: State>; + /** + * 设置标签背景区块在特定状态下的样式 + */ labelBackground?: State>; }; export type CommonMarkAreaState = { + /** + * 设置标注区域在特定状态下的样式 + */ area?: State>; + /** + * 设置标注区域标签在特定状态下的样式 + */ label?: State>; + /** + * 设置标签背景区块在特定状态下的样式 + */ labelBackground?: State>; }; export type MarkPointState = { + /** + * 设置标注点连线在特定状态下的样式 + */ line?: State[]>; + /** + * 设置线起点图形在特定状态下的样式 + */ lineStartSymbol?: State>; + /** + * 设置线终点图形在特定状态下的样式 + */ lineEndSymbol?: State>; + /** + * 设置标注图形在特定状态下的样式 + */ symbol?: State>; + /** + * 设置标注图形在特定状态下的样式 + */ image?: State>; + /** + * 设置标签在特定状态下的样式 + */ text?: State>; + /** + * 设置标签背景区块在特定状态下的样式 + */ textBackground?: State>; + /** + * 设置富文本在特定状态下的样式 + */ richText?: State>; + /** + * 设置自定义标注图形在特定状态下的样式 + */ customMark?: State>; + /** + * 设置目标元素在特定状态下的样式 + */ targetItem?: State>; }; @@ -235,6 +331,9 @@ export type MarkCommonLineAttrs; }; @@ -243,6 +342,9 @@ export type MarkLineAttrs = MarkCommonLineAttrs< keyof typeof IMarkLineLabelPosition, MarkCommonLineAnimationType > & { + /** + * 将辅助线的类型设置为 'line' + */ type?: 'line'; /** * 是否对 points 进行多段处理，默认为 false，即直接将所有的点连接成线。 @@ -255,9 +357,12 @@ export type MarkLineAttrs = MarkCommonLineAttrs< */ mainSegmentIndex?: number; /** - * 构成line的点: 如果是两个点，则为直线；多个点则为曲线 + * 构成line的点: 如果是两个点，则为直线；多个点则为折线 */ points: Point[] | Point[][]; + /** + * 线的样式设置 + */ lineStyle?: ILineGraphicAttribute; }; @@ -266,6 +371,9 @@ export type MarkArcLineAttrs = MarkCommonLineAttrs< keyof typeof IMarkCommonArcLabelPosition, MarkCommonLineAnimationType > & { + /** + * 将辅助线的类型设置为 'arc-line'，即弧线 + */ type?: 'arc-line'; /** * 弧线中心位置 @@ -286,6 +394,9 @@ export type MarkArcLineAttrs = MarkCommonLineAttrs< * 弧线终点角度（弧度） */ endAngle: number; + /** + * 设置弧线的样式 + */ lineStyle?: IArcGraphicAttribute; }; @@ -299,6 +410,9 @@ export type MarkAreaAttrs = MarkerAttrs & { * 标签 */ label?: { + /** + * 设置标签的位置 + */ position?: keyof typeof IMarkAreaLabelPosition; /** * 当 mark 配置了 limitRect 之后，label 是否自动调整位置 @@ -310,7 +424,9 @@ export type MarkAreaAttrs = MarkerAttrs & { * area的样式 */ areaStyle?: IPolygonAttribute; - + /** + * 设置标注区域在各种状态下的样式 + */ state?: CommonMarkAreaState; }; @@ -343,6 +459,9 @@ export type MarkArcAreaAttrs = MarkerAttrs & { * 标签 */ label?: { + /** + * 标签的位置 + */ position?: keyof typeof IMarkCommonArcLabelPosition; /** * 当 mark 配置了 limitRect 之后，label 是否自动调整位置 @@ -355,7 +474,9 @@ export type MarkArcAreaAttrs = MarkerAttrs & { * area的样式 */ areaStyle?: IArcGraphicAttribute; - + /** + * 辅助区域这种状态下各个图元的样式设置 + */ state?: CommonMarkAreaState; }; @@ -365,6 +486,9 @@ export type IItemContent = IMarkRef & { * Tips: 保留'richText'与之前的定义做兼容 */ type?: 'symbol' | 'text' | 'image' | 'richText' | 'custom'; + /** + * 设置标注的位置 + */ position?: keyof typeof IMarkPointItemPosition; /** * x 方向偏移量 @@ -405,6 +529,9 @@ export type IItemContent = IMarkRef & { export type IItemLine = { /** TODO：'type-opo' */ type?: 'type-s' | 'type-do' | 'type-po' | 'type-op' | 'type-arc'; + /** + * 是否展示该标注 + */ visible?: boolean; /** * 当type为type-arc时生效, 数值决定曲率, 符号决定法向, 不能等于0 @@ -415,7 +542,13 @@ export type IItemLine = { * 垂直于引导线的装饰线，参考案例: https://observablehq.com/@mikelotis/edmonton-population-history-line-chart */ decorativeLine?: { + /** + * 是否显示引导线的装饰线 + */ visible?: boolean; + /** + * 装饰线的长度 + */ length?: number; }; } & Omit; @@ -454,8 +587,13 @@ export type MarkPointAttrs = Omit, 'labelSty * @default 20 */ size?: number; + /** + * 被标注内容的样式设置 + */ style?: ISymbol; }; - + /** + * 标注点各个状态下的样式 + */ state?: MarkPointState; } & BaseMarkerAnimation; diff --git a/packages/vrender-components/src/poptip/type.ts b/packages/vrender-components/src/poptip/type.ts index e897fd8da..dc580011e 100644 --- a/packages/vrender-components/src/poptip/type.ts +++ b/packages/vrender-components/src/poptip/type.ts @@ -24,21 +24,33 @@ type StateStyle = { }; export type PopTipAttributes = { - /** 位置，参考arco design */ + /** + * 弹出框的方位，有 12 个方位可供选择 + */ position?: 'auto' | 'top' | 'tl' | 'tr' | 'bottom' | 'bl' | 'br' | 'left' | 'lt' | 'lb' | 'right' | 'rt' | 'rb'; /** * 标题内容，如果需要进行换行，则使用数组形式，如 ['abc', '123'] */ title?: string | string[] | number | number[]; - /** 标题样式 */ + /** + * 标题样式 + */ titleStyle?: Partial; + /** + * 标题的格式化方法 + */ titleFormatMethod?: (t: string | string[] | number | number[]) => string | string[] | number | number[]; /** * 内容文本，如果需要进行换行，则使用数组形式，如 ['abc', '123'] */ content?: string | string[] | number | number[]; - /** 内容文本样式 */ + /** + * 内容文本样式 + */ contentStyle?: Partial; + /** + * 内容的格式化方法 + */ contentFormatMethod?: (t: string | string[] | number | number[]) => string | string[] | number | number[]; /** * 标题与内容的间距 @@ -63,10 +75,17 @@ export type PopTipAttributes = { */ maxWidth?: number; - // 最大宽度比例 + /** + * 最大宽度比例 + */ maxWidthPercent?: number; - + /** + * 是否展示 + */ visible?: boolean; + /** + * 自定义的展示逻辑 + */ visibleFunc?: (graphic: IGraphic) => boolean; state?: StateStyle; dx?: number; diff --git a/packages/vrender-core/src/interface/color.ts b/packages/vrender-core/src/interface/color.ts index 7c9635d71..960186de9 100644 --- a/packages/vrender-core/src/interface/color.ts +++ b/packages/vrender-core/src/interface/color.ts @@ -1,5 +1,11 @@ interface IGradientStop { + /** + * 颜色偏移量, 0-1的值 + */ offset: number; + /** + * 颜色值 + */ color: string; } @@ -9,11 +15,29 @@ export type IGradientColor = ILinearGradient | IRadialGradient | IConicalGradien * 线性渐变色 */ export interface ILinearGradient { + /** + * 渐变色的类型设置为 'linear'，即线形渐变 + */ gradient: 'linear'; + /** + * 渐变色的起点x坐标，0-1的值，相对于图形包围盒x方向取值的比例值 + */ x0?: number; + /** + * 渐变色的起点y坐标，0-1的值，相对于图形包围盒y方向取值的比例值 + */ y0?: number; + /** + * 渐变色的终点x坐标，0-1的值，相对于图形包围盒x方向取值的比例值 + */ x1?: number; + /** + * 渐变色的终点y坐标，0-1的值，相对于图形包围盒y方向取值的比例值 + */ y1?: number; + /** + * 渐变色的颜色数组，每个颜色对象包含一个偏移量（0-1）和一个颜色值 + */ stops: IGradientStop[]; } @@ -21,13 +45,37 @@ export interface ILinearGradient { * 径向渐变色 */ export interface IRadialGradient { + /** + * 渐变色的类型设置为 'radial'，即环形渐变 + */ gradient: 'radial'; + /** + * 径向渐变的起点的x坐标 + */ x0?: number; + /** + * 径向渐变的起点的y坐标 + */ y0?: number; + /** + * 径向渐变的终点的x坐标 + */ x1?: number; + /** + * 径向渐变的终点的x坐标 + */ y1?: number; + /** + * 径向渐变的起点的半径 + */ r0?: number; + /** + * 径向渐变的终点的半径 + */ r1?: number; + /** + * 径向渐变的颜色数组，每个颜色对象包含一个偏移量（0-1）和一个颜色值 + */ stops: IGradientStop[]; } @@ -35,16 +83,40 @@ export interface IRadialGradient { * 环形渐变色/锥形渐变色 */ export interface IConicalGradient { + /** + * 渐变色的类型设置为 'conical'，即环形渐变 + */ gradient: 'conical'; + /** + * 锥形渐变的开始角度 + */ startAngle?: number; + /** + * 锥形渐变的开始角度 + */ endAngle?: number; + /** + * 锥形渐变的中心点x坐标 + */ x?: number; + /** + * 锥形渐变的中心点y坐标 + */ y?: number; + /** + * 锥形渐变的颜色 + */ stops: IGradientStop[]; } export interface IColorStop { + /** + * 颜色偏移量, 0-1的值 + */ offset: number; + /** + * 颜色值 + */ color: string; } diff --git a/packages/vrender-core/src/interface/graphic.ts b/packages/vrender-core/src/interface/graphic.ts index cda04af76..ff05f1766 100644 --- a/packages/vrender-core/src/interface/graphic.ts +++ b/packages/vrender-core/src/interface/graphic.ts @@ -91,23 +91,77 @@ export type Cursor = | 'zoom-out'; export type ITransform = { + /** + * x坐标 + */ x: number; + /** + * y坐标 + */ y: number; + /** + * z坐标 + */ z: number; + /** + * x方向偏移量 + */ dx: number; + /** + * y方向偏移量 + */ dy: number; + /** + * z方向偏移量 + */ dz: number; + /** + * x方向的滚动值 + */ scrollX: number; + /** + * y方向的滚动值 + */ scrollY: number; + /** + * x方向的缩放值 + */ scaleX: number; + /** + * y方向的缩放值 + */ scaleY: number; + /** + * z方向的缩放值 + */ scaleZ: number; + /** + * 绕z轴的转角，即xy平面上的旋转角度 + */ angle: number; + /** + * 绕x轴的转角 + */ alpha: number; + /** + * 绕y轴的转角 + */ beta: number; + /** + * 应用缩放的中心 + */ scaleCenter: [number | string, number | string]; - anchor: [number | string, number | string]; // 基于AABB的锚点位置，用于简单的定位某些path - anchor3d: [number | string, number | string, number] | [number | string, number | string]; // 3d的锚点位置 + /** + * 基于AABB的锚点位置，用于简单的定位某些path + */ + anchor: [number | string, number | string]; + /** + * 3d的锚点位置 + */ + anchor3d: [number | string, number | string, number] | [number | string, number | string]; + /** + * 处理矩阵，在正常计算完变换矩阵之后，会将该矩阵乘到变换矩阵上得到最终的变换矩阵 + */ postMatrix: IMatrix; }; @@ -140,11 +194,20 @@ export type IFillStyle = { }; export type ILayout = { + /** + * 设置对齐方式 + */ alignSelf: 'auto' | 'flex-start' | 'flex-end' | 'center'; }; export type IBorderStyle = Omit & { + /** + * 边距离边缘的距离 + */ distance: number | string; + /** + * 是否显示边框，默认是不显示的 + */ visible?: boolean; }; @@ -162,11 +225,34 @@ export type IStrokeStyle = { * 描边的透明度 */ strokeOpacity: number; + /** + * 设置线条虚线样式的属性，它通过定义实线和空白的交替长度来创建虚线效果 + */ lineDash: number[]; + + /** + * 设置虚线样式的起始偏移量 + */ lineDashOffset: number; + + /** + * 设置线条的宽度 + */ lineWidth: number; + + /** + * 设置线条末端的样式 + */ lineCap: CanvasLineCap; + + /** + * 设置线条拐角的样式 + */ lineJoin: CanvasLineJoin; + + /** + * 设置线条拐角处的斜接限制 + */ miterLimit: number; /** * 描边的boundsBuffer，用于控制bounds的buffer @@ -229,8 +315,17 @@ export type IBackgroundConfig = { type IBackgroundType = string | HTMLImageElement | HTMLCanvasElement | IBackgroundConfig; export interface SimpleDomStyleOptions { - width: number; // 容器的宽度 - height: number; // 容器的高度 + /** + * 容器的宽度 + */ + width: number; + /** + * 容器的高度 + */ + height: number; + /** + * 容器的样式设置 + */ style?: | string | Record @@ -242,13 +337,41 @@ export interface SimpleDomStyleOptions { } export interface CommonDomOptions { + /** + * 全局唯一的id + */ id?: string; - container: string | HTMLElement | null; // id或者dom + /** + * 容器元素的id或者dom元素 + */ + container: string | HTMLElement | null; + /** + * 是否显示 + */ visible?: boolean; + /** + * 是否支持事件冒泡 + */ pointerEvents?: boolean | string; - // 可穿透的事件列表 - // @since 0.21.2 + /** + * 可穿透的事件列表 + * @since 0.21.2 + */ penetrateEventList?: string[]; + /** + * 定位类型 + * 'position' - 根据挂载图形节点的坐标也就是x,y进行定位 + * 'boundsLeftTop' - 定位到挂载图形节点bounds的左上角 + * 'left' - 定位到挂载图形节点bounds 的左侧 + * 'right' - 定位到挂载图形节点bounds 的右侧 + * 'bottom' - 定位到挂载图形节点bounds 的底部 + * 'top' - 定位到挂载图形节点bounds 的顶部 + * 'center' - 定位到挂载图形节点bounds 的中心 + * 'top-left' - 定位到挂载图形节点bounds 的左上角 + * 'top-right' - 定位到挂载图形节点bounds 的右上角 + * 'bottom-left' - 定位到挂载图形节点bounds 的左下角 + * 'bottom-right' - 定位到挂载图形节点bounds 的右下角 + */ anchorType?: 'position' | 'boundsLeftTop' | BoundsAnchorType; } @@ -268,10 +391,25 @@ export type IGraphicStyle = ILayout & * 透明度，会同时影响填充和描边 */ opacity: number; + /** + * 影子节点 + */ shadowGraphic?: IGraphic | undefined; - backgroundMode: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat'; // 填充模式（与具体图元有关） - backgroundFit: boolean; // 是否正好填充，只在repeat-x或者repeat-y以及no-repeat的时候生效 + /** + * 背景填充模式（与具体图元有关） + */ + backgroundMode: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat'; + /** + * 是否正好填充，只在repeat-x或者repeat-y以及no-repeat的时候生效 + */ + backgroundFit: boolean; + /** + * 背景圆角半径 + */ backgroundCornerRadius: number | number[]; + /** + * 背景透明度 + */ backgroundOpacity: number; /** * 背景，支持颜色字符串、html image元素、html canvas元素 @@ -337,7 +475,10 @@ export type IGraphicStyle = ILayout & */ html: | ({ - dom: string | HTMLElement; // dom字符串或者dom + /** + * dom字符串或者dom + */ + dom: string | HTMLElement; } & SimpleDomStyleOptions & CommonDomOptions) | null; @@ -346,7 +487,10 @@ export type IGraphicStyle = ILayout & */ react: | ({ - element: any; // react场景节点 + /** + * react场景节点 + */ + element: any; } & SimpleDomStyleOptions & CommonDomOptions) | null; diff --git a/packages/vrender-core/src/interface/graphic/richText.ts b/packages/vrender-core/src/interface/graphic/richText.ts index 01d788a52..8568e00f9 100644 --- a/packages/vrender-core/src/interface/graphic/richText.ts +++ b/packages/vrender-core/src/interface/graphic/richText.ts @@ -5,20 +5,63 @@ import type { IImage, IImageGraphicAttribute } from './image'; import type { ITextGraphicAttribute } from './text'; export type IRichTextAttribute = { + /** + * 富文本的总宽度 + */ width: number; + /** + * 富文本的总高度 + */ height: number; + /** + * 是否可编辑 + */ editable: boolean; + /** + * 文本超长的时候是否显示省略字符串 + * 1. boolean类型，true 表示将截断后的省略字符串设置为..., false 表示不显示省略字符串 + * 2. string类型，表示显示省略字符串，并将省略字符串设置为指定的值 + */ ellipsis: boolean | string; + /** + * 文字换行类型 + */ wordBreak: RichTextWordBreak; + /** + * 文字垂直方向 + */ verticalDirection: RichTextVerticalDirection; + /** + * 富文本的最大高度，超过这个高度根据ellipsis的配置展示省略字符串或者直接截断 + */ maxHeight: number; + /** + * 富文本的最大宽度，超过这个宽度根据ellipsis的配置展示省略字符串或者直接截断 + */ maxWidth: number; + /** + * 文字对齐方式 + */ textAlign: RichTextGlobalAlignType; + /** + * 文字基线 + */ textBaseline: RichTextGlobalBaselineType; + /** + * 富文本的布局方向 + */ layoutDirection: RichTextLayoutDirectionType; + /** + * 富文本的内容配置 + */ textConfig: IRichTextCharacter[]; - // 是否不自动每行截断 + /** + * 不自动换行，仅当用户设置了换行符的时候才换行 + */ disableAutoWrapLine: boolean; + /** + * 是否强制单行显示 + */ singleLine: boolean; }; @@ -36,81 +79,230 @@ export type RichTextTextDecoration = 'none' | 'underline' | 'line-through'; export type RichTextScript = 'normal' | 'sub' | 'super'; export type IRichTextBasicCharacter = { + /** + * 行高 + */ lineHeight?: number | string; - textAlign?: CanvasTextAlign; // left, right, center + /** + * 文字对齐方式 + * left, right, center + */ + textAlign?: CanvasTextAlign; + /** + * 文字基线 + */ textBaseline?: CanvasTextBaseline; + /** + * 文字方向 + */ direction?: RichTextLayoutDirectionType; }; +/** + * 富文本段落为文本类型时候的配置 + */ export type IRichTextParagraphCharacter = IRichTextBasicCharacter & { + /** + * 文本内容 + */ text: string | number; + /** + * 富文本片段的字体大小 + */ fontSize?: number; + /** + * 富文本片段的字体类型 + */ fontFamily?: string; + /** + * 富文本片段的文字颜色 + */ fill?: IColor | boolean; + /** + * 富文本片段的文字描边颜色 + */ stroke?: IColor | boolean; + /** + * 富文本片段的文字字重 + */ fontWeight?: string; + /** + * 富文本片段的文字描边宽度 + */ lineWidth?: number; // lineHeight?: number; - fontStyle?: RichTextFontStyle; // normal, italic, oblique - textDecoration?: RichTextTextDecoration; // none, underline, line-through + /** + * 富文本片段的文字斜体设置，支持以下属性 + * normal, italic, oblique + */ + fontStyle?: RichTextFontStyle; + /** + * 富文本片段的文字中划线设置，支持以下属性 + * none, underline, line-through + */ + textDecoration?: RichTextTextDecoration; // textAlign?: RichTextTextAlign; // left, right, center script?: RichTextScript; // normal, sub, super + /** + * 富文本片段的文字下划线设置，是否显示下划线 + */ underline?: boolean; + /** + * 富文本片段的文字中划线设置，是否显示中划线 + */ lineThrough?: boolean; + /** + * 富文本片段的透明度 + */ opacity?: number; + /** + * 富文本片段的文字填充透明度 + */ fillOpacity?: number; + /** + * 富文本片段的文字描边透明度 + */ strokeOpacity?: number; // direction?: RichTextLayoutDirectionType; }; export type IRichTextImageCharacter = IRichTextBasicCharacter & { - // 图片基础属性 + /** + * 设置图片的内容， + * 支持三种格式： + * 1. 图片的url + * 2. 图片的Image对象 + * 3. 图片的Canvas对象 + */ image: string | HTMLImageElement | HTMLCanvasElement; + /** + * 图片的宽度 + */ width: number; + /** + * 图片的高度 + */ height: number; // hover相关属性 // backgroundShow?: boolean; // 是否显示background + /** + * 背景的展示模式，支持以下属性 + * always： 一直显示 + * hover： 鼠标hover时显示 + */ backgroundShowMode?: 'always' | 'hover'; - backgroundFill?: boolean | IColor; // 背景矩形填充颜色 - backgroundFillOpacity?: number; // 背景矩形填充透明度 - backgroundStroke?: boolean | IColor; // 背景矩形边框颜色 - backgroundStrokeOpacity?: number; // 背景矩形边框透明度 - backgroundRadius?: number; // 背景矩形圆角 + /** + * 背景矩形填充颜色 + */ + backgroundFill?: boolean | IColor; + /** + * 背景矩形填充透明度 + */ + backgroundFillOpacity?: number; + /** + * 背景矩形边框颜色 + */ + backgroundStroke?: boolean | IColor; + /** + * 背景矩形边框透明度 + */ + backgroundStrokeOpacity?: number; + /** + * 背景矩形圆角 + */ + backgroundRadius?: number; // background size 同时控制了该icon的响应范围 + /** + * 背景矩形的宽度 + */ backgroundWidth?: number; + /** + * 背景矩形的高度 + */ backgroundHeight?: number; - // 唯一标识符 + /** + * 唯一标识符 + */ id?: string; // lineHeight?: number; // textAlign?: RichTextTextAlign; // left, right, center // direction?: RichTextLayoutDirectionType; + /** + * 图片与相邻节点的间距 + */ margin?: number | number[]; funcType?: string; hoverImage?: string | HTMLImageElement | HTMLCanvasElement; }; - +/** + * 富文本的字符类型 + */ export type IRichTextCharacter = IRichTextParagraphCharacter | IRichTextImageCharacter; export type IRichTextIconGraphicAttribute = IImageGraphicAttribute & { + /** + * 唯一id + */ id?: string; + /** + * 背景的展示模式，支持以下属性 + * always： 一直显示 + * hover： 鼠标hover时显示 + * never： 不显示 + */ backgroundShowMode?: 'always' | 'hover' | 'never'; - backgroundFill?: boolean | IColor; // 背景矩形填充颜色 - backgroundFillOpacity?: number; // 背景矩形填充透明度 - backgroundStroke?: boolean | IColor; // 背景矩形边框颜色 - backgroundStrokeOpacity?: number; // 背景矩形边框透明度 - backgroundRadius?: number; // 背景矩形圆角 + /** + * 背景矩形填充颜色 + */ + backgroundFill?: boolean | IColor; + /** + * 背景矩形填充透明度 + */ + backgroundFillOpacity?: number; + /** + * 背景矩形边框颜色 + */ + backgroundStroke?: boolean | IColor; + /** + * 背景矩形边框透明度 + */ + backgroundStrokeOpacity?: number; + /** + * 背景矩形圆角 + */ + backgroundRadius?: number; + /** + * 背景矩形的宽度 + */ backgroundWidth?: number; + /** + * 背景矩形的高度 + */ backgroundHeight?: number; // lineHeight?: number; - textAlign?: CanvasTextAlign; // left, right, center + /** + * 文字对齐方式 + * left, right, center + */ + textAlign?: CanvasTextAlign; + /** + * 文字基线 + * top, middle, bottom + */ textBaseline?: CanvasTextBaseline; + /** + * 文字方向 + * horizontal, vertical + */ direction?: RichTextLayoutDirectionType; - + /** + * 图片与相邻节点的间距 + */ margin?: number | number[]; // backgroundShow?: boolean;