weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/assets/dom-structure/Picture.json

@@ -0,0 +1,209 @@
+{
+  "component": "picture 图片组件（weapp-ebdbasecoms/src/components/picture，组件类型 Picture；注册见 src/ebcoms.ts）",
+  "usage": "组件根元素就是那张 img（root），引擎类名直接拼在它身上，没有 #<comId>.ebcom > .content 外壳。先按外壳选：默认只有 root 一张 img；config.showTitleAndDesc===true → 看 tree-title-desc（img 外多一层 div.ebcoms-picture-wrapper.<comId>，图上叠标题/描述遮罩）；config.float===true && page.layoutType==='FLOW' && config.position==='absolute' && config.flow.parent==='ROOT' → 看 tree-flow-absolute（最外再套一层 position:fixed 的壳）。定位器优先写 #<comId>（命中 img）或 .ebcoms-picture-content，遮罩统一写 .ebcoms-picture-wrapper .ebcoms-picture-desc。",
+  "legend": {
+    "[cls]": "条件class，满足配置/布局/事件条件才挂载",
+    "{a|b}": "多选一class（同一位置按页面布局或视图类型换成其中一个）",
+    "a > b": "父子层级压缩写法，冒号左边是右边的父级",
+    "ref": "引用 shared 中定义的复用片段：写成 ref:shared.xxx",
+    "uncontrolled": "外部模块（基础设计器/布局引擎/事件动作）渲染，内部结构不可控，只给挂载点",
+    "<comId>": "组件实例 id。picture 是 standalone 组件，没有引擎外壳，<comId> 直接落在 img 的 id 上（开标题描述时同时也是 wrapper 的 class）",
+    "ebcoms-": "组件自己写的类名前缀（clsPrefix='ebcoms'），加上 @weapp/ebdcoms AssetsImg 的 ebcoms-assets-img",
+    "ebcom-": "引擎/框架层类名前缀（ebcomPrefix='ebcom'），由 createView/createDesign 通过 className 拼进组件根，组件源码里搜不到",
+    "standalone": "引擎追加的标记类：picture 声明了 render.standalone=true，所以引擎不渲染 header/content/footer 外壳",
+    "weId": "React 节点上的定位属性，DOM 里小写为 weid，是样式编辑器内部用的，不要写进选择器"
+  },
+  "pickTree": "1. 先看是不是设计态：设计态根类名是 ebcom-design（并多一层 mask 之外的定位容器，见 shared.designShell）；运行态是 ebcom-view。\n2. 再按外壳叠加选树：默认（showTitleAndDesc 不为 true，也没走流式绝对定位）→ 只有 root 一层；showTitleAndDesc===true → tree-title-desc；config.float===true 且 page.layoutType==='FLOW' 且 config.position==='absolute' 且 config.flow.parent==='ROOT' → tree-flow-absolute。\n3. 后两者可叠加，三层结构是 div.ebcoms-picture-flow-absolute-wrap > div.ebcoms-picture-wrapper.<comId> > img。\n4. 看不到图时去 shared.placeholder 对号（空路径/取数中/无权限）。",
+  "root": {
+    "tag": "img",
+    "id": "<comId>",
+    "class": [
+      "ebcoms-assets-img",
+      "[lazyload]",
+      "ebcom",
+      "ebcom-picture",
+      "[ebcom-picture-<pluginResourceType>]",
+      "[ebcom-m]",
+      "{ebcom-grid|ebcom-flow|ebcom-excel}",
+      "{ebcom-view|ebcom-design}",
+      "standalone",
+      "[event-action-click]",
+      "ebcoms-picture-content",
+      "[ebcoms-picture-default-flow]",
+      "[ebcoms-picture-flow-absolute]",
+      "[ebcoms-picture-url]"
+    ],
+    "desc": "图片本体，同时也是组件根元素：引擎类名永远拼在这张 img 上（classNameStr 无条件传给 AssetsImg）。⚠️ 和 slide/nav-bar 不同，picture 的 Design/View 都声明了 render.standalone=true，所以没有 #<comId>.ebcom > .content 这套外壳，别去找 .content。类名分三段：最前 ebcoms-assets-img(+lazyload) 是 @weapp/ebdcoms AssetsImg 自己加的；中间 ebcom + ebcom-picture + ebcom-grid/flow/excel + ebcom-m + ebcom-view/design + standalone 由引擎的 getClassName 按顺序拼；末尾 ebcoms-picture-content 与几个条件类由组件自己拼。",
+    "when": "运行态与设计态都是这张 img；--showTitleAndDesc 时它外面还有 div.ebcoms-picture-wrapper.<comId>，流式绝对定位时外面还有 div.ebcoms-picture-flow-absolute-wrap",
+    "tips": [
+      "写样式直接用 #<comId> 或 .ebcoms-picture-content 即可命中最外层元素；图片尺寸/边框/圆角都在这一层",
+      "img 上会被 spread 一批 config 字段当 HTML 属性（width、height、imageMode、displayMode、scale… 例如 width=\"100%\"），这些是属性不是样式：不要写 img[width]、也不要把它们当成行内样式来源；改尺寸用 CSS",
+      "objectFit 才是行内样式：AssetsImg 收了 useAttr 后用 style={{objectFit: imageMode}}（imageMode 取 config.imageMode，默认 cover），而 config.width/height 不进 style。要覆盖图片适应方式必须显式写 object-fit，或改配置",
+      "lazyLoad 相关：config.lazyLoad===true 时 img 上是 lazyload 类 + data-src（lazysizes 加载完自己加 lazyloaded 并把地址写到 src）；没开时直接 src 出图。写图片选择器建议只认 .ebcoms-assets-img 或 .ebcoms-picture-content",
+      "class 顺序有意义：先 AssetsImg 的 ebcoms-assets-img，再引擎 className，最后组件追加的类；用 class 选择器时不要依赖顺序",
+      "运行态 img 上会由引擎写 data-id=<comId>（createView.onDomMountEvent 用 findDOMNode 取到的根元素；有 wrapper 时 data-id 落在 wrapper 上），data-id 是官方样式的作用域锚点"
+    ]
+  },
+  "shared": {
+    "imgRoot": {
+      "tag": "img",
+      "id": "<comId>",
+      "desc": "图片本体，和 root 是同一个元素，class 以 root.class 为准。外壳树里用它占位。"
+    },
+    "descBlock": {
+      "desc": "图片上的标题/描述遮罩（源码里叫 picture-desc）。只有 showTitleAndDesc===true 且「标题或描述至少一个非空」时才渲染（条件：getLocaleValue(textTitle) || getLocaleValue(textDescribe)）。这是用户说「图片上的标题/描述」时唯一命中的地方",
+      "chain": "div.ebcoms-picture-wrapper > div.ebcoms-picture-desc > div.title + div.desc",
+      "children": [
+        {
+          "tag": "div",
+          "class": ["title"],
+          "desc": "标题文字，取值 config.textTitle（走 getLocaleValue 多语言）。⚠️ .title 是裸类名，没有前缀，全页面其它组件（tabs、list…）也叫 .title，必须用 .ebcoms-picture-desc .title 或 #<comId> 限域"
+        },
+        {
+          "tag": "div",
+          "class": ["desc"],
+          "desc": "描述文字，取值 config.textDescribe；.desc 同样是裸类名，限定方式同上"
+        }
+      ],
+      "tips": [
+        "两个 div 无论标题还是描述为空都会渲染（只是内容为空串），所以别用 :empty 之类的写法去判断「有没有配标题」",
+        "遮罩默认：position:absolute、bottom:0、width:100%、padding:12px 15px、背景 rgba(0,0,0,.5)、圆角 8px，来自 view/index.less",
+        "⚠️ 遮罩的 absolute 参照物不是 wrapper：div.ebcoms-picture-wrapper 只有 height:100%，没有 position，所以遮罩会往上找最近的有定位祖先（流式绝对定位场景就是 position:fixed 的 div.ebcoms-picture-flow-absolute-wrap）。要自己控位置就给 wrapper 加 position",
+        "遮罩样式有两处来源且属性重叠：view/index.less（.ebcoms-picture-wrapper .ebcoms-picture-desc）和样式库默认代码 styleConfigDefault（.ebcoms-picture-desc，含背景色/圆角/绝对定位/display:flex）。写覆盖时用 .ebcoms-picture-wrapper .ebcoms-picture-desc 提高优先级",
+        "区域设置面板（样式库/样式管理）改的就是这三个选择器：背景色 → .ebcoms-picture-desc；标题 → .ebcoms-picture-desc .title；描述 → .ebcoms-picture-desc .desc（见 view/getPictureStyles.ts）",
+        "标题/描述是行内纯文本，没有 span 包裹，想加图标/多行排版要自己用伪元素或改结构，别指望里面有子节点"
+      ]
+    },
+    "placeholder": {
+      "desc": "「看不到图片」的几种情况，样式需求落到这里时不要去 img 的兄弟节点里找东西",
+      "list": [
+        {
+          "when": "config.path 为空（含 { url: '' }）",
+          "chain": "仍然是 img 本身，src 换成默认空图（dftPicPath = images/coms/picture/empty.png），class 上多一个 ebcoms-picture-default-flow",
+          "note": "构造器与 render 各判一次：page.layoutType==='GRID' 和 !=='GRID' 最终都会换成这张空图；该类名只给 img 加了 object-fit/display/max-width，不影响是否有图"
+        },
+        {
+          "when": "图片地址含数据集语法（图片路径绑定数据）且真实地址还没取回来，且非设计态",
+          "chain": "整块不渲染（render 返回 null）",
+          "note": "gettingPath===true 期间组件短暂为空，调样式前先确认不是这个状态"
+        },
+        {
+          "when": "页面开启 showHiddenComs 且当前组件不在 rightCompIds 里",
+          "chain": "div.ebcom-no-right-mask > span（文本「对不起，您暂时没有权限！」，引擎渲染）",
+          "note": "picture 覆写了 renderNoPermission（view/View.tsx → view/NoPermission.tsx），只是补一段流式布局的定位修正，DOM 仍是引擎这段；此时根元素不是 img"
+        }
+      ]
+    },
+    "state": {
+      "desc": "运行时由脚本动态加/移除的类，初始 render 里没有，写选择器时按「可能出现」对待",
+      "list": [
+        {
+          "condition": "开了 lazyLoad 的图片被 lazysizes 加载完成",
+          "targetSelector": "img.ebcoms-assets-img",
+          "addClass": "lazyloaded",
+          "note": "同时把 data-src 的值写进 src"
+        },
+        {
+          "condition": "流式绝对定位壳被选中（选中置顶）",
+          "targetSelector": ".ebcoms-picture-flow-absolute-wrap",
+          "addClass": "selected",
+          "note": "less 只给了 .selected{z-index:102!important}；相关选中逻辑在源码里已注释/废弃"
+        },
+        {
+          "condition": "组件被事件动作隐藏",
+          "targetSelector": "组件根元素（有 wrapper 时是 wrapper，否则是 img）",
+          "addClass": "ebcom-display-none",
+          "note": "同时写 style.display='none'，显示时按原 display 还原"
+        },
+        {
+          "condition": "点击组件（弹出悬浮菜单类事件动作的绑定标记）",
+          "targetSelector": "被点击的元素",
+          "addClass": "ebsdk-bind-dom",
+          "note": "引擎事件动作统一行为（weapp-ebdcoms event-action），每次点击会先清掉全页其它同名类"
+        }
+      ]
+    },
+    "designShell": {
+      "desc": "设计态/运行态最外层的定位容器，由基础设计器与布局引擎渲染，不在这几个仓库的源码里，组件只用 querySelector 反查它们（uncontrolled，只给挂载点，改它们会影响页面上所有组件）",
+      "list": [
+        {
+          "when": "设计态 + 网格布局（非 float）",
+          "chain": "组件按 div[data-i=<config.layout.i>] 找父节点取容器，旋转容器是 div.weapp-ebde-gl-pc-card[data-id=<comId>]"
+        },
+        {
+          "when": "设计态 + 绝对定位（float）",
+          "chain": "div.weapp-ebde-position-absolute[data-id=<comId>]，内部旋转把手是 .weapp-ebde-mgl-card-item-handle"
+        },
+        {
+          "when": "设计态 + 移动端绝对定位",
+          "chain": "div.weapp-ebde-mgl-position[data-id=<comId>]"
+        },
+        {
+          "when": "运行态 + 绝对定位",
+          "chain": "div.weapp-ebpv-gl-position[data-id=<comId>]（PC）/ div.weapp-ebpv-mgl-position[data-id=<comId>]（移动端）",
+          "note": "createView.viewMountHandler 与 NoPermission 改的就是这层的 style"
+        },
+        {
+          "when": "运行态 + 网格布局（非 float）",
+          "chain": "就是组件根 img 自己（JS 用 .ebcoms-assets-img#<comId> 或 img#<comId> 取）"
+        }
+      ],
+      "tips": [
+        "这些容器上的定位/旋转/透明度由 JS 直接重写 dom.style（setPcDomStyle / setMobileSomStyle），写在 CSS 里的同类属性常被行内覆盖",
+        "设计态组件外壳是 ebcom-picture … ebcom-design standalone，由 createDesign 拼好 className 后直接传给 PictureContent，同样没有 .content 层"
+      ]
+    }
+  },
+  "tree-title-desc": {
+    "when": "config.showTitleAndDesc === true。样式库/样式管理场景默认开启（com-style-config/picture/getCompConfig.ts 里写死 showTitleAndDesc:true、isStyleManager:true），所以这个结构在样式调优时是高频命中项",
+    "tree": [
+      {
+        "tag": "div",
+        "class": ["ebcoms-picture-wrapper", "<comId>"],
+        "desc": "标题/描述外壳（源码：`${clsPrefix}-picture-wrapper ${id}`）。⚠️ comId 同时被当成类名挂在这层，所以 .<comId> 命中 wrapper，而 #<comId> 命中里面的 img —— 同名不同层是 picture 最容易定位错的地方。less 只给了 height:100%，没有 position",
+        "children": [
+          "ref:shared.imgRoot",
+          "ref:shared.descBlock"
+        ],
+        "tips": [
+          "wrapper 只有在 showTitleAndDesc===true 时才存在；此时引擎的 data-id 也落在 wrapper 上（findDOMNode 取到的根元素），运行态官方样式作用域 div[data-id=<comId>] 指的就是它",
+          "想给「整张图 + 遮罩」作为一个整体加边框/圆角/overflow:hidden，改这层；只改图片本身用 img 那层",
+          "遮罩是 wrapper 的兄弟还是子级要注意：div.ebcoms-picture-desc 与 img 是兄弟关系，都在 wrapper 下，不是 img 的子节点"
+        ]
+      }
+    ]
+  },
+  "tree-flow-absolute": {
+    "when": "config.float===true && page.layoutType==='FLOW' && config.position==='absolute' && config.flow.parent==='ROOT'（典型是登录前页面/流式布局里的绝对定位图片）。同一个条件还决定 img 上多挂 ebcoms-picture-flow-absolute 类",
+    "tree": [
+      {
+        "tag": "div",
+        "class": ["ebcoms-picture-flow-absolute-wrap"],
+        "desc": "流式布局的绝对定位外壳，带 data-id=<comId>（设计态与运行态都有）。less 给了 position:fixed；偏移/层级/透明度全部由行内 style 决定（wrapStyle：left/right/top/bottom + transform:translate(...) + zIndex + width/height + opacity，按 horizontal.basis/vertical.basis 组合算出）",
+        "children": ["ref:shared.imgRoot"],
+        "tips": [
+          "这一层的位置尺寸是行内样式，CSS 改不动（除非 !important 且确认优先级），要改位置请改配置里的坐标/偏移",
+          "它是 position:fixed，会成为内部遮罩 absolute 的参照物",
+          "selected 类（z-index:102!important）由脚本加，用于选中置顶"
+        ]
+      }
+    ],
+    "diffs": [
+      "开了 showTitleAndDesc 时，壳里的直接子节点是 div.ebcoms-picture-wrapper.<comId>（包住 img + 遮罩），即 fixed 壳 > wrapper > img 三层；wrapper 类名见 tree-title-desc",
+      "img 上会多一个 ebcoms-picture-flow-absolute 类，它只是标记（less 没为它写规则），别当成样式钩子",
+      "img 上还可能带行内 style（imgStyle.transform = rotate(...)，仅在配置了 rotate 时），用于旋转图片本身而不转外壳"
+    ]
+  },
+  "notes": [
+    "前缀三类分清：ebcoms-* 是组件自己写的（含 @weapp/ebdcoms 公共件 AssetsImg 的 ebcoms-assets-img）；ebcom-* 是引擎/框架层，经 className 拼进组件根，组件源码里搜不到；ui-* 基本与 picture 无关（本组件没直接用 @weapp/ui 渲染结构，只有 PhotoView 预览弹层是外部组件）。",
+    "最容易犯的定位错误：照搬其它组件去找 #<comId>.ebcom > .content。picture 是 standalone 组件，引擎不生成这层外壳，组件根就是 img，引擎类名全在 img 上。",
+    "第二个易错点：comId 有双重身份。默认是 img 的 id（#<comId>）；showTitleAndDesc 时又是 wrapper 的 class（.<comId>）。样式管理器模式下 getPictureStyles 生成的自定义样式作用域是 ` .<comId>`，运行态是 ` div[data-id=<comId>]`（data-id 挂在引擎 findDOMNode 找到的根元素上：默认 img，有 wrapper 则 wrapper）。",
+    "裸类名 .title / .desc 只在遮罩内部，务必用 .ebcoms-picture-desc .title / .ebcoms-picture-desc .desc 或 #<comId> 限域，否则会命中页面其它组件的同名类。",
+    "已有 less 钩子（不要重复写）：.ebcoms-picture-content（inline-block + vertical-align）、.ebcoms-picture-url（cursor:pointer，非设计态且有链接时）、.ebcoms-picture-default-flow（object-fit:cover 等）、.ebcoms-picture-flow-absolute-wrap（position:fixed / .selected）、.ebcoms-picture-wrapper（height:100%）及其下遮罩与标题/描述全套默认外观。less 通过 src/style/lib.less 全量引入（PictureContent 里 import './index.less' 是注释掉的，别以为没生效）。",
+    "两处死代码，别照着写选择器：1) view/PictureContent.tsx 的 renderDefaultImg 从未被调用，所以 .ebcoms-picture-default-grid（及 less 里它的 svg 规则）在运行时永远不命中；2) less 的 .ebcoms-picture-default-flow > img 也不会命中——该类挂在 img 自己身上，没有子 img。",
+    "配置面板的类名（ebcoms-picture-config-*、ebcoms-picture-path-*、ebcoms-picture-config-image-mode 等）来自 config/ 目录，只出现在设计器右侧属性面板，不属于组件渲染结构，写页面运行时样式时不要用它们。",
+    "官方样式生成器 getPictureStyles 的三个目标就是 .ebcoms-picture-desc / .ebcoms-picture-desc .title / .ebcoms-picture-desc .desc（来自样式库里「图片」类目 category='1218870220785048537'，见 constants/StyleLib.ts 的 StyleType.PICTURE）；用户自定义 CSS 会被包进 div[data-id=<comId>]（样式管理器下是 .<comId>）作用域，所以自定义代码里可以直接写组件内部类名。",
+    "设计态用同一棵结构树，差别只在根类名是 ebcom-design，且外面多了基础设计器的定位容器（shared.designShell）；在页面运行态验证选择器，不要拿设计器里的结构当依据。",
+    "反查源码：view 渲染与条件分支在 view/PictureContent.tsx 的 render / renderDefaultImg；组件入口与 standalone 声明在 view/View.tsx、design/Design.tsx；class 拼装顺序在 weapp-ebdcoms/src/components/core/view/createView.tsx 的 getContainerClass 与 .../core/utils/comp.ts 的 getClassName；img 元素与 ebcoms-assets-img 在 weapp-ebdcoms/src/common/assets-lib/assets-item/Img.tsx；已有样式在 view/index.less；样式生成在 view/getPictureStyles.ts。"
+  ]
+}

package/skills/weaver-e10-builder/assets/dom-structure/Pie.json

@@ -0,0 +1,338 @@
+{
+  "component": "Pie（饼状图）",
+  "usage": "图表组件的 HTML 结构索引，用于样式定位：用户说「给饼状图的 XX 设置样式」时，在这里按语义找节点，用它的 id / class 写选择器。不是完整 DOM 树，只列有 id 或关键 class 的元素。",
+  "legend": {
+    "[cls]": "条件类名：条件满足时才出现，否则该类名不存在",
+    "{a|b}": "多选一：实际只会出现其中一个",
+    "a > b": "合并两层：b 是 a 的直接子元素（中间没有有意义的元素）",
+    "ref": "引用本文件 shared.* 里的复用片段",
+    "<comId>": "尖括号 = 需要替换的占位符。<comId> 是该组件在页面里的实例 id（配置界面叫「组件ID」），写样式时用它限域，例如 #<comId> .ebcoms-charts-total；<contentClass> 等同理。注意花括号 {a|b} 只表示「多选一」，不用来表示占位符。",
+    "ebcom / ebcom-*": "weapp-ebdcoms 引擎加的类，不在图表组件源码里（core/view/createView.tsx + core/utils/comp.ts）",
+    "ebcoms-*": "图表组件源码写的类（clsPrefix = 'ebcoms'）",
+    "ui-*": "@weapp/ui 组件的类：ui-echarts / ui-table-grid-* / ui-spin / ui-empty / ui-pagination / ui-icon / ui-bread-crumb / ui-popover",
+    "weapp-ebdf-*": "筛选搜索组件（@weapp/ebpagedesign）的类，只给挂载点，内部结构不可控"
+  },
+  "pickTree": "按「区域」取树：标题区→header，图表区（合计/轴名/canvas/加载）→chartArea，数据表→dataList，图表左右侧的数值清单→labelDataList。写样式时先 #<comId> 限域再往下找。",
+  "root": {
+    "desc": "引擎外壳，所有图表组件完全一致，由 weapp-ebdcoms 渲染（不在图表源码里）。写样式统一用 #<comId> 限域。",
+    "tree": {
+      "tag": "div",
+      "id": "<comId>",
+      "class": "ebcom ebcom-pie [ebcom-m] ebcom-{grid|flow} ebcom-view ebcom-chart has-no-header",
+      "desc": "组件根。ebcom-pie=类型类（同页多个图表组件靠它区分类型）；ebcom-m 仅移动端；ebcom-{grid|flow}=页面布局；ebcom-chart 来自图表 defaultOpts.render.containerClass；has-no-header 恒有（图表用 renderHeader 自渲染标题，不走引擎的默认 header）。",
+      "children": [
+        {
+          "tag": "div",
+          "class": "header",
+          "when": "config.titleEnabled = true",
+          "desc": "标题区。内容由图表自己的 ChartHeader 接管（见 header 树）。标题关闭时这个节点整个不存在。",
+          "ref": "header.tree"
+        },
+        {
+          "tag": "div",
+          "class": "<contentClass> content",
+          "desc": "引擎内容槽，图表全部内容都在这里。view 模式初始只有 content，其余类名由脚本 classList.toggle 追加；design 模式直接带全。可能追加到 .content 上的类：ebcoms-charts-fl（流式布局）、ebcoms-pie-content（流式布局）、show-data-list、data-list-direction-{top|bottom|left|right}、ebcoms-charts-reloading、ebcoms-charts-grid-mobile、displayFlex。",
+          "ref": "chartArea.tree"
+        },
+        {
+          "tag": "div",
+          "class": "footer",
+          "desc": "引擎底部操作栏。图表默认不开，几乎见不到；开了才会在 .content 之后出现 .ebcoms-footer-btns。"
+        }
+      ]
+    }
+  },
+  "shared": {
+    "desc": "跨区域复用的小片段。同一个 class 在多个区域出现时以这里的定义为准。",
+    "empty": {
+      "tag": "div",
+      "class": "ui-empty",
+      "desc": "@weapp/ui Empty。图表里三种用法：未匹配配置（“请设置图表配置项”）、无数据（type=noData）、词云 IE 提示（多一个 ebcoms-charts-com-WordCloud-IEempty）。紧挨着还有一个 .ebcoms-charts-placeholder 占位块（echarts 未实例化时）。"
+    },
+    "spin": {
+      "tag": "div",
+      "class": "ui-spin [ui-spin-nested-loading > ui-spin-container]",
+      "desc": "@weapp/ui Spin。图表里有 3 处，外层都会再拼一个 ebcoms-* 类：ebcoms-charts-view-loading（图表区首次加载，在 .ebcoms-charts-com 内）、ebcoms-charts-view-reloading（刷新遮罩，绝对定位铺满半透明白，在 .ebcoms-charts-main 下）、数据表内部（ui-table-grid 内自动包一层）。"
+    },
+    "toolbarBtn": {
+      "tag": "span",
+      "desc": "标题区每个操作按钮外层都是一个无 class 的 span（OperationBtns 渲染）。里面要么是图表自己的定制视图（ChartSwitch / YMDSwitch / ChartsToolbarBtn），要么是 @weapp/ui 的 ConfigurableButton（ui-btn）或配置的图标（ui-icon > svg.ui-icon-svg）。想单独选中某个按钮只能靠 :nth-child() 或按内容定位。"
+    },
+    "filterMount": {
+      "tag": "div",
+      "class": "ebcoms-cmf-view [showFilter] [empty] [mobile] [onlyCondition]  或  ebcoms-cms-search [design] [active]",
+      "desc": "筛选条件区的挂载点（CommonFilter / SearchContent）。标题区和图表区各可能出现一个，两者互斥：筛选按钮配置在标题区时只在标题区渲染。内部 DOM 不可控，只在这个挂载点上写样式。"
+    }
+  },
+  "header": {
+    "when": "config.titleEnabled = true。关闭时 #<comId> 上带 has-no-header，.header 节点不存在。",
+    "chain": "#<comId> > .header.ebcoms-charts-custom-header.PC|MOBILE",
+    "tree": {
+      "tag": "div",
+      "class": "ebcoms-charts-custom-header header  PC|MOBILE",
+      "desc": "标题区根。同时带引擎的 .header（布局用的通用类）和组件的 ebcoms-charts-custom-header。末尾的 PC / MOBILE 是 page.client 直接拼上去的，用来控制标题最大宽度（PC 65% / MOBILE 45%），不是类名前缀。",
+      "children": [
+        {
+          "tag": "div",
+          "class": "ebcoms-charts-custom-header-title-content",
+          "desc": "标题文本区。可能先有一个标题图标组件（TitleIconCom，仅配了标题图标时），然后是一个 <div> 承载标题 HTML（dangerouslySetInnerHTML，所以标题里的富文本、动态字段也会渲染进这个 div，别以为只有纯文本）。"
+        },
+        {
+          "tag": "div",
+          "class": "[isDesign]",
+          "desc": "flex:1 的右侧区，按顺序放：操作按钮组、筛选条件、再一个操作按钮组（筛选按钮配置在最后一位时按钮会挪到筛选前面）、design 模式下的遮罩 ebcoms-charts-main-filtertotal-mask。",
+          "children": [
+            {
+              "tag": "div",
+              "class": "ebcoms-header-btns",
+              "desc": "顶部操作按钮组（OperationBtns 的 wrapClass）。左侧按钮和右侧按钮会渲染成两个同 class 的兄弟 div，所以 .ebcoms-header-btns 在标题区可能出现两次，别用 :first-child 猜。",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ebcoms-chart-toolbar",
+                  "when": "“图表工具栏”按钮开启（isSupportChartToolsConfig）",
+                  "desc": "图表工具栏。固定 6 个 span 槽位，顺序固定；每个槽位内部再分 .default / .hover 两个 span。.default 和 .hover 是通用类名，写样式必须用 .ebcoms-chart-toolbar 限定，否则会串到别处。",
+                  "children": [
+                    {
+                      "tag": "span",
+                      "class": "btn-boxSelect",
+                      "desc": "区域缩放。槽位恒在，但本类型不渲染图标，是个空 span（要按顺序定位时别数错）。"
+                    },
+                    {
+                      "tag": "span",
+                      "class": "btn-clearBoxSelect",
+                      "desc": "区域缩放还原。槽位恒在，但本类型不渲染图标，是个空 span（要按顺序定位时别数错）。"
+                    },
+                    {
+                      "tag": "span",
+                      "class": "btn-changeLine",
+                      "desc": "切换为折线图。槽位恒在，但本类型不渲染图标，是个空 span（要按顺序定位时别数错）。"
+                    },
+                    {
+                      "tag": "span",
+                      "class": "btn-changeBar",
+                      "desc": "切换为柱状图。槽位恒在，但本类型不渲染图标，是个空 span（要按顺序定位时别数错）。"
+                    },
+                    {
+                      "tag": "span",
+                      "class": "btn-restore",
+                      "desc": "还原。槽位恒在，但本类型不渲染图标，是个空 span（要按顺序定位时别数错）。"
+                    },
+                    {
+                      "tag": "span",
+                      "class": "btn-saveAsImage",
+                      "desc": "保存为图片。图标存在；里面有 .default 与 .hover 两个 span（默认显示 default，hover 换成 hover，宽度/颜色/底色可由按钮配置写进行内 style），图标是 ui-icon > svg.ui-icon-svg，选中态加 .selected。"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "ref": "shared.filterMount",
+              "when": "筛选按钮在标题区"
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "chartArea": {
+    "desc": "引擎 .content 里的全部内容，由 AsyncBaseView + ChartView 渲染。",
+    "tree": {
+      "tag": "div",
+      "class": "ebcoms-charts-main",
+      "desc": ".content 下唯一的内容根。它是个 flex 容器：图表容器 .ebcoms-charts-com 和数据表 .ebcoms-data-list-display-content 是平级兄弟，所以 dataListDisplay.visible 时 .content 加 show-data-list，index.less 用它和 data-list-direction-* 决定图表与数据表是上下还是左右排列。",
+      "children": [
+        {
+          "tag": "div",
+          "class": "ebcoms-charts-main-switchChartType",
+          "when": "“图表类型”按钮开启 && customValue.keepDisplaying && 标题未开启（标题开启时它挪进标题区）",
+          "desc": "常驻在图表上方的图表类型切换条。",
+          "children": [
+            {
+              "tag": "div",
+              "class": "ebcoms-chart-head-chartSwitch",
+              "children": [
+                {
+                  "tag": "span",
+                  "class": "ebcoms-chart-head-chartSwitch-item [active]",
+                  "desc": "每个可切换类型一项，active=当前类型。内含图标（普通类型 ui-icon；Bullet 内联 svg.icon；WordCloud / Facet / HeatMap 是 img）+ 类型名文本。"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "tag": "div",
+          "id": "id_<comId>",
+          "class": "ebcoms-charts-com [ebcoms-charts-preview] [hide]",
+          "desc": "图表容器，图表区所有东西都在这。id 是 id_<comId>（id_ + 组件 id）。ebcoms-charts-preview 仅 stylePre（预览）时；hide 仅 dataListDisplay.onlyTable（只显示数据表）时。容器自带 min-width: 30px（源码注释：宽度过小时气泡图 echart 内部会报错）。",
+          "children": [
+            {
+              "tag": "div",
+              "id": "filtertotal_<comId>",
+              "class": "ebcoms-charts-main-filtertotal [hasRelationStatistics]",
+              "desc": "图表上方一行：左边合计、右边筛选条件（两者独立出现）。hasRelationStatistics 仅关系图且有统计时（左侧让出 150px）。注意它和 .ebcoms-charts-main 是两个不同的 main。",
+              "children": [
+                {
+                  "tag": "ul",
+                  "class": "ebcoms-charts-total",
+                  "when": "showTotal && 有数据 && 配置已初始化（本类型支持合计）",
+                  "desc": "合计区，每个指标一个 li，li 上没有类名（要单独选只能 :nth-child()）。这里会先撑高再触发图表 resize。"
+                },
+                {
+                  "ref": "shared.filterMount",
+                  "when": "配了筛选条件且按钮不在标题区"
+                }
+              ]
+            },
+            {
+              "tag": "div",
+              "id": "chartStatChildren_<comId>",
+              "when": "第一个维度开了“统计下级”，或有维度钻取",
+              "desc": "下钻 / 统计下级 / 关系图展开的挂载点（面包屑 + 弹出菜单）。不需要时这个 id 节点不存在。",
+              "children": [
+                {
+                  "tag": "div",
+                  "class": "ui-bread-crumb ebcoms-charts-bread-crumb {drilling|...}",
+                  "desc": "面包屑。带 drilling 时样式不同（可点层级为蓝色）。关系图不渲染它。"
+                },
+                {
+                  "tag": "span",
+                  "class": "ebcoms-charts-statChildrenSpan",
+                  "desc": "弹出菜单的定位锚点：1px 绝对定位的隐形 span，left/top 由点击坐标算出来。"
+                },
+                {
+                  "tag": "div",
+                  "class": "ebcoms-charts-statChildrenPop",
+                  "desc": "菜单弹层（Popover）。内部列表项 class 为 ebcoms-charts-list-item；弹层箭头 .ui-popover-arrow 在这里被隐藏。"
+                }
+              ]
+            },
+            {
+              "tag": "div",
+              "class": "ebcoms-charts-axis-name",
+              "when": "永不出现",
+              "desc": "本类型在 hasNoAxis 列表里（无直角坐标轴），不会渲染坐标轴名称节点。注意：ECharts 的 category/axis 概念跟这里的 DOM 无关，不要以为没 DOM 就没配置项。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-echarts [ui-echarts-rtl]",
+              "when": "非空数据且没在 loading",
+              "desc": "图表本体。ECharts 用 canvas 渲染，图例 / 坐标轴 / 数据标签 / tooltip / 柱子颜色全在 canvas 里，CSS 选不到——这些只能改图表配置项或图表主题。容器本身可改尺寸、背景、边框、滤镜；RTL 页面会多 ui-echarts-rtl（会 transform: scaleX(-1)）。"
+            },
+            {
+              "ref": "labelDataList.tree",
+              "when": "config.labelPosition = left 或 right，且 label.valType !== none，且非移动端、非“仅统计表”"
+            },
+            {
+              "ref": "shared.empty"
+            },
+            {
+              "tag": "div",
+              "class": "ebcoms-charts-placeholder",
+              "when": "chartInstance 尚未就绪",
+              "desc": "占位块，撑住高度防止塌陷。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-spin ebcoms-charts-view-loading",
+              "when": "配置还未初始化完成，或正在刷新数据（此时上面那批节点都不渲染，互斥）",
+              "desc": "图表区加载态。"
+            }
+          ]
+        },
+        {
+          "tag": "div",
+          "class": "ui-pagination ebcoms-charts-pagination",
+          "when": "config.showPagination = true（本类型支持分页配置）",
+          "desc": "图表级分页（不是数据表里的分页）。内部 ui-pagination-pager / ui-pagination-pager-item / ui-pagination-pager-active / ui-pagination-pager-page-input。"
+        },
+        {
+          "ref": "dataList.tree"
+        },
+        {
+          "tag": "div",
+          "class": "ui-spin ebcoms-charts-view-reloading",
+          "when": "reloading（切换图表类型 / 切换日期分组 / 强刷）",
+          "desc": "整块刷新遮罩：绝对定位居中铺满 + rgba(255,255,255,.7) 底。要改遮罩底色改这里。"
+        }
+      ]
+    }
+  },
+  "labelDataList": {
+    "when": "config.labelPosition = left 或 right，且 label.valType !== none，且非移动端、非“仅统计表”",
+    "chain": ".ebcoms-charts-com > .ebcoms-label-data-list-content.{onLeft|onRight} > .ui-table-grid...",
+    "tree": {
+      "tag": "div",
+      "class": "ebcoms-label-data-list-content {onLeft|onRight} [onSameSide]",
+      "desc": "图表左/右侧的「分类 + 数值」清单（config.labelPosition = left/right 时出现，同时图例会被隐藏）。maxWidth / height / top 都在行内 style 上（30% 或 50% 宽）。onLeft / onRight 对应 labelPosition；onSameSide 表示和图例同侧（此时行可点击联动图例）。",
+      "children": [
+        {
+          "tag": "div",
+          "class": "ui-table-grid ui-table-grid-bordered ui-table-grid-no-pagination",
+          "desc": "内部是 @weapp/ui Table，没有额外 class，只能用 ui-table-grid-* 选。两列：分类（65%）/ 数值（35%）。分类列里有个 8x8 的色块 span（颜色写在行内 style.background-color），数值列是 span（行内 style.color，被点击后置灰 #ccc）。要改色块/文字颜色只能覆盖行内样式（!important）。"
+        }
+      ]
+    }
+  },
+  "dataList": {
+    "when": "dataListDisplay.visible = true 且非空数据",
+    "chain": ".content > .ebcoms-charts-main > .ebcoms-data-list-display-content.{horizantal|vertical}[.show-total][.isMobile] > .ui-table-grid.ebcoms-datalist-table",
+    "tree": {
+      "tag": "div",
+      "class": "ebcoms-data-list-display-content {horizantal|vertical} [show-total] [isMobile]",
+      "desc": "数据表区域。和图表的 .ebcoms-charts-com 是 .ebcoms-charts-main 下的平级兄弟（不在图表容器里），所以它不会跟着图表一起被 hide。注意类名是 horizantal（源码里的拼写，少一个 o），别写成 horizontal。位置由 .content 上的 data-list-direction-{top|bottom|left|right} 控制；horizantal 表示横向扩展（第一列固定）。",
+      "children": [
+        {
+          "tag": "div",
+          "class": "ui-table-grid ebcoms-datalist-table ui-table-grid-bordered [ui-table-grid-no-pagination] [ui-table-grid-scroll-position-*] [ui-table-grid-table__fixed]",
+          "desc": "数据表（@weapp/ui Table）。下面这些 ui-table-grid-* 是引擎已有样式钩子，可以直接复用；要改文字色 / 表头底色 / 内容底色 / 边框色，优先用组件外观样式里的「数据表」配置（会自动生成这些选择器，见 notes）。",
+          "children": [
+            {
+              "tag": "div",
+              "class": "ui-spin > ui-spin-nested-loading > ui-spin-container",
+              "desc": "表格自带 loading 包裹层，表格内容都在 ui-spin-container 里。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-table-grid-header-warp > .ui-table-grid-header",
+              "desc": "表头。里面 table > thead.ui-table-grid-thead > tr > th.ui-table-grid-th。固定列时还会有一份 ui-table-grid-sticky-header-warp（滚动吸顶）。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-table-grid-body-outer > .ui-table-grid-body",
+              "desc": "表体。table > tbody.ui-table-grid-tbody > tr > td.ui-table-grid-td。合计行在 tfoot.ui-table-grid-tfoot（showTotal && 纵向扩展时）。细分隔行 tr 带 ui-table-grid-tr__gray。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-table-grid-scroll",
+              "desc": "横向滚动容器；只在有固定列或按 table 滚动时出现。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-table-grid-fixed-left / ui-table-grid-fixed-right",
+              "desc": "左右固定列（横向扩展时第一列 fixed: left）。"
+            },
+            {
+              "tag": "div",
+              "class": "ui-table-grid-empty",
+              "desc": "无数据占位。"
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "notes": [
+    "样式作用域：图表样式由「组件外观样式」生成，最终选择器都会被包在 #<comId>.ebcom 下面（自定义源码再套一层 #<comId> .comCodeSource）。自己写选择器也建议 #<comId> .xxx，避免同页多图表互相污染。",
+    "数据表配色有官方生成器：组件外观样式→数据表里的「字体/表头底色/内容底色/边框色」，会直接生成 .ebcoms-data-list-display-content 下的 .ui-table-grid-td/.ui-table-grid-th/.ui-table-grid-thead/.ui-table-grid-header-warp/.ui-table-grid-body-outer/.ui-table-grid-tbody/.ui-table-grid-tfoot 规则。要改数据表颜色优先用这个，不要重复写 CSS。",
+    "canvas 边界：图例、坐标轴刻度、数据标签、tooltip、柱/扇区颜色全部是 ECharts canvas，CSS 选不到。这类需求只能改图表配置项或图表主题，不要试图用选择器命中。",
+    "同名陷阱：引擎的 .header / .content / .footer（无前缀）≠ 组件的 ebcoms-*-content；.ebcoms-charts-main 和 .ebcoms-charts-main-filtertotal 是两个不同层的节点，只差一个后缀；.default / .hover 是工具栏按钮的通用类名，必须用 .ebcoms-chart-toolbar 限定；displayFlex 是无前缀裸类名（全局限定）。",
+    "引擎自动加的修饰类：#<comId> 上恒有 has-no-header；ebcom-chart 来自图表 defaultOpts.render.containerClass；padding=false 时加 content-no-padding；配了点击事件时加 event-action-click。",
+    "移动端：外壳多 ebcom-m 类；网格布局 + 移动端时 .content 多 ebcoms-charts-grid-mobile（内部把加载块高度固定 300px）。",
+    "反查源码：引擎 weapp-ebdcoms/src/components/core/{view,design}/{createView,Base,createDesign}.tsx、core/utils/comp.ts、core/view/operation-btns/OperationBtns.tsx；组件 weapp-ebdchartcoms/src/components/charts/core/{BaseView,ChartView,ChartHeader,AxisLabelName,ChartTotal,ChartStatChildren,getChartsStyles}.ts(x)、core/DataListDisplay/*、core/LabelDataListDisplay.tsx、core/index.less；UI 库 weapp-ui/src/components/{echarts,table,spin,pagination,empty}。",
+    "饼图是唯一会同时出现「数值展示列表」和「图表级分页」的类型。",
+    "扇形/扇区颜色、标签、引导线（hasLeadLength）都是 canvas，不是 DOM。"
+  ]
+}