工程结构与配置说明

2.1 标准工程目录

一个典型的 Wyn 插件工程通常包含如下结构：

plugin-name/
├── src/
│   └── visual.ts
├── style/
│   └── visual.less
├── i18nResources/
│   ├── zh-CN.json
│   ├── en-US.json
│   └── zh-TW.json
├── assets/
│   └── icon.png
├── dist/
│   ├── visual.js
│   └── visual.css
├── capabilities.json
├── visual.json
├── visual.d.ts
├── webpack.config.js
├── tsconfig.json
└── package.json

2.2 核心文件职责

文件	作用	是否关键
`src/visual.ts`	插件主逻辑入口，负责渲染、交互、数据消费	是
`style/visual.less`	插件样式定义	是
`capabilities.json`	数据绑定、属性面板、动作栏、分析能力定义	是
`visual.json`	插件元信息、运行参数、依赖资源定义	是
`visual.d.ts`	Wyn 提供的接口类型声明	是
`i18nResources/*.json`	多语言资源	推荐
`assets/*`	图标或图片资源	推荐
`webpack.config.js`	打包输出配置	是
`tsconfig.json`	TypeScript 编译配置	是
`package.json`	依赖、脚本、版本号	是

2.3 `visual.json`：定义插件身份与运行参数

2.3.1 接口定义

interface IVisualMeta extends ILocalizable, IIconable {
    name: string;
    description?: string;
    externalJs?: string[];
    externalCss?: string[];
    assets?: {
        images?: {
            [key: string]: string;
        }
    };
    configuration?: {
        [key: string]: string;
    };
}

2.3.2 常用字段说明

字段	说明
`name`	插件内部名称
`displayName` / `displayNameKey`	插件显示名或国际化键
`description`	插件说明
`icon`	插件图标
`externalJs`	外部 JavaScript 依赖
`externalCss`	外部 CSS 依赖
`assets.images`	图片资源，打包后通常以 base64 形式访问
`configuration`	运行参数定义，上传后可在管理后台配置

2.3.3 常见配置项

原始资料中给出的典型配置包括：

{
  "configuration": {
    "$runInIframe": true,
    "$trusted": true
  }
}

字段理解建议：

$runInIframe：控制插件以 iframe 还是 DIV 方式运行
$trusted：与宿主的信任/沙箱策略相关，实际生产使用前建议结合当前版本验证

2.4 `capabilities.json`：定义插件能力边界

2.4.1 顶层接口定义

interface ICapabilityDefinition {
    dataBinding?: IDataBinding;
    options?: IOptions;
    actions?: Array<IAction>;
    analysis?: Array<IAction>;
}

该文件主要回答四个问题：

需要什么数据：dataBinding
可以配置什么属性：options
支持哪些动作：actions
支持哪些分析行为：analysis

2.5 通用基础接口

多个接口都会复用以下公共定义：

interface ILocalizable {
    displayName?: string;
    displayNameKey?: string;
}

interface IIconable {
    icon?: string;
    iconCss?: string;
}

interface IMember extends ILocalizable, IIconable {
    name?: string;
}

interface IEnumItem extends ILocalizable, IIconable {
    value: any;
}

interface IPosition {
    top?: number;
    right?: number;
    bottom?: number;
    left?: number;
}

interface ISize {
    width?: number;
    height?: number;
}

这些接口的作用分别是：

ILocalizable：让对象支持显示名称或国际化键
IIconable：让对象支持图标或图标样式
IMember：常用于动作、属性等命名成员
IEnumItem：用于枚举属性、动作扩展项等下拉项
IPosition：用于边距或定位
ISize：用于尺寸配置

2.6 `package.json`、`tsconfig.json` 与 `webpack.config.js`

2.6.1 `package.json`

通常承担三类职责：

依赖版本管理
构建脚本定义
插件版本号维护

版本号非常关键，因为系统上传插件时会检查新旧版本，高版本才能正常升级旧版本。

2.6.2 `tsconfig.json`

常见配置关注项包括：

target
module
resolveJsonModule
esModuleInterop
lib
skipLibCheck

2.6.3 `webpack.config.js`

负责把 src/visual.ts 和样式文件打包为最终交付产物：

dist/visual.js
dist/visual.css

2.7 国际化资源目录

原始资料建议在 i18nResources 中至少维护：

zh-CN.json
en-US.json
zh-TW.json（可选）

典型用途包括：

插件名称
数据绑定面板字段名
属性面板名称
动作栏按钮名称
无数据提示文案

2.8 配置文件之间的关系

可以把这些文件理解为一张“职责地图”：

文件	定义什么
`visual.json`	插件是谁、依赖什么、运行参数是什么
`capabilities.json`	插件暴露什么数据、属性、动作、分析能力
`visual.ts`	插件如何工作
`visual.d.ts`	插件可调用哪些 Wyn 接口
`style/visual.less`	插件呈现样式是什么
`i18nResources/*`	插件在不同语言下如何显示

也就是说：

visual.json + capabilities.json 决定“插件能暴露什么”
visual.ts 决定“插件实际上怎么运行”