From 0b307accb69eea8e2a621c595d66bbd692c7f19e Mon Sep 17 00:00:00 2001 From: xile611 Date: Tue, 14 Jan 2025 11:50:07 +0800 Subject: [PATCH] docs: update comments for vchart --- packages/vchart/src/animation/spec.ts | 23 ++++---- .../vchart/src/component/legend/interface.ts | 16 +++++- packages/vchart/src/series/area/interface.ts | 3 +- .../vchart/src/series/box-plot/interface.ts | 2 +- .../src/series/progress/linear/interface.ts | 2 +- .../vchart/src/series/word-cloud/interface.ts | 4 +- packages/vchart/src/typings/layout.ts | 4 +- packages/vchart/src/typings/spec/common.ts | 57 ++++++++++++++++--- 8 files changed, 85 insertions(+), 26 deletions(-) diff --git a/packages/vchart/src/animation/spec.ts b/packages/vchart/src/animation/spec.ts index bca918a61b..4881c6d4c0 100644 --- a/packages/vchart/src/animation/spec.ts +++ b/packages/vchart/src/animation/spec.ts @@ -2,11 +2,7 @@ import type { IAnimationConfig, IStateAnimationConfig } from '@visactor/vgrammar import type { EasingType } from '@visactor/vrender-core'; export type { IRunningConfig as IMorphConfig, IMorphAnimationConfig } from '@visactor/vgrammar-core'; -export type IStateAnimateSpec = { - /** - * 预设动画效果 - */ - preset?: Preset | false; +export interface ICommonStateAnimateSpec { /** * 图表动画时长 */ @@ -23,7 +19,14 @@ export type IStateAnimateSpec = { * 是否轮流执行 */ oneByOne?: boolean; -}; +} + +export interface IStateAnimateSpec extends ICommonStateAnimateSpec { + /** + * 预设动画效果 + */ + preset?: Preset | false; +} export type IMarkAnimateSpec = Partial< Record @@ -38,19 +41,19 @@ export interface IAnimationSpec /** * 数据更新 - 新增数据动画 */ - animationEnter?: boolean | Omit, 'preset'> | IMarkAnimateSpec; + animationEnter?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec; /** * 数据更新 - 数据更新动画 */ - animationUpdate?: boolean | Omit, 'preset'> | IMarkAnimateSpec; + animationUpdate?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec; /** * 数据更新 - 数据删除动画 */ - animationExit?: boolean | Omit, 'preset'> | IMarkAnimateSpec; + animationExit?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec; /** * 图表退场动画 */ - animationDisappear?: boolean | Omit, 'preset'> | IMarkAnimateSpec; + animationDisappear?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec; /** * 状态切换动画 * @since 1.12.0 diff --git a/packages/vchart/src/component/legend/interface.ts b/packages/vchart/src/component/legend/interface.ts index 7e21caa3db..2154d89b97 100644 --- a/packages/vchart/src/component/legend/interface.ts +++ b/packages/vchart/src/component/legend/interface.ts @@ -67,12 +67,24 @@ export type ILegendCommonSpec = { */ visible?: boolean; /** - * 图例位置 + * 图例的位置，相对于region区域的四个方位， + * left - 图例在左侧 + * right - 图例在右侧 + * top - 图例在上方 + * bottom - 图例在下方 * @default 'left' */ orient?: IOrientType; /** - * 图例在当前行列的对齐方式，起始 | 居中 | 末尾 + * 图例在当前行或者列的对齐方式，起始 | 居中 | 末尾， + * 对于orient为'left'或者'right'的图例， + * start - 图例在左侧 + * middle - 图例居中 + * end - 图例在右侧 + * 对于orient为'top'或者'bottom'的图例， + * start - 图例在上方 + * middle - 图例居中 + * end - 图例在下方 * @default 'middle' */ position?: 'start' | 'middle' | 'end'; diff --git a/packages/vchart/src/series/area/interface.ts b/packages/vchart/src/series/area/interface.ts index f8f166b036..7520b7fcf7 100644 --- a/packages/vchart/src/series/area/interface.ts +++ b/packages/vchart/src/series/area/interface.ts @@ -8,6 +8,7 @@ import type { IDataSamping, IMarkOverlap, IMarkProgressiveConfig } from '../../m import type { IMultiLabelSpec, ILabelSpec } from '../../component/label/interface'; import type { DirectionType } from '../../typings/space'; +type AreaMarks = 'point' | 'line' | 'area'; export interface IAreaAnimationParams { direction: DirectionType; } @@ -16,7 +17,7 @@ export type AreaAppearPreset = 'clipIn' | 'fadeIn' | 'grow'; export interface IAreaSeriesSpec extends ICartesianSeriesSpec, - IAnimationSpec, + IAnimationSpec, IMarkProgressiveConfig, IDataSamping, IMarkOverlap { diff --git a/packages/vchart/src/series/box-plot/interface.ts b/packages/vchart/src/series/box-plot/interface.ts index 876c2890fc..d0ffdf996b 100644 --- a/packages/vchart/src/series/box-plot/interface.ts +++ b/packages/vchart/src/series/box-plot/interface.ts @@ -7,7 +7,7 @@ import type { SeriesMarkNameEnum } from '../interface/type'; export interface IBoxPlotSeriesSpec extends Omit, // TODO: 补充动画类型 @chengda - IAnimationSpec, + IAnimationSpec, IMarkProgressiveConfig { /** 系列类型 */ type: 'boxPlot'; diff --git a/packages/vchart/src/series/progress/linear/interface.ts b/packages/vchart/src/series/progress/linear/interface.ts index 0f4bcf87f5..6f8cb463e3 100644 --- a/packages/vchart/src/series/progress/linear/interface.ts +++ b/packages/vchart/src/series/progress/linear/interface.ts @@ -14,7 +14,7 @@ export type LinearProgressAppearPreset = 'grow' | 'fadeIn'; export interface ILinearProgressSeriesSpec extends IProgressSeriesSpec, // TODO: 补充MarkName类型 @liupei - IAnimationSpec { + IAnimationSpec { type: 'linearProgress'; /** * coordinate: 'cartesian' diff --git a/packages/vchart/src/series/word-cloud/interface.ts b/packages/vchart/src/series/word-cloud/interface.ts index 8b411e8bb6..8f4aa14917 100644 --- a/packages/vchart/src/series/word-cloud/interface.ts +++ b/packages/vchart/src/series/word-cloud/interface.ts @@ -199,7 +199,9 @@ export type WordCloudShapeConfigType = { fillingRatio?: number; }; -export interface IWordCloudSeriesBaseSpec extends ISeriesSpec, IAnimationSpec { +export interface IWordCloudSeriesBaseSpec + extends ISeriesSpec, + IAnimationSpec { /** * 文本字段 */ diff --git a/packages/vchart/src/typings/layout.ts b/packages/vchart/src/typings/layout.ts index c77e1f0772..e91c98e7bc 100644 --- a/packages/vchart/src/typings/layout.ts +++ b/packages/vchart/src/typings/layout.ts @@ -21,11 +21,11 @@ export type IPercent = `${number}%`; export type IPercentOffset = { /** - * 百分比值 + * 百分比值，取值范围为0-1 */ percent?: number; /** - * 偏移量 + * 偏移量，偏移的像素值 */ offset?: number; }; diff --git a/packages/vchart/src/typings/spec/common.ts b/packages/vchart/src/typings/spec/common.ts index 06f80bce9b..85fd53c156 100644 --- a/packages/vchart/src/typings/spec/common.ts +++ b/packages/vchart/src/typings/spec/common.ts @@ -248,12 +248,7 @@ export interface IChartSpec { media?: IMediaQuerySpec; } -export type IBackgroundStyleSpec = ConvertToMarkStyleSpec> & { - image?: IRectMarkSpec['background']; - cornerRadius?: IRectMarkSpec['cornerRadius']; -}; - -export type IBackgroundSpec = IColor | IBackgroundStyleSpec; +export type IBackgroundSpec = IColor | ConvertToMarkStyleSpec; /** data */ export type IDataType = IDataValues | DataView; @@ -492,6 +487,29 @@ export type AdaptiveSpec = { [key in Exclude]: T[key]; } & { [key in K]: any }; +export interface IMarkStateFullSpec extends Record | IMarkStateStyleSpec> { + /** + * 正常状态下图元的样式设置 + */ + normal?: IMarkStateSpec | IMarkStateStyleSpec; + /** + * hover状态下图元的样式设置 + */ + hover?: IMarkStateSpec | IMarkStateStyleSpec; + /** + * 没有被hover的状态下图元的样式设置 + */ + hover_reverse?: IMarkStateSpec | IMarkStateStyleSpec; + /** + * 选中状态下图元的样式设置 + */ + selected?: IMarkStateSpec | IMarkStateStyleSpec; + /** + * 没有被选中的状态下图元的样式设置 + */ + selected_reverse?: IMarkStateSpec | IMarkStateStyleSpec; +} + /** markSpec */ export type IMarkSpec = { /** @@ -518,7 +536,7 @@ export type IMarkSpec = { /** 默认样式设置 */ style?: ConvertToMarkStyleSpec; /** 不同状态下的样式配置 */ - state?: Record | IMarkStateStyleSpec>; + state?: IMarkStateFullSpec; /** * 状态排序方法，默认状态都是按照添加的顺序处理的，如果有特殊的需求，需要指定状态顺序，可以通过这个方法实现 * @since 1.9.0 @@ -561,6 +579,29 @@ export interface IMarkStateSpec { export type IMarkStateStyleSpec = ConvertToMarkStyleSpec; +export interface IMarkStateTheme extends Record { + /** + * 图元在正常状态下的主题样式设置 + */ + normal?: T; + /** + * 图元在 hover 状态下的主题样式设置 + */ + hover?: T; + /** + * 图元在 未被hover 状态下的主题样式设置 + */ + hover_reverse?: T; + /** + * 图元在 选中状态下的主题样式设置 + */ + selected?: T; + /** + * 图元在 未被选中 状态下的主题样式设置 + */ + selected_reverse?: T; +} + export type IMarkTheme = { /** * mark 层 是否显示配置 @@ -569,7 +610,7 @@ export type IMarkTheme = { /** 默认样式设置 */ style?: T; /** 不同状态下的样式配置 */ - state?: Record; + state?: IMarkStateTheme; /** * 可交互的开关 */