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 extends string> = {
-  /**
-   * 预设动画效果
-   */
-  preset?: Preset | false;
+export interface ICommonStateAnimateSpec {
   /**
    * 图表动画时长
    */
@@ -23,7 +19,14 @@ export type IStateAnimateSpec<Preset extends string> = {
    * 是否轮流执行
    */
   oneByOne?: boolean;
-};
+}
+
+export interface IStateAnimateSpec<Preset extends string> extends ICommonStateAnimateSpec {
+  /**
+   * 预设动画效果
+   */
+  preset?: Preset | false;
+}
 
 export type IMarkAnimateSpec<MarkName extends string> = Partial<
   Record<MarkName, false | IAnimationConfig | IAnimationConfig[]>
@@ -38,19 +41,19 @@ export interface IAnimationSpec<MarkName extends string, Preset extends string>
   /**
    * 数据更新 - 新增数据动画
    */
-  animationEnter?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationEnter?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 数据更新 - 数据更新动画
    */
-  animationUpdate?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationUpdate?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 数据更新 - 数据删除动画
    */
-  animationExit?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationExit?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 图表退场动画
    */
-  animationDisappear?: boolean | Omit<IStateAnimateSpec<Preset>, 'preset'> | IMarkAnimateSpec<MarkName>;
+  animationDisappear?: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>;
   /**
    * 状态切换动画
    * @since 1.12.0
diff --git a/packages/vchart/src/component/axis/cartesian/interface/spec.ts b/packages/vchart/src/component/axis/cartesian/interface/spec.ts
index 5eba9266aa..e444dca917 100644
--- a/packages/vchart/src/component/axis/cartesian/interface/spec.ts
+++ b/packages/vchart/src/component/axis/cartesian/interface/spec.ts
@@ -18,6 +18,9 @@ export type ICartesianAxisSpec =
   | ICartesianSymlogAxisSpec;
 
 export type ICartesianVertical = {
+  /**
+   * 坐标轴的位置
+   */
   orient: 'left' | 'right';
   /**
    * 内padding/留白
@@ -35,6 +38,9 @@ export type ICartesianVertical = {
   };
 };
 export type ICartesianHorizontal = {
+  /**
+   * 坐标轴的位置
+   */
   orient: 'top' | 'bottom';
   /**
    * 内padding/留白
@@ -52,6 +58,9 @@ export type ICartesianHorizontal = {
   };
 };
 export type ICartesianZ = {
+  /**
+   * 坐标轴的位置
+   */
   orient: 'z';
 };
 
@@ -139,6 +148,9 @@ export interface ILinearAxisSync {
 
 export type ICartesianLinearAxisSpec = ICartesianAxisCommonSpec &
   ILinearAxisSpec & {
+    /**
+     * 设置轴同步相关内容，包含0值对齐和刻度对齐功能
+     */
     sync?: ILinearAxisSync;
   };
 
diff --git a/packages/vchart/src/component/axis/interface/common.ts b/packages/vchart/src/component/axis/interface/common.ts
index 2390a9206e..200da00504 100644
--- a/packages/vchart/src/component/axis/interface/common.ts
+++ b/packages/vchart/src/component/axis/interface/common.ts
@@ -22,12 +22,24 @@ export interface IAxis extends IComponent {
 }
 
 export interface IAxisItem<T> {
+  /**
+   * 是否显示
+   */
   visible?: boolean;
+  /**
+   * 样式配置
+   */
   style?: Omit<T, 'visible'>;
 }
 
 export interface IAxisItemTheme<T> {
+  /**
+   * 是否显示
+   */
   visible?: boolean;
+  /**
+   * 主题样式配置
+   */
   style?: Omit<T, 'visible'>;
 }
 export type AxisAnimationPreset = 'groupFadeIn' | 'fadeIn' | 'grow';
diff --git a/packages/vchart/src/component/axis/interface/spec.ts b/packages/vchart/src/component/axis/interface/spec.ts
index fd5ae488c6..887667567c 100644
--- a/packages/vchart/src/component/axis/interface/spec.ts
+++ b/packages/vchart/src/component/axis/interface/spec.ts
@@ -141,7 +141,13 @@ export interface ILinearAxisSpec {
    * @description 当配置了 min和 max，该配置项失效
    */
   expand?: {
+    /**
+     * 轴范围扩展的最小比例
+     */
     min?: number;
+    /**
+     * 轴范围扩展的最大比例
+     */
     max?: number;
   };
 
diff --git a/packages/vchart/src/component/crosshair/interface/spec.ts b/packages/vchart/src/component/crosshair/interface/spec.ts
index f864e7bc29..44c531e71b 100644
--- a/packages/vchart/src/component/crosshair/interface/spec.ts
+++ b/packages/vchart/src/component/crosshair/interface/spec.ts
@@ -15,8 +15,13 @@ export type CrossHairTrigger = 'click' | 'hover' | ['click', 'hover'];
 
 export interface ICommonCrosshairSpec extends IComponentSpec {
   /**
-   * 是否和tooltip保持同步
+   * 是否和tooltip保持同步，默认为false
    * tooltip出现的时候crosshair出现；tooltip隐藏的时候crsshair隐藏；
+   * 默认只要有tooltip显示，都会显示crosshair
+   * 也可以通过设置 followTooltip.dimension 为 `false` 来实现显示dimension tooltip的时候不显示crosshair
+   * 设置 followTooltip.mark 为 `false` 来实现显示mark tooltip的时候不显示crosshair
+   * 设置 followTooltip.group 为 `false` 来实现显示group tooltip的时候不显示crosshair
+   *
    * @since 1.11.1
    */
   followTooltip?: boolean | Partial<ITooltipActiveTypeAsKeys<boolean, boolean, boolean>>;
@@ -110,11 +115,11 @@ export type ICrosshairRectStyle = ICrosshairLineStyle & Pick<IRectMarkSpec, 'fil
 
 export interface ICrosshairLineSpec {
   /**
-   * 是否显示
+   * 是否显示辅助图形
    */
   visible?: boolean;
   /**
-   * 辅助图形的类型
+   * 辅助图形的类型设置为'line'
    */
   type?: 'line';
   /**
@@ -122,7 +127,9 @@ export interface ICrosshairLineSpec {
    * @default 2
    */
   width?: number;
-  /** 极坐标系下是否平滑 */
+  /**
+   * 极坐标系下是否平滑
+   */
   smooth?: boolean;
   /**
    * 辅助图形的样式配置
@@ -133,7 +140,13 @@ export interface ICrosshairLineSpec {
 export type ICrosshairRectWidthCallback = (axisSize: { width: number; height: number }, axis: IAxis) => number;
 
 export interface ICrosshairRectSpec {
+  /**
+   * 是否显示辅助图形
+   */
   visible?: boolean;
+  /**
+   * 辅助图形的类型设置为'rect'
+   */
   type?: 'rect';
   /**
    * 字符串xx%表示此处是内容区间的百分比，数字表示宽度像素，
@@ -141,10 +154,16 @@ export interface ICrosshairRectSpec {
    * @default '100%''
    */
   width?: number | string | ICrosshairRectWidthCallback;
+  /**
+   * 辅助图形的样式配置
+   */
   style?: ICrosshairRectStyle;
 }
 
 export interface ICrosshairLabelSpec {
+  /**
+   * 十字准星辅助标签是否展示
+   */
   visible?: boolean;
   /**
    * label 文本格式化方法
@@ -186,6 +205,9 @@ export interface ICrosshairLabelBackgroundSpec {
    * 内部边距
    */
   padding?: IPadding | number | number[];
+  /**
+   * 标签背景的样式配置
+   */
   style?: Partial<IRectMarkSpec>;
 }
 
diff --git a/packages/vchart/src/component/data-zoom/data-zoom/interface.ts b/packages/vchart/src/component/data-zoom/data-zoom/interface.ts
index 6e1069e85b..3fa8180582 100644
--- a/packages/vchart/src/component/data-zoom/data-zoom/interface.ts
+++ b/packages/vchart/src/component/data-zoom/data-zoom/interface.ts
@@ -115,15 +115,15 @@ export interface IDataZoomStyle {
 /** spec */
 export interface IDataZoomSpec extends IDataZoomStyle, IDataFilterComponentSpec {
   /**
-   * @since 1.11.3
    * 是否展示背景图
+   * @since 1.11.3
    */
   showBackgroundChart?: boolean;
   /**
    * 数据过滤模式
-   * @default 'filter' （dataZoom默认数据过滤模式）
    * 'filter' 为过滤数据从而达到缩放轴的效果, 'axis'为直接缩放轴, 不过滤数据
    * 具体效果可参考: https://www.visactor.io/vchart/demo/sequence-chart/social-media-event?keyword=dataZoom
+   * @default 'filter' （dataZoom默认数据过滤模式）
    */
   filterMode?: IFilterMode;
   /**
diff --git a/packages/vchart/src/component/label/interface.ts b/packages/vchart/src/component/label/interface.ts
index 40f65072ff..a628844807 100644
--- a/packages/vchart/src/component/label/interface.ts
+++ b/packages/vchart/src/component/label/interface.ts
@@ -82,9 +82,13 @@ export interface ILabelSpec extends IComponentSpec, ILabelAnimationSpec {
    * @since 1.3.0
    */
   customOverlapFunc?: BaseLabelAttrs['customOverlapFunc'];
-  /** 标签布局 */
+  /**
+   * 标签布局
+   */
   labelLayout?: 'series' | 'region';
-  /** 是否支持3D */
+  /**
+   * 是否支持3D
+   */
   support3d?: boolean;
   /**
    * 是否同步数据图元的状态变化
diff --git a/packages/vchart/src/component/legend/continuous/interface.ts b/packages/vchart/src/component/legend/continuous/interface.ts
index 04d9092c2a..a925a4916d 100644
--- a/packages/vchart/src/component/legend/continuous/interface.ts
+++ b/packages/vchart/src/component/legend/continuous/interface.ts
@@ -41,7 +41,7 @@ export type HandlerTextAttribute = {
 // 连续图例通用配置
 export type IContinuousLegendSpec = ILegendCommonSpec & {
   /**
-   * 是否开启反向展示
+   * 连续图例是否开启反向展示，最小值和最大值会发生反向
    * @default false
    * @since 1.11.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/component/marker/interface.ts b/packages/vchart/src/component/marker/interface.ts
index 5c473325bd..28fb3d169c 100644
--- a/packages/vchart/src/component/marker/interface.ts
+++ b/packages/vchart/src/component/marker/interface.ts
@@ -158,6 +158,9 @@ export type IMarkerPositionsSpec = {
 };
 
 export type IMarkerLabelWithoutRefSpec = {
+  /**
+   * 是否展示标注标签
+   */
   visible?: boolean;
   /**
    * label整体 - 是否自动旋转
@@ -176,6 +179,9 @@ export type IMarkerLabelWithoutRefSpec = {
    * label整体 - 背景面板配置
    */
   labelBackground?: {
+    /**
+     * 标签背景是否显示，是否可见
+     */
     visible?: boolean;
     /**
      * 标签背景支持自定义path
@@ -192,7 +198,10 @@ export type IMarkerLabelWithoutRefSpec = {
     padding?: IPadding | number[] | number;
   } & Partial<IMarkerState<Omit<IRectMarkSpec, 'visible'>>>;
 
-  /** @deprecated  */
+  /**
+   * @deprecated
+   * 设置文本类型为富文本或者普通文本，已废弃
+   **/
   type?: 'rich' | 'text';
   /**
    * 文本内容，如果需要进行换行，则使用数组形式，如 ['abc', '123']
@@ -211,7 +220,13 @@ export type IMarkerLabelWithoutRefSpec = {
    * label文本 - 文本前 mark 图元
    */
   shape?: {
+    /**
+     * 是否显示标签文本前的图形
+     */
     visible?: boolean;
+    /**
+     * 标签文本前的图形对应的样式设置
+     */
     style: Omit<ISymbolMarkSpec, 'visible'>;
   };
   /**
@@ -255,17 +270,30 @@ export interface IMarkerRef {
 // 跨越系列的配置
 export interface IMarkerCrossSeriesSpec {
   /**
-   * 起点和终点关联的series（仅在标注目标：坐标空间下有效）
+   * 设置起点关联的系列，设置该系列的序号（仅在标注目标：坐标空间下有效）
    */
   startRelativeSeriesIndex?: number;
+  /**
+   * 设置终点关联的系列，设置该序列的序号（仅在标注目标：坐标空间下有效）
+   */
   endRelativeSeriesIndex?: number;
+  /**
+   * 设置起点关联的系列，设置该系列的id（仅在标注目标：坐标空间下有效）
+   */
   startRelativeSeriesId?: string;
+  /**
+   * 设置终点关联的系列，设置该序列的id（仅在标注目标：坐标空间下有效）
+   */
   endRelativeSeriesId?: string;
   /**
-   * 数据处理需要单独关联系列, 当配置为'all'时代表关联当前region下所有系列
+   * 数据处理需要单独关联系列, 设置序列的序号来进行关联，当配置为'all'时代表关联当前region下所有系列
    * @since 1.11.0
    */
   specifiedDataSeriesIndex?: 'all' | number | number[];
+  /**
+   * 数据处理需要单独关联系列, 设置序列的id来进行关联，当配置为'all'时代表关联当前region下所有系列
+   * @since 1.11.0
+   */
   specifiedDataSeriesId?: 'all' | string | string[];
 }
 
diff --git a/packages/vchart/src/component/marker/mark-area/interface/spec.ts b/packages/vchart/src/component/marker/mark-area/interface/spec.ts
index 4af446b976..1b3242ee08 100644
--- a/packages/vchart/src/component/marker/mark-area/interface/spec.ts
+++ b/packages/vchart/src/component/marker/mark-area/interface/spec.ts
@@ -53,6 +53,9 @@ export interface IMarkAreaXSpec extends IMarkerCrossSeriesSpec {
    * 可以将 x 配置为 '15%' 百分比的形式，用于表示将 x 绘制在 marker 所在 region 横轴（从左往右）的百分之 15 位置处
    */
   x: IDataPos | IDataPosCallback;
+  /**
+   * 设置x轴上的第二个值，如果同时设置了x 和 x1，会形成一个范围
+   */
   x1: IDataPos | IDataPosCallback;
 }
 
@@ -62,6 +65,9 @@ export interface IMarkAreaYSpec extends IMarkerCrossSeriesSpec {
    * 可以将 y 配置为 '15%' 百分比的形式，用于表示将 y 绘制在 marker 所在 region 纵轴（从上到下）的百分之 15 位置处
    */
   y: IDataPos | IDataPosCallback;
+  /**
+   * 设置y轴上的第二个值，如果同时设置了y 和 y1，会形成一个范围
+   */
   y1: IDataPos | IDataPosCallback;
 }
 
@@ -71,12 +77,18 @@ export interface IMarkAreaXYSpec extends IMarkerCrossSeriesSpec {
    * 可以将 x 配置为 '15%' 百分比的形式，用于表示将 x 绘制在 marker 所在 region 横轴（从左往右）的百分之 15 位置处
    */
   x: IDataPos | IDataPosCallback;
+  /**
+   * 设置x轴上的第二个值，如果同时设置了x 和 x1，会形成一个范围
+   */
   x1: IDataPos | IDataPosCallback;
   /**
    * y轴上的参考线。可以配置参考线在y轴上的值，或者聚合计算类型
    * 可以将 y 配置为 '15%' 百分比的形式，用于表示将 y 绘制在 marker 所在 region 纵轴（从上到下）的百分之 15 位置处
    */
   y: IDataPos | IDataPosCallback;
+  /**
+   * 设置y轴上的第二个值，如果同时设置了y 和 y1，会形成一个范围
+   */
   y1: IDataPos | IDataPosCallback;
 }
 
diff --git a/packages/vchart/src/component/marker/mark-area/interface/theme.ts b/packages/vchart/src/component/marker/mark-area/interface/theme.ts
index ccb458b722..07987497d7 100644
--- a/packages/vchart/src/component/marker/mark-area/interface/theme.ts
+++ b/packages/vchart/src/component/marker/mark-area/interface/theme.ts
@@ -3,8 +3,13 @@ import type { IArcMarkSpec, IPolygonMarkSpec } from '../../../../typings';
 import type { IMarkerLabelWithoutRefSpec, IMarkerState } from '../../interface';
 
 export interface IMarkAreaTheme {
+  /**
+   * 标记区域的样式
+   */
   area?: Partial<IMarkerState<IPolygonMarkSpec | IArcMarkSpec>>;
-
+  /**
+   * 标记区域的标签样式配置
+   */
   label?: {
     /**
      * label整体 - 相对line的位置
diff --git a/packages/vchart/src/component/title/interface/spec.ts b/packages/vchart/src/component/title/interface/spec.ts
index 9f5cf75f50..4adfafcfd3 100644
--- a/packages/vchart/src/component/title/interface/spec.ts
+++ b/packages/vchart/src/component/title/interface/spec.ts
@@ -63,7 +63,13 @@ interface ITitleSpecWithoutText extends Omit<IComponentSpec, 'orient'> {
    * 主标题样式
    */
   textStyle?: {
+    /**
+     * 给主标题设置给定的宽度
+     */
     width?: number;
+    /**
+     * 给主标题设置给定的高度
+     */
     height?: number;
     /**
      * 文字水平对齐方式
diff --git a/packages/vchart/src/component/tooltip/interface/spec.ts b/packages/vchart/src/component/tooltip/interface/spec.ts
index 8d08696f96..79cba1dab6 100644
--- a/packages/vchart/src/component/tooltip/interface/spec.ts
+++ b/packages/vchart/src/component/tooltip/interface/spec.ts
@@ -20,6 +20,9 @@ export interface ITooltipSpec
      */
     ITooltipActiveTypeAsKeys<
       ITooltipPattern & {
+        /**
+         * mark tooltip是否展示触发点所在的所有图形的数据
+         */
         checkOverlap?: boolean;
       },
       ITooltipPattern,
@@ -129,7 +132,13 @@ export interface ITooltipSpec
    * 计算tooltip位置时候的偏移量
    */
   offset?: {
+    /**
+     * x 方向的偏移量
+     */
     x?: number;
+    /**
+     * y 方向的偏移量
+     */
     y?: number;
   };
 }
diff --git a/packages/vchart/src/component/tooltip/interface/theme.ts b/packages/vchart/src/component/tooltip/interface/theme.ts
index d9ce10ff28..f2bdff0212 100644
--- a/packages/vchart/src/component/tooltip/interface/theme.ts
+++ b/packages/vchart/src/component/tooltip/interface/theme.ts
@@ -4,29 +4,54 @@ import type { Padding } from '@visactor/vrender-components';
 import type { ITokenKey } from '../../../theme/token/interface';
 
 export interface ITooltipTextTheme<ColorType = string> {
-  /** 字体 */
+  /**
+   * 字体
+   */
   fontFamily?: string;
-  /** 字体大小 */
+  /**
+   * 字体大小
+   */
   fontSize?: number | ITokenKey;
-  /** 字体颜色 */
+  /**
+   * 字体颜色
+   */
   fill?: ColorType;
-  /** @deprecated 字体颜色（兼容旧版本） */
+  /**
+   * 字体颜色（兼容旧版本）
+   * @deprecated
+   */
   fontColor?: ColorType;
-  /** 字重 */
+  /**
+   * 字重
+   */
   fontWeight?: StringOrNumber;
-  /** 对齐方式 */
+  /**
+   * 对齐方式
+   */
   textAlign?: TextAlign;
-  /** 字体基线 */
+  /**
+   * 字体基线
+   */
   textBaseline?: TextBaseLine;
-  /** 行高 */
+  /**
+   * 行高
+   */
   lineHeight?: number | string | ITokenKey;
-  /** 与相邻元素的水平间距 */
+  /**
+   * 与相邻元素的水平间距
+   */
   spacing?: number;
-  /** 是否支持换行 */
+  /**
+   * 是否支持换行
+   */
   multiLine?: boolean;
-  /** 最大宽度 */
+  /**
+   * 最大宽度
+   */
   maxWidth?: number;
-  /** 换行模式，默认为'break-word' */
+  /**
+   * 换行模式，默认为'break-word'
+   */
   wordBreak?: ITextAttribute['wordBreak'];
   /**
    * 是否开启自动宽度。效果分为以下几种情况：
@@ -61,6 +86,9 @@ export interface ITooltipTheme<ColorType = string> {
       color: ColorType;
     };
   };
+  /**
+   * 设置 tooltip 中 shape 的样式
+   */
   shape?: {
     /** 标记大小 */
     size?: number;
@@ -92,11 +120,10 @@ export interface ITooltipTheme<ColorType = string> {
    */
   transitionDuration?: number;
   /**
-   * @since 1.11.5
-   *
    * shape、key、value的对齐方式，可选项如下：
    * 'left': 从左到右对齐
    * 'right': 从右到左对齐
+   * @since 1.11.5
    */
   align?: 'left' | 'right';
 }
diff --git a/packages/vchart/src/interaction/interface.ts b/packages/vchart/src/interaction/interface.ts
index ac635f29c4..13db40d750 100644
--- a/packages/vchart/src/interaction/interface.ts
+++ b/packages/vchart/src/interaction/interface.ts
@@ -55,7 +55,13 @@ export interface ITriggerOption {
 }
 
 export interface IBaseInteractionSpec {
+  /**
+   * 触发交互的图元id
+   */
   markIds?: StringOrNumber[];
+  /**
+   * 触发交互的图元名称
+   */
   markNames?: StringOrNumber[];
 }
 
diff --git a/packages/vchart/src/layout/interface.ts b/packages/vchart/src/layout/interface.ts
index cbaa4458b3..a19bc93c5a 100644
--- a/packages/vchart/src/layout/interface.ts
+++ b/packages/vchart/src/layout/interface.ts
@@ -25,40 +25,99 @@ export type LayoutCallBack = (
 ) => void;
 
 export interface ILayoutSpecBase {
+  /**
+   * 布局的类型，现在支持 grid布局和默认布局（基于占位的布局）
+   */
   type: string;
 }
 
 export type ElementSpec = (
   | {
-      modelKey: string; // spec key
+      /**
+       * 组件对应的spec key，如'legends'表示图例
+       */
+      modelKey: string;
+      /**
+       * 组件对应的序号
+       */
       modelIndex: number;
     }
   | {
+      /**
+       * 组件对应的id
+       */
       modelId: string;
     }
 ) & {
+  /**
+   * 组件在grid布局中所在的列。从左向右，从 0 开始计数
+   */
   col: number;
+  /**
+   * 组件在grid布局中所在的列跨度，即占了几列，默认值为1
+   */
   colSpan?: number;
+  /**
+   * 组件在grid布局中所在的行。从上向下，从 0 开始计数。
+   */
   row: number;
+  /**
+   * 组件在grid布局中所在的行跨度，即占了几行，默认值为1
+   */
   rowSpan?: number;
 };
 
 export interface IGridLayoutSpec extends ILayoutSpecBase {
+  /**
+   * 设置布局类型为grid布局
+   */
   type: 'grid';
+  /**
+   * grid布局的总列数
+   */
   col: number;
+  /**
+   * grid布局的总行数
+   */
   row: number;
+  /**
+   * 可选配置，指定某几列的宽度
+   */
   colWidth?: {
+    /**
+     * 指定列数，序号从 0 开始
+     */
     index: number;
+    /**
+     * 设置指定列的宽度，单位为像素
+     */
     size: number | ((maxSize: number) => number);
   }[];
+  /**
+   * 可选配置，指定某几行的高度
+   */
   rowHeight?: {
+    /**
+     * 指定行数，序号从 0 开始
+     */
     index: number;
+    /**
+     * 设置指定行的高度，单位为像素
+     */
     size: number | ((maxSize: number) => number);
   }[];
+  /**
+   *
+   * 指定所有图表元素所在位置，图表元素的位置起点和占几行几列，可以占多行多列
+   * 图表元素位置允许配置重叠。
+   */
   elements: ElementSpec[];
 }
 
 export interface IBaseLayoutSpec extends ILayoutSpecBase {
+  /**
+   * 设置布局类型为默认布局
+   */
   type: 'base';
 }
 
diff --git a/packages/vchart/src/mark/interface/common.ts b/packages/vchart/src/mark/interface/common.ts
index 2f4456662d..18e1ebd91d 100644
--- a/packages/vchart/src/mark/interface/common.ts
+++ b/packages/vchart/src/mark/interface/common.ts
@@ -87,7 +87,9 @@ export interface ICompileMarkConfig extends IMarkConfig {
 
   /** morph元素的唯一key */
   morphElementKey?: string;
-  /** 是否支持 3d */
+  /**
+   * 是否支持 3d
+   */
   support3d?: boolean;
   /* customized shape of mark  */
   setCustomizedShape?: (datum: any[], attrs: any, path: ICustomPath2D) => ICustomPath2D;
diff --git a/packages/vchart/src/region/interface.ts b/packages/vchart/src/region/interface.ts
index 48bfd33f52..02b046778d 100644
--- a/packages/vchart/src/region/interface.ts
+++ b/packages/vchart/src/region/interface.ts
@@ -97,7 +97,13 @@ export interface IGeoRegionSpec extends IRegionSpec {
    * 缩放最大最小倍数限制
    */
   zoomLimit?: {
+    /**
+     * 最小缩放倍数
+     */
     min?: number;
+    /**
+     * 最大缩放倍数
+     */
     max?: number;
   };
 }
diff --git a/packages/vchart/src/series/area/interface.ts b/packages/vchart/src/series/area/interface.ts
index 7ed24998ef..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<string, AreaAppearPreset>,
+    IAnimationSpec<AreaMarks, AreaAppearPreset>,
     IMarkProgressiveConfig,
     IDataSamping,
     IMarkOverlap {
@@ -50,6 +51,9 @@ export interface IAreaSeriesSpec
    */
   [SeriesMarkNameEnum.label]?: IMultiLabelSpec<
     Omit<ILineLikeLabelSpec, 'position'> & {
+      /**
+       * 标签位置，面积图元支持的标签位置
+       * */
       position:
         | 'top'
         | 'bottom'
@@ -68,6 +72,11 @@ export interface IAreaSeriesSpec
    * @since 1.7.0
    */
   [SeriesMarkNameEnum.areaLabel]?: Omit<ILabelSpec, 'position'> & {
+    /**
+     * 面积图元标签的位置配置，支持两种位置：
+     * - start：面积图元的起点
+     * - end：面积图元的终点
+     */
     position?: 'start' | 'end';
   };
   /**
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<ICartesianSeriesSpec, 'xField' | 'yField' | 'direction'>,
     // TODO: 补充动画类型 @chengda
-    IAnimationSpec<string, string>,
+    IAnimationSpec<SeriesMarkNameEnum.boxPlot, string>,
     IMarkProgressiveConfig {
   /** 系列类型 */
   type: 'boxPlot';
diff --git a/packages/vchart/src/series/circle-packing/interface.ts b/packages/vchart/src/series/circle-packing/interface.ts
index 6bb55c099a..9ef374db55 100644
--- a/packages/vchart/src/series/circle-packing/interface.ts
+++ b/packages/vchart/src/series/circle-packing/interface.ts
@@ -57,7 +57,16 @@ export interface ICirclePackingSeriesSpec
 }
 
 export interface ICirclePackingSeriesTheme extends Omit<IPolarSeriesTheme, 'label'> {
+  /**
+   * 层内边距
+   */
   layoutPadding?: number | number[];
+  /**
+   * 标签的主题样式配置
+   */
   [SeriesMarkNameEnum.label]?: IMarkTheme<ITextMarkSpec>;
+  /**
+   * 圆图元的主题样式配置
+   */
   [SeriesMarkNameEnum.circlePacking]?: IMarkTheme<IArcMarkSpec>;
 }
diff --git a/packages/vchart/src/series/interface/common.ts b/packages/vchart/src/series/interface/common.ts
index b6fbbe886d..923d65f5ef 100644
--- a/packages/vchart/src/series/interface/common.ts
+++ b/packages/vchart/src/series/interface/common.ts
@@ -61,11 +61,27 @@ export interface ISeriesStackDataLeaf {
 export type ISeriesStackDataMeta = ISeriesStackDataNode | ISeriesStackDataLeaf;
 export type ISeriesStackData = ISeriesStackDataNode;
 
+/**
+ * 设置图表中系列分组的样式，这里的分组对应了相同的分组字段值
+ */
 export type ISeriesStyle = ISeriesStyleItem[];
+
+/**
+ * 特定系列分组的样式配置
+ */
 export type ISeriesStyleItem = {
+  /**
+   * 系列的分组名称
+   */
   name: string;
 } & {
+  /**
+   * 设置该系列分组下各种图元对应的样式
+   */
   [markName: string]: {
+    /**
+     * 图元的样式
+     */
     style?: any;
   };
 };
diff --git a/packages/vchart/src/series/map/interface.ts b/packages/vchart/src/series/map/interface.ts
index 994c8fee1b..d91dba9d9c 100644
--- a/packages/vchart/src/series/map/interface.ts
+++ b/packages/vchart/src/series/map/interface.ts
@@ -42,7 +42,9 @@ export interface IMapSeriesSpec extends ISeriesSpec, IAnimationSpec<LineMarks, '
    */
   area?: IMarkSpec<Omit<IPathMarkSpec, 'smoothScale'>>;
 
-  /** 默认填充颜色 */
+  /**
+   * 默认填充颜色
+   */
   defaultFillColor?: string;
 
   /**
@@ -57,7 +59,27 @@ export interface IMapSeriesSpec extends ISeriesSpec, IAnimationSpec<LineMarks, '
 }
 
 export interface IMapSeriesTheme {
+  /**
+   * 地图系列默认的填充颜色
+   */
   defaultFillColor?: string;
-  label?: Partial<IMarkTheme<ITextMarkSpec> & { offset?: number; position?: string }>;
+  /**
+   * 地图标签主题样式配置
+   */
+  label?: Partial<
+    IMarkTheme<ITextMarkSpec> & {
+      /**
+       * 标签文字偏移量
+       */
+      offset?: number;
+      /**
+       * 标签位置
+       */
+      position?: string;
+    }
+  >;
+  /**
+   * 地图中色块图元的主题样式配置
+   */
   area?: Partial<IMarkTheme<Omit<IPathMarkSpec, 'smoothScale'>>>;
 }
diff --git a/packages/vchart/src/series/mixin/interface.ts b/packages/vchart/src/series/mixin/interface.ts
index 35748da5f2..8f07669ae6 100644
--- a/packages/vchart/src/series/mixin/interface.ts
+++ b/packages/vchart/src/series/mixin/interface.ts
@@ -4,8 +4,17 @@ import type { IMarkTheme } from '../../typings/spec/common';
 import type { ILineMarkSpec, ISymbolMarkSpec } from '../../typings/visual';
 
 export interface ILineLikeSeriesTheme {
+  /**
+   * 线图元的主题样式配置
+   */
   line?: Partial<IMarkTheme<ILineMarkSpec>>;
+  /**
+   * 点图元的主题样式配置
+   */
   point?: Partial<IMarkTheme<ISymbolMarkSpec>> & { visibleInActive?: boolean };
+  /**
+   * 标签的主题样式配置
+   */
   label?: Partial<ILineLikeLabelSpec>;
 }
 
diff --git a/packages/vchart/src/series/polar/interface.ts b/packages/vchart/src/series/polar/interface.ts
index 284f467aea..ab1142ddfb 100644
--- a/packages/vchart/src/series/polar/interface.ts
+++ b/packages/vchart/src/series/polar/interface.ts
@@ -60,11 +60,24 @@ export interface IPolarSeriesSpec extends ISeriesSpec {
 
 export interface IPolarSeriesTheme {
   /**
+   * 外径
    * @deprecated use outerRadius instead
    */
   radius?: number;
+  /**
+   * 外径，外半径
+   */
   outerRadius?: number;
+  /**
+   * 内径，内半径
+   */
   innerRadius?: number;
+  /**
+   * 起始角度
+   */
   startAngle?: number;
+  /**
+   * 结束角度
+   */
   endAngle?: number;
 }
diff --git a/packages/vchart/src/series/progress/linear/interface.ts b/packages/vchart/src/series/progress/linear/interface.ts
index a9e02e2430..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<string, LinearProgressAppearPreset> {
+    IAnimationSpec<SeriesMarkNameEnum.progress | SeriesMarkNameEnum.track, LinearProgressAppearPreset> {
   type: 'linearProgress';
   /**
    * coordinate: 'cartesian'
@@ -59,7 +59,17 @@ export interface ILinearProgressSeriesSpec
 }
 
 export interface ILinearProgressSeriesTheme {
+  /**
+   * 进度条宽度
+   * 以像素值(px)为单位
+   */
   bandWidth?: number;
+  /**
+   * 进度条样式
+   */
   [SeriesMarkNameEnum.progress]?: Partial<IMarkTheme<IRectMarkSpec>>;
+  /**
+   * 背景条样式
+   */
   [SeriesMarkNameEnum.track]?: Partial<IMarkTheme<IRectMarkSpec>>;
 }
diff --git a/packages/vchart/src/series/radar/interface.ts b/packages/vchart/src/series/radar/interface.ts
index 069438000d..2717f24ad0 100644
--- a/packages/vchart/src/series/radar/interface.ts
+++ b/packages/vchart/src/series/radar/interface.ts
@@ -58,5 +58,8 @@ export interface IRadarSeriesSpec
 }
 
 export interface IRadarSeriesTheme extends IRoseLikeSeriesTheme, ILineLikeSeriesTheme {
+  /**
+   * 面积图元的主题样式配置
+   */
   [SeriesMarkNameEnum.area]?: Partial<IMarkTheme<IAreaMarkSpec>>;
 }
diff --git a/packages/vchart/src/series/scatter/interface.ts b/packages/vchart/src/series/scatter/interface.ts
index 5f9b1bab23..142c82658b 100644
--- a/packages/vchart/src/series/scatter/interface.ts
+++ b/packages/vchart/src/series/scatter/interface.ts
@@ -36,14 +36,28 @@ export interface IScatterSeriesSpec
    */
   [SeriesMarkNameEnum.point]?: IMarkSpec<ISymbolMarkSpec>;
   /**
-   * 尺寸 视觉通道
+   * 尺寸 对应的数据字段。
    */
   sizeField?: string;
+  /**
+   * 设置尺寸的可选值，支持多种格式：
+   * - 单一数值：如 10，则所有点的大小都为 10
+   * - 数组：如 [10, 30]，则根据尺寸数据字段映射到该范围
+   * - 回调函数，自定义根据数据计算尺寸的逻辑
+   * - scale配置，自定义尺寸对应的scale
+   */
   size?: number | number[] | FunctionType<number> | IVisualSpecBase<unknown, number>;
   /**
-   * 形状 视觉通道
+   * 设置形状对应的数据字段
    */
   shapeField?: string;
+  /**
+   * 形状配置，设置形状的可选值
+   * - 单一形状：如 'circle'，则所有点的形状都为 'circle'
+   * - 数组：如 ['circle', 'square']，则根据形状数据字段映射到该范围
+   * - 回调函数，自定义根据数据计算形状的逻辑
+   * - scale配置，自定义形状对应的scale
+   */
   shape?: ShapeType | ShapeType[] | FunctionType<ShapeType> | IVisualSpecBase<unknown, ShapeType>;
   /**
    * 标签配置
@@ -52,7 +66,16 @@ export interface IScatterSeriesSpec
 }
 
 export interface IScatterSeriesTheme extends ICartesianSeriesTheme {
+  /**
+   * 设置默认的尺寸大小，主题中仅支持单一数值
+   */
   size?: number;
+  /**
+   * 设置默认的形状，主题中仅支持单一形状
+   */
   shape?: ShapeType;
+  /**
+   * 设置点图元的主题样式
+   */
   [SeriesMarkNameEnum.point]?: Partial<IMarkTheme<ISymbolMarkSpec>>;
 }
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<string, WordcloudAppearPreset> {
+export interface IWordCloudSeriesBaseSpec
+  extends ISeriesSpec,
+    IAnimationSpec<SeriesMarkNameEnum.word, WordcloudAppearPreset> {
   /**
    * 文本字段
    */
diff --git a/packages/vchart/src/typings/layout.ts b/packages/vchart/src/typings/layout.ts
index e2e3cc10c4..e91c98e7bc 100644
--- a/packages/vchart/src/typings/layout.ts
+++ b/packages/vchart/src/typings/layout.ts
@@ -19,7 +19,16 @@ export interface ILayoutRect {
 
 export type IPercent = `${number}%`;
 
-export type IPercentOffset = { percent?: number; offset?: number };
+export type IPercentOffset = {
+  /**
+   * 百分比值，取值范围为0-1
+   */
+  percent?: number;
+  /**
+   * 偏移量，偏移的像素值
+   */
+  offset?: number;
+};
 
 export type ILayoutPercent = IPercent | number;
 
diff --git a/packages/vchart/src/typings/spec/common.ts b/packages/vchart/src/typings/spec/common.ts
index f56202d3a8..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<Omit<IFillMarkSpec, 'width' | 'height' | 'background'>> & {
-  image?: IRectMarkSpec['background'];
-  cornerRadius?: IRectMarkSpec['cornerRadius'];
-};
-
-export type IBackgroundSpec = IColor | IBackgroundStyleSpec;
+export type IBackgroundSpec = IColor | ConvertToMarkStyleSpec<IGroupMarkSpec>;
 
 /** data */
 export type IDataType = IDataValues | DataView;
@@ -299,7 +294,16 @@ export interface IFieldsMeta {
 }
 
 export interface SheetParseOptions extends CommonParseOptions {
+  /**
+   * 特定类型的数据，支持以下类型：
+   * - csv: 逗号分隔值（Comma-Separated Values，CSV，有时也称为字符分隔值，因为分隔字符也可以不是逗号），其文件以纯文本形式存储表格数据（数字和文本）。
+   * - dsv: 分隔值（Delimiter-Separated Values，DSV，有时也称为字符分隔值，因为分隔字符也可以不是逗号），其文件以纯文本形式存储表格数据（数字和文本）。
+   * - tsv: 制表符分隔值（Tab-Separated Values，TSV，有时也称为字符分隔值，因为分隔字符也可以不是逗号），其文件以纯文本形式存储表格数据（数字和文本）。
+   */
   type: 'csv' | 'dsv' | 'tsv';
+  /**
+   * 具体的解析配置
+   */
   options?: IDsvParserOptions;
 }
 
@@ -342,7 +346,9 @@ export interface IDataValues {
     string,
     IFieldsMeta
   >;
-
+  /**
+   * 数据解析器配置
+   */
   parser?: SheetParseOptions | CommonParseOptions;
 }
 
@@ -481,6 +487,29 @@ export type AdaptiveSpec<T, K extends keyof any> = {
   [key in Exclude<keyof T, K>]: T[key];
 } & { [key in K]: any };
 
+export interface IMarkStateFullSpec<T> extends Record<string, IMarkStateSpec<T> | IMarkStateStyleSpec<T>> {
+  /**
+   * 正常状态下图元的样式设置
+   */
+  normal?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * hover状态下图元的样式设置
+   */
+  hover?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * 没有被hover的状态下图元的样式设置
+   */
+  hover_reverse?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * 选中状态下图元的样式设置
+   */
+  selected?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+  /**
+   * 没有被选中的状态下图元的样式设置
+   */
+  selected_reverse?: IMarkStateSpec<T> | IMarkStateStyleSpec<T>;
+}
+
 /** markSpec */
 export type IMarkSpec<T extends ICommonSpec = ICommonSpec> = {
   /**
@@ -507,14 +536,16 @@ export type IMarkSpec<T extends ICommonSpec = ICommonSpec> = {
   /** 默认样式设置 */
   style?: ConvertToMarkStyleSpec<T>;
   /** 不同状态下的样式配置 */
-  state?: Record<StateValue, IMarkStateSpec<T> | IMarkStateStyleSpec<T>>;
+  state?: IMarkStateFullSpec<T>;
   /**
    * 状态排序方法，默认状态都是按照添加的顺序处理的，如果有特殊的需求，需要指定状态顺序，可以通过这个方法实现
    * @since 1.9.0
    */
   stateSort?: (stateA: string, stateB: string) => number;
 
-  /* 是否是3d视角的mark */
+  /*
+   * 是否是3d视角的mark
+   */
   support3d?: boolean;
   /* customized shape of mark  */
   customShape?: (datum: any[], attrs: any, path: ICustomPath2D) => ICustomPath2D;
@@ -548,6 +579,29 @@ export interface IMarkStateSpec<T> {
 
 export type IMarkStateStyleSpec<T> = ConvertToMarkStyleSpec<T>;
 
+export interface IMarkStateTheme<T> extends Record<string, T> {
+  /**
+   * 图元在正常状态下的主题样式设置
+   */
+  normal?: T;
+  /**
+   * 图元在 hover 状态下的主题样式设置
+   */
+  hover?: T;
+  /**
+   * 图元在 未被hover 状态下的主题样式设置
+   */
+  hover_reverse?: T;
+  /**
+   * 图元在 选中状态下的主题样式设置
+   */
+  selected?: T;
+  /**
+   * 图元在 未被选中 状态下的主题样式设置
+   */
+  selected_reverse?: T;
+}
+
 export type IMarkTheme<T> = {
   /**
    * mark 层 是否显示配置
@@ -556,7 +610,7 @@ export type IMarkTheme<T> = {
   /** 默认样式设置 */
   style?: T;
   /** 不同状态下的样式配置 */
-  state?: Record<StateValue, T>;
+  state?: IMarkStateTheme<T>;
   /**
    * 可交互的开关
    */
@@ -747,7 +801,13 @@ export type ITextFormatMethod<T extends any[]> = (
 
 export type IRichTextFormatMethod<T extends any[]> = (...args: T) =>
   | {
+      /**
+       * 设置文本类型为富文本
+       */
       type: 'rich';
+      /**
+       * 当文本类型为富文本的时候，设置文本的内容
+       */
       text: IRichTextCharacter[];
     }
   | IRichTextCharacter[];
diff --git a/packages/vchart/src/typings/tooltip/line.ts b/packages/vchart/src/typings/tooltip/line.ts
index 7bae76842c..dee5cb6ea4 100644
--- a/packages/vchart/src/typings/tooltip/line.ts
+++ b/packages/vchart/src/typings/tooltip/line.ts
@@ -25,9 +25,13 @@ export interface ITooltipLinePattern extends ITooltipShapePattern, ITooltipLabel
    */
   valueFormatter?: string;
 
-  /** 该行是否可见 */
+  /**
+   * 该行是否可见
+   */
   visible?: TooltipContentProperty<boolean>;
-  /** key 列是否适应内容 */
+  /**
+   * key 列是否适应内容
+   */
   isKeyAdaptive?: TooltipContentProperty<boolean>;
   /**
    * 该行行间距
@@ -39,25 +43,45 @@ export interface ITooltipLinePattern extends ITooltipShapePattern, ITooltipLabel
    * @since 1.9.0
    */
   keyTimeFormat?: string;
+  /**
+   * key值时间格式的模式，支持两种模式：
+   * - utc：表示时间是 UTC 时间
+   * - local：表示时间是本地时间
+   */
   keyTimeFormatMode?: 'utc' | 'local';
   /**
    * 如果配置了该值，则 value 字段的最终值会自动格式化为时间字符串
    * @since 1.9.0
    */
   valueTimeFormat?: string;
+  /**
+   * value值时间格式的模式，支持两种模式：
+   * - utc：表示时间是 UTC 时间
+   * - local：表示时间是本地时间
+   */
   valueTimeFormatMode?: 'utc' | 'local';
 }
 
 export interface ITooltipLineActual extends ITooltipShapeActual, ITooltipLabelActual {
-  /** tooltip key 值内容 */
+  /**
+   * tooltip key 值内容
+   */
   key?: string;
-  /** tooltip value 值内容 */
+  /**
+   * tooltip value 值内容
+   */
   value?: string | TooltipRichTextAttrs;
-
+  /**
+   * tooltip value 的格式化模板
+   */
   valueFormatter?: string;
-  /** 该行是否可见 */
+  /**
+   * 该行是否可见
+   */
   visible?: boolean;
-  /** key 列是否适应内容 */
+  /**
+   * key 列是否适应内容
+   */
   isKeyAdaptive?: boolean;
   /**
    * 该行行间距
@@ -72,6 +96,12 @@ export interface ITooltipLineActual extends ITooltipShapeActual, ITooltipLabelAc
 }
 
 export type TooltipActualTitleContent = {
+  /**
+   * tooltip标题内容
+   */
   title?: ITooltipLineActual;
+  /**
+   * tooltip内容
+   */
   content?: ITooltipLineActual[];
 };
diff --git a/packages/vchart/src/typings/tooltip/shape.ts b/packages/vchart/src/typings/tooltip/shape.ts
index 206c52a2d3..3546d9648e 100644
--- a/packages/vchart/src/typings/tooltip/shape.ts
+++ b/packages/vchart/src/typings/tooltip/shape.ts
@@ -4,7 +4,13 @@ import type { TooltipContentProperty } from './common';
 export interface ITooltipShapePattern {
   /** 该 pattern 属于哪个系列id（用户不需要设置） */
   seriesId?: number;
+  /**
+   * 是否显示形状图形
+   */
   hasShape?: boolean;
+  /**
+   * 形状图形的类型
+   */
   shapeType?: TooltipContentProperty<ShapeType | string>;
   /**
    * 形状填充颜色
@@ -21,16 +27,30 @@ export interface ITooltipShapePattern {
    * @since 1.4.0
    */
   shapeLineWidth?: TooltipContentProperty<number>;
+  /**
+   * 形状的大小
+   */
   shapeSize?: TooltipContentProperty<number>;
-  /** 形状是否空心 */
+  /**
+   * 形状是否空心
+   */
   shapeHollow?: TooltipContentProperty<boolean>;
 
-  /** @deprecated 规范命名，用户 spec 中建议用 shapeFill 代替，内部默认值可以维持使用 shapeColor */
+  /**
+   * 规范命名，用户 spec 中建议用 shapeFill 代替，内部默认值可以维持使用 shapeColor
+   * @deprecated
+   */
   shapeColor?: TooltipContentProperty<string>;
 }
 
 export interface ITooltipShapeActual {
+  /**
+   * 是否显示图形
+   */
   hasShape?: boolean;
+  /**
+   * 图形的类型
+   */
   shapeType?: ShapeType | string;
   /**
    * 形状填充颜色
@@ -47,6 +67,12 @@ export interface ITooltipShapeActual {
    * @since 1.4.0
    */
   shapeLineWidth?: number;
+  /**
+   * 图形的大小
+   */
   shapeSize?: number;
+  /**
+   * 形状是否空心
+   */
   shapeHollow?: boolean;
 }
diff --git a/packages/vchart/src/typings/tooltip/tooltip.ts b/packages/vchart/src/typings/tooltip/tooltip.ts
index cacf64e4d1..f3baddc856 100644
--- a/packages/vchart/src/typings/tooltip/tooltip.ts
+++ b/packages/vchart/src/typings/tooltip/tooltip.ts
@@ -47,9 +47,13 @@ export interface ITooltipPattern extends ITooltipShapePattern {
   /** tooltip content 保留的最大数据行数，默认为 20 */
   maxLineCount?: number;
 
-  /** tooltip content 保留最大数据行数后，代表“其他”的数据行内容 */
+  /**
+   * tooltip content 保留最大数据行数后，代表“其他”的数据行内容
+   */
   othersLine?: ITooltipLineActual;
-  /** 方便内部逻辑辨别 tooltip 类型，不暴露给用户 */
+  /**
+   * 方便内部逻辑辨别 tooltip 类型，不暴露给用户
+   */
   activeType?: TooltipActiveType;
 }
 
diff --git a/packages/vchart/src/typings/visual.ts b/packages/vchart/src/typings/visual.ts
index f27b8e0af9..167214b307 100644
--- a/packages/vchart/src/typings/visual.ts
+++ b/packages/vchart/src/typings/visual.ts
@@ -41,17 +41,32 @@ export interface IVisualSpecBase<D, T> {
 }
 // 用来给用户进行mark.style上的映射配置。所以要配置数据维度
 export interface IVisualSpecStyle<D, T> extends IVisualSpecBase<D, T> {
+  /**
+   * 指定映射对应的数据字段
+   */
   field?: string;
 }
 
 export type IDataDomainSpec = {
+  /**
+   * 数据的id
+   */
   dataId: string;
+  /**
+   * 数据字段
+   */
   fields: string[];
 };
 
 // 用来提供给用户进行 scale 配置 所以名字是必选的 对用户配置
 export interface IVisualSpecScale<D, T> extends Omit<IVisualSpecBase<D, T>, 'domain'> {
+  /**
+   * scale 的id
+   */
   id: string;
+  /**
+   * 定义域范围
+   */
   domain:
     | IVisualSpecBase<D, T>['domain']
     // 使用数据的字段值，如果 scale 是连续的，就取区间，如果是离散的就使用 values 。
@@ -266,9 +281,9 @@ export interface ICommonSpec {
    */
   innerBorder?: IBorder;
   /**
+   * html 浮层，会将配置的html相关内容，绝对定位到图元的位置
    * @experimental
    * @since 1.10.0
-   * html 浮层
    */
   html?: IMarkHtmlSpec;
 
@@ -327,7 +342,13 @@ export interface ISymbolMarkSpec extends IFillMarkSpec {
 
 // lineMark 和 areaMark 共同配置
 export interface ILineLikeMarkSpec extends IFillMarkSpec {
+  /**
+   * 取消的差值类型，默认为线性插值，也就是普通的折线
+   */
   curveType?: InterpolateType;
+  /**
+   * 设置点是否有效，也就是是否合法
+   */
   defined?: boolean;
 }
 
@@ -526,11 +547,25 @@ export interface IBoxPlotMarkSpec extends ICommonSpec {
    * 中轴线透明度，仅当shaftType=bar时生效
    */
   shaftFillOpacity?: number;
-
+  /**
+   * 最小值
+   */
   min?: (datum: Datum) => number;
+  /**
+   * 25%分位数
+   */
   q1?: (datum: Datum) => number;
+  /**
+   * 中位数
+   */
   median?: (datum: Datum) => number;
+  /**
+   * 75%分位数
+   */
   q3?: (datum: Datum) => number;
+  /**
+   * 最大值
+   */
   max?: (datum: Datum) => number;
 }
 
@@ -554,6 +589,9 @@ export interface ILiquidMarkSpec extends ICommonSpec {
 }
 
 export interface ILiquidOutlineSpec extends ISymbolMarkSpec {
+  /**
+   * 描边的宽度
+   */
   lineWidth: number;
 }
 
@@ -571,26 +609,68 @@ export interface IOutlierMarkSpec {
 export interface IPathMarkSpec extends IFillMarkSpec {
   path?: string;
   // TODO: 该属性后续可能会删除，未定
-  // 平滑缩放，不然会发生跳变，在地图交互场景需要配置为true；常规path缩放不需要
+  /**
+   * 平滑缩放，不然会发生跳变，在地图交互场景需要配置为true；常规path缩放不需要
+   */
   smoothScale?: boolean;
 }
 
 export interface ILinkPathMarkSpec extends IFillMarkSpec {
+  /**
+   * 连边起点的x坐标
+   */
   x0?: number;
+  /**
+   * 连边起点的y坐标
+   */
   y0?: number;
+  /**
+   * 连边终点的x坐标
+   */
   x1?: number;
+  /**
+   * 连边终点的y坐标
+   */
   y1?: number;
+  /**
+   * 连边的厚度，也可以理解为宽度
+   */
   thickness?: number;
+  /**
+   * 连边的曲度，决定了连边的弯曲程度，取值范围为0-1，
+   * 0表示不弯曲，也就是直线
+   * 1表示最大的弯曲度，
+   * 默认值为0.5
+   */
   curvature?: number;
   /** round all the coordinates */
   round?: boolean;
   /** the ratio of normal style path */
   ratio?: number;
+  /**
+   * 对齐方式
+   */
   align?: 'start' | 'end' | 'center';
+  /**
+   * 连边的类型
+   *
+   */
   pathType?: 'line' | 'smooth' | 'polyline';
+  /**
+   * 是否展示终点的箭头
+   */
   endArrow?: boolean;
+  /**
+   * 是否展示起点的箭头
+   */
   startArrow?: boolean;
+  /**
+   * 背景线的样式，主要用于部分高亮的场景
+   */
   backgroundStyle?: any;
+  /**
+   * 连边的方向
+   */
   direction?: 'horizontal' | 'vertical' | 'LR' | 'RL' | 'TB' | 'BL' | 'radial';
 }
 
@@ -625,17 +705,25 @@ export interface IArcMarkSpec extends IFillMarkSpec {
    * 圆角
    */
   cornerRadius?: number;
-  /* 内边距 */
+  /**
+   * 内边距
+   */
   innerPadding?: number;
-  /* 外边距 */
+  /**
+   * 外边距
+   */
   outerPadding?: number;
-
-  /** arc的中心点偏移距离 */
+  /**
+   * arc的中心点偏移距离，一般是通过在交互状态下设置这个属性来实现将扇区移出中心的一个效果
+   */
   centerOffset?: number;
-
-  /** arc 的 roundCap 属性，即圆角是否伸出 startAngle 和 endAngle 之外 */
+  /**
+   * arc 的 roundCap 属性，即圆角是否伸出 startAngle 和 endAngle 之外
+   */
   cap?: boolean | [boolean, boolean];
-  /** arc 在 roundCap 打开且应用环形渐变时是否对 cap 部分生效 */
+  /**
+   * arc 在 roundCap 打开且应用环形渐变时是否对 cap 部分生效
+   */
   autoCapConical?: boolean;
 }
 
@@ -695,7 +783,9 @@ export interface IPolygonMarkSpec extends ICommonSpec, IFillMarkSpec {
 }
 
 export interface IPyramid3dMarkSpec extends IPolygonMarkSpec {
-  // 只能有4个顶点
+  /**
+   * 3d金字塔顶点坐标，注意只能有4个顶点
+   */
   points?: IPoint[];
 }
 
@@ -711,36 +801,105 @@ export type ImageOriginType = 'top' | 'bottom';
  */
 export type GradientPropValue<T> = ValueType<T> | FunctionType<T>;
 export type GradientStop = {
+  /**
+   * 渐变色的偏移量，0-1的值
+   */
   offset: GradientPropValue<number>;
+  /**
+   * 渐变色的颜色
+   */
   color?: GradientPropValue<string>;
+  /**
+   * 渐变色的透明度
+   */
   opacity?: number;
 };
 export interface IGradientLinear {
+  /**
+   * 渐变色的起点x坐标，0-1的值，相对于图形包围盒x方向取值的比例值
+   */
   x0?: GradientPropValue<number>;
+  /**
+   * 渐变色的起点y坐标，0-1的值，相对于图形包围盒y方向取值的比例值
+   */
   y0?: GradientPropValue<number>;
+  /**
+   * 渐变色的终点x坐标，0-1的值，相对于图形包围盒x方向取值的比例值
+   */
   x1?: GradientPropValue<number>;
+  /**
+   * 渐变色的终点y坐标，0-1的值，相对于图形包围盒y方向取值的比例值
+   */
   y1?: GradientPropValue<number>;
+  /**
+   * 渐变色的颜色
+   */
   stops: GradientStop[];
+  /**
+   * 渐变色的类型设置为 'linear'，即线形渐变
+   */
   gradient: 'linear';
 }
 
 export interface IGradientRadial {
+  /**
+   * 径向渐变的起点的半径
+   */
   r0?: GradientPropValue<number>;
+  /**
+   * 径向渐变的起点的x坐标
+   */
   x0?: GradientPropValue<number>;
+  /**
+   * 径向渐变的起点的y坐标
+   */
   y0?: GradientPropValue<number>;
+  /**
+   * 径向渐变的终点的x坐标
+   */
   x1?: GradientPropValue<number>;
+  /**
+   * 径向渐变的终点的y坐标
+   */
   y1?: GradientPropValue<number>;
+  /**
+   * 径向渐变的终点的半径
+   */
   r1?: GradientPropValue<number>;
+  /**
+   * 渐变色的颜色
+   */
   stops: GradientStop[];
+  /**
+   * 渐变色的类型设置为 'radial'，即径向渐变
+   */
   gradient: 'radial';
 }
 
 export interface IGradientConical {
+  /**
+   * 锥形渐变的中心点x坐标
+   */
   x?: GradientPropValue<number>;
+  /**
+   * 锥形渐变的中心点y坐标
+   */
   y?: GradientPropValue<number>;
+  /**
+   * 锥形渐变的开始角度
+   */
   startAngle?: GradientPropValue<number>;
+  /**
+   * 锥形渐变的结束角度
+   */
   endAngle?: GradientPropValue<number>;
+  /**
+   * 锥形渐变的颜色
+   */
   stops: GradientStop[];
+  /**
+   * 渐变色的类型设置为 'conical'，即锥形渐变
+   */
   gradient: 'conical';
 }
 
@@ -773,10 +932,28 @@ export interface IImageMarkSpec extends IFillMarkSpec {
    * 2. 如果传入数组，则分别为 [上左, 上右, 下右, 下左]
    */
   cornerRadius?: number | number[];
+  /**
+   * 图片的宽度
+   */
   width?: number;
+  /**
+   * 图片的高度
+   */
   height?: number;
+  /**
+   * 当图片的宽度小于 width 时，图片的重复方式
+   */
   repeatX?: IRepeatType;
+  /**
+   * 当图片的高度小于 height 时，图片的重复方式
+   */
   repeatY?: IRepeatType;
+  /**
+   * 设置图片的内容，支持三种类型：
+   * 1. string类型，可以是图片资源的路径或者是svg 标签字符串
+   * 2. image 元素
+   * 3. canvas 元素
+   */
   image: string | HTMLImageElement | HTMLCanvasElement;
 }