# 基类通用选项与默认命名

> 所有组件继承的通用 options（几何/边框背景/联动选中开关/内部布局/悬浮弹层）与省略 `name` 时的默认显示名。
> 返回目录：[index.md](index.md)；全量选项字典（最权威）：[widget-schema.generated.json](../widget-schema.generated.json)。

## 基类继承选项（所有组件都有）

来自 `VpWidget.defineOptions()` + `VpElement.defineOptions()`。手写时多数省略走默认，常用的是 `position`/`size`/`opacity`、联动选中开关。

| option | 类型 | 默认 | 说明 |
|---|---|---|---|
| `size` | `vector<W,H>` | `[300,200]`(各组件覆盖) | 组件大小 `[宽,高]` |
| `position` | `vector<X,Y>` | `[0,0]` | 左上角位置（容器内为相对坐标） |
| `rotate` | `vector<X,Y,Z>` | `[0,0,0]` | 旋转角度 |
| `opacity` | `slider 0~100` | `100` | 不透明度 |
| `no-events` | `boolean` | `false` | 鼠标穿透 |
| `border` | `boolean` 组 | `false` | 开启后有 `border-color/width/radius/style` |
| `background` | `boolean` 组 | `false` | 开启后有 `background-color/image/fill-type/blur` |
| `background-fill-type` | `select` | `stretch` | 背景填充方式（导出常见此键） |
| `responsive-x` / `responsive-y` | `select` | `left` / `top` | 响应式锚定 |
| `device-visible` | `boolean` | `true` | 按设备显隐（**所有画像按视口宽切档**，固定画布也生效）：写进 `sizeModeOverrides.MEDIUM/SMALL` 即只在平板/手机隐藏，基线 `false`+某模式覆盖 `true`=仅该设备显示 |
| `cross-filter-emit` / `cross-filter-receive` | `boolean` | 见下 | 联动发出/接收 |
| `select-sync-emit` / `select-sync-receive` | `boolean` | 见下 | 选中发出/接收 |
| `cross-filter-routing-enabled` / `select-sync-routing-enabled` | `boolean` | `false` | 高级联动/选中（按指定元素） |
| `filter` | `boolean` 组 | `false` | 组件级数据筛选 |
| `state-rule-fields` | `field` | — | 数据规则用到的字段（高级） |

> 联动/选中默认值因组件而异；导出文件里常见显式写 `"cross-filter-emit": true`、`"select-sync-receive": true` 等。需要组件间点击联动时显式打开相应开关即可。

**内部布局（容器通用）**：`container-layout` 有三值——`static`(绝对定位,默认)/`fluid`(流式 flex)/**`grid`(栅格)**。栅格容器项：`grid-columns`/`grid-rows`(1~24)、`grid-col-gap`/`grid-row-gap`(px)；栅格**子项**：`grid-col-span`/`grid-row-span`(跨列/跨行,默认 1)、`grid-col-start`/`grid-row-start`(1-based 起始线,0=自动流式填充)。流式容器/子项选项见 [visual-style.md](../visual-style.md) §3 与 [layouts.md](layouts.md)（`flex-direction`/`fluid-wrap`/`fluid-gap-*`/子项 `fluid-width-type` 等）。

**悬浮弹层（组件通用，`hover-popup-*`）**：任意组件可配「悬停/点击 → 旁边弹出内容」——`hover-popup-enable:true` + `hover-popup-trigger`(`hover`悬停/`click`点击 toggle) + `hover-popup-content`(`text`文字提示/`window`目标画面)。text 档配 `hover-popup-text/bg/color/font-size/max-width/padding`；window 档配 `hover-popup-window`(窗口引用，目标窗口建议锚定模式)。定位 `hover-popup-placement`(auto 自动翻转)/`hover-popup-gap`/`hover-popup-arrow`、延时 `hover-popup-open-delay`/`-close-delay`(ms)。仅预览/运行态弹出。

通用触发器（交互用，一般生成阶段不写）：`click`、`mouseEnter`、`mouseLeave`、`appear`、`disappear`、`receiveBehaviorEvent`。

---

## 默认名（省略 name 时的显示名）汇总

| 类型 | 默认名 |
|---|---|
| `basic-text` | `text` 值或"文本" |
| `basic-paragraph` / `basic-markdown` | "段落" / 内容首行或"Markdown" |
| 图表族 `chart-*` | `title` 值或图表名（"柱状图"/"折线图"/"面积图"/"双轴图"/"双轴堆叠图"/"饼图"/"散点图"/"雷达图"/"漏斗图"/"仪表盘"/"热力图"/"矩形树图"/"桑基图"/"关系图"/"水球图"/"词云"/"胶囊柱图"/"区域地图"） |
| `basic-table` / `basic-scroll-board` / `basic-ranking-list` | "基础表格" / "轮播列表" / "排名列表" |
| `group-panel` / `data-repeater` / `component-instance` / `window-instance` | "分组面板" / "数据循环容器" / 母版名或"组合组件" / "画面组件" |
| `layout-section` / `nav-views` | "视图容器" / "视图导航" |
| 控件 | "按钮"/"搜索框"/"基础下拉菜单"/"分页器"/"列表"/"进度条"/"iframe"/"弹窗"/"选项卡"/"按钮组菜单" |
| 媒体 | "图片"/"图形"/"轮播图"/"视频" |
| 时间 | "时钟"/"计时器"/"日历"/"时间选择"/"时间轴" |
| 指标/装饰 | "数字卡片"/"翻牌器"/"图标"/"装饰边框"/"装饰"/"流程管道" |
| 布局 | "行布局"/"列布局"/"网格布局"/"流式行"/"固定面板"/"停靠布局"/"侧边栏"/"手风琴"/"占位" |
| `map-2d` / `map-control-*` | "2D地图" / 各控件中文名（"坐标位置"/"比例尺"/"缩放控件"/"指南针"/"导出(图片/PDF)"/"视角+全屏"/"底图切换"/"CAD图层"/"图层管理"/"鹰眼"/"测量工具"/"数据图例"） |
| `map-body`/`map-tile`/`map-marker`/`map-geojson`/`map-region` | "场景"/"底图"/"标记"/"GeoJSON"/"区域" |
| `scada-2d` | "组态画板" |
| `scada-node`/`scada-link` | "图元"（按形状名）/"连线" |