能力声明模型与接口说明

3.1 总览：能力声明的四大块

capabilities.json 的核心由四部分组成：

dataBinding：定义数据入口
options：定义属性入口
actions：定义操作入口
analysis：定义分析入口

一个设计清晰的插件，通常具备以下闭环：

用户绑定数据
用户配置属性
用户执行动作
插件参与筛选、钻取、导出、联动等分析过程

3.2 Data Binding：数据绑定接口

3.2.1 顶层接口

interface IDataBinding {
    dataRoles: Array<IDataRole | IDataRolesCollection>;
    templates?: IDataRoleTemplate[];
    dataViewMappings?: IDataViewMappingConfig[];
    conditions?: IDataRoleConditions;
    conversionRules?: IConversionRules;
}

interface IOption extends IIconable, ILocalizable {
    name: string;
    type: DataRoleOptionType | DataRoleTemplateOptionType;
    defaultValue?: any;
}

interface IItemOption extends IIconable, ILocalizable {
    name: string;
    type: DataRoleItemOptionType;
    defaultValue?: any;
}

3.2.2 Data Role 定义

enum DataRoleOptionType {
    Enum = 'enum',
    Format = 'format',
    DisplayUnit = 'displayUnit',
}

enum DataRoleItemOptionType {
    Enum = 'enum',
    Format = 'format',
    DisplayUnit = 'displayUnit',
    RenderSetting = 'renderSetting',
}

export enum DataRoleType {
    Value = 'value',
    Grouping = 'grouping',
    GroupingOrValue = 'groupingOrValue',
    Attribute = 'attribute',
    AttributeOrValue = 'attributeOrValue',
}

enum DatasetFieldDataType {
    date = 'date',
    datetime = 'datetime',
    number = 'number',
    string = 'string',
    boolean = 'boolean',
}

interface IDataRole extends ILocalizable {
    name: DataRoleName;
    aliasName: DataRoleName;
    kind: DataRoleType;
    options: IOption[];
    itemOptions: IItemOption[];
    hidden?: boolean;
    acceptedTypes?: DatasetFieldDataType[];
    preferredKind?: DataRoleType;
}

3.2.3 `dataRoles` 关键字段说明

字段	说明
`name`	数据角色名称
`aliasName`	切换图表类型时用于识别等价角色
`kind`	角色类型
`options`	针对整个 role 的配置项
`itemOptions`	针对 role 内单个字段的配置项
`hidden`	是否在面板隐藏，但仍可参与映射
`acceptedTypes`	限定允许绑定的数据类型
`preferredKind`	对 `groupingOrValue` / `attributeOrValue` 指定优先语义

3.2.4 常见 `kind` 类型

类型	含义
`grouping`	分组/维度字段
`value`	度量值字段
`groupingOrValue`	可做分组也可做度量
`attribute`	分组后取第一个值
`attributeOrValue`	既可做属性也可做值

3.2.5 `IDataRolesCollection` 与模板集合

interface IDataRolesCollection extends ILocalizable {
    kind: DataRoleType.DataRoleCollection;
    groups?: TemplateName[];
    collapsible?: boolean;
    editable?: boolean;
}

interface IDataRoleTemplate extends ILocalizable, IIconable {
    name: TemplateName;
    dataRoles?: IDataRole[];
    dataViewMappings: IDataViewMappingConfig[];
    conditions?: IDataRoleConditions;
    options?: IOption[];
}

适用场景：

KPI 矩阵
多值组集合
复杂模板型可视化

当插件需要支持“动态增加分组模板”时，通常会使用 templates + collection 组合。

3.3 Data View Mapping：数据视图映射

3.3.1 基础接口

interface IDataViewMapping {
    required?: IDataRoleConditions;
}

interface IDataView {
    single: ISingleDataView;
    plain: IPlainDataView;
    matrix: IMatrixDataView;
}

interface IDataRoleProfile {
    options: any;
    values: IPivotSettingProfile[];
}

interface IPivotSettingProfile {
    display: string;
    name: string;
    method?: AggMethod;
    dataType: DataType;
    format: string;
}

3.3.2 Single Data View

interface ISingleDataViewMapping extends IDataViewMapping {
    value: DataRoleName;
}

interface ISingleDataView {
    value: number;
    profile: { [key: string]: IDataRoleProfile };
    options: any;
}

适用场景：

KPI
单值卡片
动态数字

3.3.3 Plain Data View

interface IPlainDataViewMapping extends IDataViewMapping {
    dataRoles: DataRoleName[];
    series?: DataRoleName;
    trellisRows?: DataRoleName;
    trellisColumns?: DataRoleName;
}

interface IPlainDataView {
    data: any[];
    profile: { [dataRoleName: string]: IDataRoleProfile };
    sort: {
        [columnDisplay: string]: {
            order: any[];
            priority: -1 | 0 | 1;
        }
    };
    options: any;
}

适用场景：

大多数图表
列表型展示
交互型控件

3.3.4 Matrix Data View

interface IMatrixDataViewMapping extends IDataViewMapping {
    values: DataRoleName[];
    rows: DataRoleName[];
    columns: DataRoleName[];
}

适用场景：

交叉表
透视型图表
热力图、矩阵图

3.4 Conditions：绑定数量约束

interface IDataRoleCondition {
    [dataRoleName: string]: {
        max?: number;
        min?: number;
    };
}

说明：

conditions 之间是“或”关系
每个 condition 内部各 role 之间是“且”关系

典型作用：

限制某角色最少绑定几个字段
当 series 存在时，把 values 限制为最多 1 个
控制某个可视化的合法绑定模式

3.5 Conversion Rules：图表转换规则

enum ConversionCommand {
    All = 'all',
    First = 'first',
    Last = 'last',
}

enum ConversionPhase {
    Pre = 'pre',
    Post = 'post'
}

interface IConversionRulesDetail {
    mode: ConversionPhase;
    conditions?: Array<IDataRoleCondition>;
    execute: Array<{
        source: DataRoleName;
        target: DataRoleName;
        cmd: ConversionCommand;
    }>;
}

interface IConversionRules {
    in?: Array<IConversionRulesDetail>;
    out?: Array<IConversionRulesDetail>;
}

主要用途：

图表类型切换时的数据角色迁移
从源插件迁移字段到目标插件
在默认转换规则前后追加自定义规则

常见命令含义：

All：全部迁移
First：迁移第一个字段
Last：迁移最后一个字段

3.6 Options：属性面板接口

3.6.1 顶层接口

interface IOptions {
    common?: {
        size?: ISize;
        margin?: IPosition;
        filter?: boolean;
    };
    visual?: IVisualCategory[];
}

3.6.2 继承与类型枚举

enum InheritProperty {
    Palette = 'dashboard.palette',
    TextStyle = 'dashboard.textStyle',
    TitleTextStyle = 'dashboard.titleTextStyle',
    BackgroundColor = 'dashboard.backgroundColor',
}

enum PublicPropertyType {
    Text = 'Text',
    Integer = 'Integer',
    Float = 'Float',
    Boolean = 'Boolean',
    LongText = 'LongText',
    Enum = 'Enum',
    Color = 'Color',
    Percentage = 'Percentage',
    Format = 'Format',
    DisplayUnit = 'DisplayUnit',
    Angle = 'Angle',
    Palette = 'Palette',
    TextStyle = 'TextStyle',
    Position = 'Position',
    Image = 'Image',
    Hidden = 'Hidden',
    ColorAssignment = 'ColorAssignment',
    Collection = 'Collection'
}

enum CategoryType {
    Title = 'title',
    Appearance = 'appearance',
    Custom = 'custom',
    Interaction = 'interaction',
}

3.6.3 分类与属性接口

interface IVisualCategory extends ILocalizable {
    type?: CategoryType;
    properties?: IVisualProperty[];
}

interface IProperty {
    name: string;
    inheritFrom?: InheritProperty;
    defaultValue?: any;
    structuredPath?: string;
}

interface IVisualProperty extends IProperty {
    type?: PublicPropertyType;
    hidden?: boolean;
}

3.6.4 分类说明

分类	说明
`title`	控制标题开关、对齐方式等
`appearance`	控制背景、边框、阴影、边距、填充等
`interaction`	控制交叉筛选、跳转、参数监听、隐藏动作等
`custom`	自定义业务属性

3.6.5 常见属性类型

类型	用途
`Text`	文本输入
`Integer`	整数输入
`Float`	浮点输入
`Boolean`	开关
`LongText`	多行文本
`Enum`	下拉选择
`Color`	颜色选择
`Percentage`	百分比滑块
`Format`	格式编辑
`DisplayUnit`	显示单位
`Angle`	角度滑块
`Palette`	调色板
`TextStyle`	字体、字号、颜色
`Position`	位置/边距
`Image`	图片
`Hidden`	隐藏属性，不在面板展示
`ColorAssignment`	颜色映射属性
`Collection`	集合型复杂属性
`ClickAction`	点击行为配置

3.6.6 关键字段说明

字段	说明
`inheritFrom`	继承仪表板属性或同级属性
`defaultValue`	默认值
`structuredPath`	嵌套路径，如 `a.b.c`
`hidden`	不在属性面板展示，但可在代码中读写

3.6.7 ColorAssignment 属性

interface IColorAssignmentProperty extends IVisualProperty {
    alias?: string;
    palettePath?: string;
}

使用要求：

在 capabilities.json 中声明 ColorAssignment
在 visual.ts 中实现 getColorAssignmentConfigMapping

3.6.8 Collection 属性

Collection 用于定义列表型复杂配置，例如阈值区间、颜色规则、分段区间等。

enum ItemType {
    Text = 'Text',
    Integer = 'Integer',
    Float = 'Float',
    Boolean = 'Boolean',
    LongText = 'LongText',
    Enum = 'Enum',
    Color = 'Color',
    Percentage = 'Percentage',
    Format = 'Format',
    DisplayUnit = 'DisplayUnit',
    Slider = 'Slider',
    Image = 'Image',
}

interface IItemProperty {
    name?: string;
    displayName?: string;
    displayNameKey?: string;
    defaultValue?: any;
    type: ItemType;
}

interface ICollectionProperty extends IVisualProperty {
    itemShape: IItemProperty | IItemProperty[];
    defaultValue?: any[];
}

3.6.9 ClickAction 属性

enum InteractionMouseEventAction {
    ShowTooltip = 'showTooltip',
    None = 'none',
    Keep = 'keep',
    Exclude = 'exclude',
    DrillTo = 'drillTo',
    JumpTo = 'jumpTo',
    AddMonitor = 'addMonitor',
}

interface IClickActionProperty extends IVisualProperty {
    disableActions?: Array<InteractionMouseEventAction>;
}

3.7 Actions：动作栏接口

3.7.1 顶层接口

interface IAction extends IMember {
    type: ActionType;
}

3.7.2 常见动作类型总览

动作	作用	设计态	运行态
`filter`	数据过滤	是	是
`sort`	排序	是	是
`rank`	排名	是	是
`convertVisual`	转换图表类型或调整绑定	是	是
`edit`	编辑	是	否
`focus`	聚焦	是	是
`showData`	聚焦态显示数据透视表	是	否
`export`	导出 PNG / Excel	否	是
`annotation`	批注	是	否
`extension`	把常用属性映射到动作栏	是	是
`event`	自定义事件按钮	是	是
`shareScenario`	共享场景	是	否
`openFullDashboard`	打开完整仪表板	是	否
`clearSelection`	清除选择	否	是
`analysisPath`	记录分析路径	否	是
`saveAsTemplate`	保存为模板	是	否

3.7.3 重要动作接口

`convertVisual`

interface IConvertVisualAction extends IAction {
    disableChangePivotSetting?: boolean;
    disableChangeChartType?: boolean;
}

`showData`

interface IShowDataAction extends IAction {
    disableCustomData?: boolean;
    rule: IConversionRules;
}

`export`

interface IExportAction extends IAction {
    disablePNG?: boolean;
    disableExcel?: boolean;
}

`extension`

enum ExtensionType {
    Toggle = 'toggle',
    Enum = 'enum',
    ReferenceLine = '_referenceLine',
    TrendLine = '_trendLine',
    ImagePicker = '_imagePicker',
    ConditionalFormat = '_conditionalFormat',
}

interface IExtensionAction extends IAction {
    path: string;
    extensionType: ExtensionType;
    horizontal?: boolean;
}

interface IToggleExtension extends IExtensionAction {
    toggleState?: Array<ILocalizable & IIconable>;
}

interface IEnumExtension extends IExtensionAction {
    items: IEnumItem[];
}

说明：

extension 允许把属性面板中的属性直接映射到动作栏
path 必须指向对应属性名称
适合暴露高频属性，例如开关、枚举、参考线、条件格式等

`event`

interface IEventAction extends IAction {
    horizontal?: boolean;
}

说明：

定义自定义动作按钮
点击后可通过 eventService.registerOnCustomEventCallback 接收事件

3.7.4 动作声明与代码实现的关系

需要特别注意：

在 capabilities.json 中声明动作，不代表业务逻辑已自动生效
例如开启 sort 后，插件仍需在消费 dataView.sort 时自行排序
开启 event 后，仍需在 visual.ts 中注册回调
开启 extension 后，仍需在代码中读取对应属性并响应变化

3.8 Analysis：分析能力接口

目前文档重点介绍的是 drill。

interface IDrillAction extends IAction {
    rule: IDrillRule;
}

interface IDrillRule {
    roles: string[];
    type?: DrillDownType;
}

enum DrillDownType {
    Default = 'all',
    List = 'list',
    Path = 'path',
}

字段说明：

roles：定义钻取时使用哪些 data role
type：默认钻取模式
- all：全部维度
- list：部分维度
- path：固定路径

这意味着插件不只是“画图”，还可以成为 Wyn 分析链路中的一个节点。

能力声明模型与接口说明

3.1 总览：能力声明的四大块

3.2 Data Binding：数据绑定接口

3.2.1 顶层接口

3.2.2 Data Role 定义

3.2.3 dataRoles 关键字段说明

3.2.4 常见 kind 类型

3.2.5 IDataRolesCollection 与模板集合

3.3 Data View Mapping：数据视图映射

3.3.1 基础接口

3.3.2 Single Data View

3.3.3 Plain Data View

3.3.4 Matrix Data View

3.4 Conditions：绑定数量约束

3.5 Conversion Rules：图表转换规则

3.6 Options：属性面板接口

3.6.1 顶层接口

3.6.2 继承与类型枚举

3.6.3 分类与属性接口

3.6.4 分类说明

3.6.5 常见属性类型

3.6.6 关键字段说明

3.6.7 ColorAssignment 属性

3.6.8 Collection 属性

3.6.9 ClickAction 属性

3.7 Actions：动作栏接口

3.7.1 顶层接口

3.7.2 常见动作类型总览

3.7.3 重要动作接口

convertVisual

showData

export

extension

event

3.7.4 动作声明与代码实现的关系

3.8 Analysis：分析能力接口

3.2.3 `dataRoles` 关键字段说明

3.2.4 常见 `kind` 类型

3.2.5 `IDataRolesCollection` 与模板集合

`convertVisual`

`showData`

`export`

`extension`

`event`