运行时 API 与开发实现说明

4.1 `IVisualUpdateOptions`：运行时更新载荷

interface IFilterTarget {
    column: string;
}

enum VisualFilterType {
    Basic = 'basic',
    Advanced = 'advanced',
    Tuple = 'tuple',
}

interface IFilterBase {
    target: IFilterTarget;
    filterType: VisualFilterType;
}

enum BasicFilterOperator {
    In = 'In',
    NotIn = 'NotIn',
}

interface IBasicFilter extends IFilterBase {
    operator: BasicFilterOperator;
    values: any[];
}

enum AdvancedFilterOperator {
    LessThan = 'LessThan',
    LessThanOrEqual = 'LessThanOrEqual',
    GreaterThan = 'GreaterThan',
    GreaterThanOrEqual = 'GreaterThanOrEqual',
    Contains = 'Contains',
    DoesNotContain = 'DoesNotContain',
    StartWith = 'StartWith',
    DoesNotStartWith = 'DoesNotStartWith',
    EndWith = 'EndWith',
    DoesNotEndWith = 'DoesNotEndWith',
    Is = 'Is',
    IsNot = 'IsNot',
}

interface IAdvancedFilterCondition {
    value: any;
    operator: AdvancedFilterOperator;
    caseSensitive?: boolean;
}

enum AdvancedFilterLogicalOperator {
    And = 'And',
    Or = 'Or',
}

interface IAdvancedFilter extends IFilterBase {
    conditions: IAdvancedFilterCondition[];
    logicalOperator: AdvancedFilterLogicalOperator;
}

type ITuple = { value: any }[];

interface ITupleFilter {
    target: IFilterTarget[];
    filterType: VisualFilterType;
    operator: BasicFilterOperator;
    values: ITuple[];
}

type IFilter = IBasicFilter | IAdvancedFilter | ITupleFilter;

interface IParameterPair {
    name: string;
    value: any[];
}

interface IWatchedParameter {
    meta: {
        name: string;
        display: string;
        dataType: string;
        type: string;
        multiValue: boolean;
    };
    value: any[];
}

interface IVisualUpdateOptions {
    isViewer: boolean;
    isMobile: boolean;
    isEditing: boolean;
    isFocus: boolean;
    dataViews: any;
    updateType: string;
    properties: any;
    language: string;
    scale: number;
    filters: IFilter[];
    watchedParameters?: {
        [key: string]: IWatchedParameter;
    };
    viewport: {
        width: number;
        height: number;
        scale: number;
    };
}

4.1.1 关键字段说明

字段	说明
`isViewer`	是否处于预览/查看状态
`isMobile`	是否移动端
`isEditing`	是否处于编辑状态
`isFocus`	是否处于聚焦状态
`dataViews`	根据数据绑定规则生成的数据视图
`updateType`	本次更新类型
`properties`	属性面板中定义的属性值
`language`	当前语言
`scale`	缩放因子
`filters`	当前过滤器集合
`watchedParameters`	当前监听到的参数值
`viewport`	当前视口尺寸

4.2 `WynVisual`：插件基类

declare class WynVisual {
  static Models = {
    Filter: {
      BasicFilter, AdvancedFilter, TupleFilter,
    },
  };
  static Enums = {
    FilterType,
    BasicFilterOperator,
    AdvancedFilterOperator,
    AdvancedFilterLogicalOperator,
    UpdateType
  };
  constructor(dom: HTMLDivElement, host: VisualHost, updateOptions: IVisualUpdateOptions);
  update(options: IVisualUpdateOptions): void;
  getInspectorHiddenState(updateOptions: IVisualUpdateOptions): string[];
  getActionBarHiddenState(updateOptions: IVisualUpdateOptions): string[];
  getColorAssignmentConfigMapping(dataViews: IDataView[]): IColorAssignmentConfigMapping;
  onResize(): void;
  onDestroy(): void;
}

4.2.1 生命周期说明

方法	作用
`constructor`	初始化 DOM、宿主对象、第三方实例
`update`	数据或属性变化时重新消费数据并渲染
`getInspectorHiddenState`	动态隐藏属性面板字段
`getActionBarHiddenState`	动态隐藏动作栏项
`getColorAssignmentConfigMapping`	定义颜色映射配置
`onResize`	容器尺寸变化时重新布局
`onDestroy`	销毁实例、监听器、定时器等资源

4.3 推荐的实现模式

4.3.1 初始化阶段

在构造函数中完成：

DOM 容器初始化
选择管理器初始化
第三方图表实例初始化
事件监听注册

4.3.2 更新阶段

在 update(options) 中完成：

读取 dataViews
读取 properties
读取 filters 与 watchedParameters
将 Wyn 数据结构转换为第三方图表结构
更新 UI 与交互状态

4.3.3 尺寸变化阶段

在 onResize() 中完成：

图表 resize
布局重算
画布或容器尺寸同步

4.3.4 销毁阶段

在 onDestroy() 中完成：

销毁图表实例
解除事件监听
清理定时器
释放第三方资源

4.4 Color Assignment：颜色分配机制

原始资料给出的使用方式如下：

在 capabilities.json 中增加 ColorAssignment 属性
在 visual.ts 中实现 getColorAssignmentConfigMapping
在渲染逻辑中消费 options.mainColorAssignment

典型适用场景：

分类颜色一致性控制
系列颜色映射
同一业务维度在多个图表间保持统一颜色

4.5 SelectionId 与 SelectionManager

4.5.1 SelectionId

SelectionId 类似一个“绑定了维度和度量的选择向量”，常用于：

数据点点击
交叉筛选
Tooltip 字段展示
保留/排除
钻取/跳转

常用方法：

withMeasure(profile: IFieldProfile, dataPoint?: IDataPoint): SelectionId
withDimension(profile: IFieldProfile, dataPoint: IDataPoint): SelectionId

4.5.2 SelectionManager

常用方法：

setSelectionIds(ids: SelectionId[]): void
getSelectionIds(): SelectionId[]
getCount(): number
select(id: SelectionId | SelectionId[], multiSelect?: boolean): Promise<void>
clear(id?: SelectionId): Promise<void>
registerOnSelectCallback(fn: (ids: SelectionId[]) => void): void
contains(id: SelectionId): boolean
isEmpty(): boolean

常见用途：

处理单选/多选
控制图形高亮状态
触发交叉筛选
在 tooltip 或上下文菜单中传递当前选择

4.6 VisualHost 服务清单

4.6.1 `eventService`

作用：通知宿主当前插件渲染状态，并接收自定义动作事件。

常用方法：

renderStart()
renderError()
renderFinish()
registerOnCustomEventCallback(fn)

4.6.2 `localizationManager`

作用：获取国际化字符串。

常用方法：

getDisplay(displayNameKey: string): string

4.6.3 `toolTipService`

作用：控制提示框显示与移动。

常用接口：

interface ITooltipConfig {
    position: { x: number; y: number; };
    title?: string;
    fields?: { label: string; value: string; }[];
    selectionId?: SelectionId;
    selected?: SelectionId[];
    menu?: boolean;
}

常用方法：

show(config)
hide()
move(pos)

4.6.4 `propertyService`

作用：动态更新 options.visual 中定义的属性。

常用方法：

setProperty(propertyName: string, value: any): void

4.6.5 `formatService`

作用：处理格式化与显示单位。

常用方法：

isAutoDisplayUnit(displayUnit)
getAutoDisplayUnit(values)
format(format, value)

4.6.6 `selectionService`

作用：创建选择管理器与选择对象。

常用方法：

createSelectionManager()
createSelectionId()

4.6.7 `configurationManager`

作用：读取 visual.json 中定义的 configuration 参数。

常用方法：

get(key: string): string

4.6.8 `assetsManager`

作用：读取 visual.json 中打包的图片资源。

常用方法：

getImage(imageName: string): string

4.6.9 `commandService`

作用：执行宿主命令。

常见命令包括：

SwitchTab
SwitchPage
Keep
Exclude
Drill
Jump
ShowScenario
HideScenario
ToggleScenario

4.6.10 `filterService`

作用：把过滤器派发给其他场景。

前提：

需要在 options.common.filter 中启用过滤能力

常用方法：

applyFilter(filter)
clean()

4.6.11 `contextMenuService`

作用：显示或隐藏上下文菜单。

常用方法：

show({ position })
hide()

4.6.12 `moduleManager`

作用：获取 Wyn 已支持的模块。

文档中明确提到支持的模块示例：

echarts
lodash
html2canvas

常用方法：

getModule(name: string): any

4.6.13 `parameterService`

作用：设置仪表板静态参数值。

常用方法：

setParameter(pairs: IParameterPair | IParameterPair[]): void

4.7 三类过滤器说明

4.7.1 BasicFilter

适用于单字段过滤，类似：

SELECT * FROM table WHERE Dept IN ('DTD1', 'DTD2')

常用能力：

setOperator/getOperator
setValues/getValues
toJSON/fromJSON
contains
add/remove
isEmpty

4.7.2 TupleFilter

适用于多维组合过滤，类似：

SELECT * FROM table
WHERE (Team = 'DTD1' AND Prod = 'Wyn')
   OR (Team = 'DTD2' AND Prod = 'SpreadJS')

适合场景：

多个维度共同决定一个过滤条件
图上点击某个复合节点或组合标签

4.7.3 AdvancedFilter

适用于范围与文本高级条件过滤，支持运算符如：

LessThan
GreaterThan
Contains
StartWith
EndWith
Is
IsNot

4.8 一个典型的实现心智模型

建议按下面顺序理解或开发一个 Wyn 插件：

先读 capabilities.json，明确数据、属性、动作、分析能力
再读 update(options)，明确数据与属性如何被消费
再看交互逻辑，理解筛选、联动、点击、提示框与动作栏
最后看 onResize 与 onDestroy，确认生命周期是否完整

4.9 ECharts 开发示例的落地流程

原始示例文档给出的开发流程可以抽象为：

运行 wyn-visual-tools init 初始化工程
安装 echarts 及类型依赖
在构造函数中创建图表实例
先实现 mock chart
在 capabilities.json 中补充数据绑定
在 update 中把 dataViews 转为 ECharts 数据结构
在 onResize 中处理自适应
补充自定义属性并在 render 中消费
增加标题和交互支持
增加 focus、filter、rank 等 action
在 onDestroy 中销毁实例
最终打包为 .viz 上传系统

运行时 API 与开发实现说明

4.1 IVisualUpdateOptions：运行时更新载荷

4.1.1 关键字段说明

4.2 WynVisual：插件基类

4.2.1 生命周期说明

4.3 推荐的实现模式

4.3.1 初始化阶段

4.3.2 更新阶段

4.3.3 尺寸变化阶段

4.3.4 销毁阶段

4.4 Color Assignment：颜色分配机制

4.5 SelectionId 与 SelectionManager

4.5.1 SelectionId

4.5.2 SelectionManager

4.6 VisualHost 服务清单

4.6.1 eventService

4.6.2 localizationManager

4.6.3 toolTipService

4.6.4 propertyService

4.6.5 formatService

4.6.6 selectionService

4.6.7 configurationManager

4.6.8 assetsManager

4.6.9 commandService

4.6.10 filterService

4.6.11 contextMenuService

4.6.12 moduleManager

4.6.13 parameterService

4.7 三类过滤器说明

4.7.1 BasicFilter

4.7.2 TupleFilter

4.7.3 AdvancedFilter

4.8 一个典型的实现心智模型

4.9 ECharts 开发示例的落地流程

4.1 `IVisualUpdateOptions`：运行时更新载荷

4.2 `WynVisual`：插件基类

4.6.1 `eventService`

4.6.2 `localizationManager`

4.6.3 `toolTipService`

4.6.4 `propertyService`

4.6.5 `formatService`

4.6.6 `selectionService`

4.6.7 `configurationManager`

4.6.8 `assetsManager`

4.6.9 `commandService`

4.6.10 `filterService`

4.6.11 `contextMenuService`

4.6.12 `moduleManager`

4.6.13 `parameterService`