统计图（Chart）定义编写指南¶

目标：Agent 直接生成/修改 workspace 统计图 XML。知识以本文为准。不写原理；不依赖外链。

iScript：写 scripttext（须 return ECharts option）时，先读 iscript-usage（含 GraalVM 差异） → chart.md；本文只定 chartName/挂接与落盘。

术语：实体类 cn.myapps.core.common.model.chart.Chart；产品「统计图 / 图表」；设计器模块下「统计图」。是模块内 iScript → ECharts option 的可视化资源；不是 UReport/自定义报表（report）、不是 echartsreport、**不是**首页 Widget 本体（Widget 可挂接本资源）。

依赖：挂在**模块（Module）**下；parentId=模块 id。菜单 linkType=02 或 Widget type=chart 引用本资源 id。

产出物一览¶

部分	落盘	形态
统计图	`{图表名}.chart/{图表名}.chart`	目录型；JAXB 根 `chart`；`id` 为根属性

storage/workspace/{软件名}.application/module/{模块名}.module/{图表名}.chart/{图表名}.chart

路径相对 storage/workspace。嵌套模块时把 {模块名}.module 换成完整模块链。

常量（`ModelSuffix`）	值
`CHART_PATH_SUFFIX` / `CHART_FILE_SUFFIX`	`chart`

新建最低配置：

模块目录已存在
建目录 {name}.chart/，写同名文件 {name}.chart
XML：id、name、parentId=模块 id、非空 scripttext（返回 ECharts option）、chartName（样例类型键）
（常用）fontSize=12；commonFilterCondition 写 <![CDATA[[]]]>；viewId/searchFormId 可空
需要入口时：菜单 linkType=02 或 Widget type=chart，actionContent=图表 id，moduleid=模块 id

约定：

JAXB；根 chart；id 在 根属性（勿写成子元素 <id>）；统一 __ + 短 UUID
scripttext、commonFilterCondition、description 用 CDATA
文件名 = name + .chart；目录名 = 文件名；同模块下 name 不重名
name 勿含 / % \（落盘替换为 =47/=37/=92）
parentId = 模块 id；applicationid 样例可写软件 id，也可省略（靠路径归属）
**必须**放在模块下；勿放到应用根或 task/ 等应用级目录
布尔以外数字字段用字面量（fontSize）

硬规则（落盘前必查）¶

id 一律写在根属性：<chart id="...">；写成子元素 → 不进 url.index
scripttext 必须 return ECharts option 对象（常用 IIFE）；仅写静态 JSON 或无 return → 前台空白/报错
chartName 用设计器样例键（如 lineChart）；与脚本内 series[].type（line/bar/pie…）不是同一套字符串
菜单/Widget 挂接前图表 id 必须已存在；moduleid 必须是图表所在模块

1. 心智模型¶

模块 Module
  └─ {名}.chart/{名}.chart     ← 本文：元数据 + scripttext
        │
        ▼ 前台打开 / Widget 渲染
运行 iScript（scripttext）
        │  return option（ECharts 配置对象）
        ▼
ECharts.setOption(option)

可选入口：
  菜单 linkType=02，actionContent=图表 id，moduleid=模块 id
  Widget type=chart，actionContent=图表 id，moduleid=模块 id
可选交互：
  viewId → 点击图表跳转视图
  searchFormId + commonFilterCondition → 查询表单过滤

概念	说明
`scripttext`	打开时执行的 iScript；必须 return 合法 ECharts option
`chartName`	设计器「选择样例」键；标识样例类型，不代替脚本内容
`viewId`	点击图表跳转的视图 id；可空
`searchFormId`	查询表单 id（表单 type=256）；可空
`commonFilterCondition`	JSON 字符串：常用查询字段列表；无查询时 `[]`
`fontSize`	脚本编辑器字号；默认 `12`

与其它资源区分：

对象	用途
`.chart`（本文）	模块统计图；脚本返回 ECharts option
`.report` / UReport	报表模板，不是本资源
`.echartsreport`	另一类 ECharts 报表扩展；后缀不同
Widget `type=chart`	首页砖块，引用图表 id，不是图表定义本身

2. Chart 属性 → `.chart` XML¶

属性表¶

属性	XML	类型	默认/样例	说明
`id`	根属性	string	须生成	`__` + 短 UUID；菜单/Widget 的 `actionContent`
`name`	子元素	string	—	必填；文件名；模块内唯一
`parentId`	子元素	string	—	= 模块 id
`applicationid`	子元素	string	软件 id	可选；样例有时写 `undefined`，新建请写真实软件 id 或省略
`description`	CDATA/文本	string	可空	备注
`scripttext`	CDATA	string	—	必填；iScript，return ECharts option
`chartName`	子元素	string	`lineChart` 等	样例类型键；设计器保存写此字段
`type`	子元素	string		历史字段；部分旧文件写与 `chartName` 同值；新建以 `chartName` 为准，可同时写同值
`viewId`	子元素	string	可空	点击跳转视图 id
`searchFormId`	子元素	string	可空	查询表单 id
`commonFilterCondition`	CDATA	string	`[]`	JSON 数组字符串；见下
`fontSize`	子元素	int	`12`	12–26
`title` / `view` / `json` / `userid` / `module` / `chartName` 以外历史字段				模型仍有；现行设计器不写；新建可省略

`chartName`（设计器样例键）¶

chartName	含义
`lineChart`	折线图
`barChart`	柱状图
`pieChart`	饼图
`funnelChart`	漏斗图
`stepChart`	阶梯图
`stackedBarChart`	堆叠柱状图
`ringChart`	环形图
`rectangleChart`	矩形树图
`basicAreaChart`	基础面积图
`stackedAreaChart`	堆叠面积图

选样例仅提供**静态演示脚本**；业务图须把 scripttext 改成查库/汇总后组装 option。

`commonFilterCondition`¶

设计器保存时 JSON.stringify 数组。元素形如 { "field": "<查询表单字段id>" }。

无常用查询：<commonFilterCondition><![CDATA[[]]]></commonFilterCondition>
有字段：例如 <![CDATA[[{"field":"__FIELD_UUID"}]]]>
依赖 searchFormId；字段 id 来自该查询表单；空 field 或重复 field 设计器会拦

3. `scripttext` 编写要点¶

形态（必须）¶

(function () {
  // 1) 查数 / 组装数组
  // 2) 构造 option
  var option = { /* ECharts option */ };
  return option;
})()

运行时执行脚本，拿 返回值 交给 ECharts；不是把 option JSON 直接当文件内容
可用平台 iScript：findBySQL、数据源 queryDataSourceSQL、getDomainid() 等（与视图 SQL 脚本同类环境）
业务表：TLK_ + 表单 name；业务列：ITEM_ + 字段名大写；查平台表常带域条件

查库拼 option（推荐骨架）¶

(function () {
  var categories = [];
  var values = [];
  try {
    var sql = "select item_name as name, count(*) as cnt from tlk_xxx where domainid='" + getDomainid() + "' group by item_name";
    var datas = findBySQL(sql);
    if (datas != null) {
      for (var it = datas.iterator(); it.hasNext();) {
        var row = it.next();
        categories.push(new String(row.get("name")));
        values.push(Number(row.get("cnt")));
      }
    }
  } catch (e) { }
  var option = {
    title: { text: "示例统计" },
    tooltip: { trigger: "axis" },
    xAxis: [{ type: "category", data: categories }],
    yAxis: [{ type: "value" }],
    series: [{ name: "数量", type: "bar", data: values }]
  };
  return option;
})()

具名数据源查询（与产品文档一致）：

var service = Packages.cn.myapps.designtime.common.service.DesignTimeServiceFactory
  .resolve("cn.myapps.designtime.datasource.service.DataSourceDesignTimeService");
var datas = service.queryDataSourceSQL("软件显示名或标识", sql, "数据源id");

静态样例（折线，可作占位）¶

(function () {
  var option = {
    title: { text: "未来一周气温变化", subtext: "纯属虚构" },
    tooltip: { trigger: "axis" },
    legend: { data: ["最高气温", "最低气温"] },
    xAxis: [{ type: "category", boundaryGap: false, data: ["周一", "周二", "周三", "周四", "周五", "周六", "周日"] }],
    yAxis: [{ type: "value", axisLabel: { formatter: "{value} °C" } }],
    series: [
      { name: "最高气温", type: "line", data: [11, 11, 15, 13, 12, 13, 10] },
      { name: "最低气温", type: "line", data: [1, -2, 2, 5, 3, 2, 0] }
    ]
  };
  return option;
})()

4. XML 骨架¶

最小可用（折线占位）¶

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<chart id="__CHART_UUID">
  <name>SalesTrend</name>
  <parentId>__MODULE_UUID</parentId>
  <description></description>
  <scripttext><![CDATA[(function () {
  var option = {
    title: { text: "销售趋势" },
    tooltip: { trigger: "axis" },
    xAxis: [{ type: "category", data: ["Q1", "Q2", "Q3", "Q4"] }],
    yAxis: [{ type: "value" }],
    series: [{ name: "金额", type: "line", data: [120, 200, 150, 280] }]
  };
  return option;
})()]]></scripttext>
  <commonFilterCondition><![CDATA[[]]]></commonFilterCondition>
  <viewId></viewId>
  <searchFormId></searchFormId>
  <fontSize>12</fontSize>
  <chartName>lineChart</chartName>
</chart>

带跳转视图 + 查询表单¶

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<chart id="__CHART_UUID">
  <name>OrderStatusPie</name>
  <parentId>__MODULE_UUID</parentId>
  <description><![CDATA[订单状态分布]]></description>
  <scripttext><![CDATA[(function () {
  var data = [];
  try {
    var sql = "select item_status as name, count(*) as cnt from tlk_order where domainid='" + getDomainid() + "' group by item_status";
    var datas = findBySQL(sql);
    if (datas != null) {
      for (var it = datas.iterator(); it.hasNext();) {
        var row = it.next();
        data.push({ name: new String(row.get("name")), value: Number(row.get("cnt")) });
      }
    }
  } catch (e) { }
  var option = {
    title: { text: "订单状态", x: "center" },
    tooltip: { trigger: "item" },
    series: [{ name: "状态", type: "pie", radius: "55%", data: data }]
  };
  return option;
})()]]></scripttext>
  <commonFilterCondition><![CDATA[[{"field":"__SEARCH_FIELD_UUID"}]]]></commonFilterCondition>
  <viewId>__LIST_VIEW_UUID</viewId>
  <searchFormId>__SEARCH_FORM_UUID</searchFormId>
  <fontSize>12</fontSize>
  <chartName>pieChart</chartName>
</chart>

5. 入口挂接¶

5.1 PC / 移动菜单（`linkType=02`）¶

  <linkType>02</linkType>
  <moduleid>{模块id}</moduleid>
  <actionContent><![CDATA[{图表id}]]></actionContent>

细节见 generate-menu-file / generate-mobilemenu-file。

5.2 首页 Widget（`type=chart`）¶

  <type>chart</type>
  <moduleid>{模块id}</moduleid>
  <actionContent><![CDATA[{图表id}]]></actionContent>

须先有 .widgetgroup；细节见 generate-widget-file。

6. 新建清单¶

确认模块 id、软件路径
生成图表 id（__ + 短 UUID）；name 用英文标识（显示可用中文 description 或 name 本身，与项目约定一致）
写 {name}.chart/{name}.chart：parentId、scripttext、chartName、fontSize、commonFilterCondition
按需填 viewId、searchFormId、查询字段 JSON
按需建菜单 02 或 Widget chart
大批量落盘后先 verify-workspace，再 rebuild-index

7. 与其它技能边界¶

内容	本文	其它
`.chart` XML / scripttext / chartName	✅
菜单打开图表	只给 linkType=02 要点	`generate-menu-file`
Widget 挂图表	只给 type=chart 要点	`generate-widget-file`
列表/树视图		`generate-view-file`
UReport / 自定义报表		非本技能
`echartsreport`		后缀不同，勿混用
应用规划中的图表项		`plan-application` §7 / 实施清单

8. 硬规则清单¶

- [ ] 路径：module/.../{name}.chart/{name}.chart；parentId=模块 id
- [ ] id 在根属性 <chart id="...">
- [ ] scripttext CDATA，IIFE，必须 return ECharts option
- [ ] chartName 用样例键（lineChart/barChart/…）；series.type 用 ECharts 类型（line/bar/pie/…）
- [ ] 无查询时 commonFilterCondition 为 [] 的 CDATA
- [ ] 菜单 02 / Widget chart 的 actionContent=图表 id，且 moduleid 正确
- [ ] 勿与 .report / .echartsreport 混淆