@guandata/guanvis 0.1.34 → 0.1.35

package/skills/guanvis/references/api-reference.md

@@ -7,6 +7,7 @@
 | `defineDataset(dsId, columns, options?)` | 定义数据集 schema（由 init 命令生成）。第一个数据集自动暴露为 `global.DS`（dsId 字符串）。`options.displayType` 指定数据集类型（如 `"EXCEL"`, `"DATAFLOW"`），确保看板页面正确显示数据集图标 |
 | `field(dsId, fieldName, overrides?)` | 从 schema 构造字段引用，`dsId` 是字符串。可叠加 aggrType/alias/numberFormat/sortType/granularity 等 |
 | `f(fieldName, overrides?)` | `field(DS, fieldName, overrides)` 的简写，仅适用于**单数据集**场景 |
+| `chartField(zone, index)` | 按最终数据区和位置引用图表字段，用于 `setAuxiliaryLine()` 的计算辅助线 |
 | `calcField(name, formula, opts?)` | 创建卡片级计算字段（公式中用 `[字段名]` 引用字段）。`opts`: `calculationType`/`fdType`/`numberFormat`/`advCalc`/`fieldFormat` 等 |
 | `filterField(dsId, fieldName, filterType, filterValue?, opts?)` | 创建筛选字段（带 filterType/filterValue），传给 `.addFilter()` 使用 |
 | `getDataset(dsId)` | 获取已定义的数据集对象（返回对象，**不要**传给 `field()` 和 `bindDataset()`） |

package/skills/guanvis/references/builder-reference.md

@@ -21,18 +21,26 @@
 | `.addTooltip(field)` / `.addFilter(field)` | 提示/筛选 |
 | `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
-| `.setSplitSetting({ rows, columns })` | 拆分行列数（默认各 3），需配合 `.addSplit(field)` |
-| `.setColorByColors(preset_or_config)` | colorBy 渐变色。传 `ColorByPreset.RedGreen` 等预设名称，或 `{ startColor, endColor, middleColor?, steps? }` 自定义 hex 颜色 |
-| `.setShapeColorType(type)` | 图形填充方式。默认不调用为纯色；支持 `ShapeColorType.TransparentGradient`，仅用于前端已支持的柱/条类图表 |
-| `.setShowTitle(show)` | 是否显示卡片标题；隐藏标题用 `.setShowTitle(false)` |
-| `.setShowLegend(show, position)` | 图例 |
-| `.setDataLabel(config)` | 数据标签 |
-| `.setAxis(config)` | 轴配置（见下方 Axis Config 详解） |
-| `.setTableSetting(config)` / `.setPieSetting(config)` | 特殊图表设置 |
-| `.setThemeColor(tcId, colors)` | 主题颜色 |
+| `.setSplitSetting(config)` | 拆分图配置 |
+| `.setColorByColors(preset_or_config)` | 渐变色配置 |
+| `.setShapeColorType(type)` | 图形填充配置 |
+| `.setLineSetting(config)` | 折线显示配置 |
+| `.setCardSetting(config)` | 卡片背景、主题跟随、内边距和内容间距 |
+| `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 卡片标题显隐和样式配置 |
+| `.setShowLegend(show, position?)` / `.setChartLegend(config)` | 图例配置 |
+| `.setDataLabel(config)` / `.setMetricAdditionalDataLabel(config)` | 数据标签配置 |
+| `.setAxis(config)` | 坐标轴配置 |
+| `.setTooltip(config)` | 工具提示配置 |
+| `.setTableSetting(config)` / `.setTableCellMerge(config)` | 表格配置 |
+| `.setPieSetting(config)` / `.setPieCenterText(config)` | 饼图配置 |
+| `.setGrandTotal(config)` | 表格总计与小计配置 |
+| `.setSummary(field, options?)` / `.setSummaryStyle(config)` | 汇总指标及样式配置 |
+| `.setSpecialValue(config)` | 特殊值显示配置 |
+| `.setDynamicParameterDefaultValue(param(dpId), value, options?)` | 卡片级动态参数默认值；数组按逗号连接，默认 `inheritParent: false` |
+| `.setThemeColor(tcId, colors?, options?)` | 主题色、颜色覆盖和分类/顺序色板配置 |
 | `.setLimit(count)` | 数据行数限制 |
-| `.setConditionalFormat(config)` / `.setAuxiliaryLine(config)` | 条件格式/辅助线 |
-| `.setMainViceStyle(config)` | 设置主副指标内容样式，配置见“数值组与主副指标组” |
+| `.setConditionalFormat(config)` / `.setAuxiliaryLine(config)` | 条件格式和辅助线配置 |
+| `.setMainViceStyle(config)` | 主副指标样式配置 |
 | `.linkTo(target, config)` | 图表卡片点击联动；`target` 可传布局 index 或 cardId，详细规则见本节 Card Linkage |
 | `registerDrillPath(parentCardIndex, drillCards, config?)` | 全局函数，声明固定路径下钻，详细规则见本节 Card Drill |
 | `.setRawSettings(key, value)` | 原始设置 |
@@ -150,10 +158,20 @@ attachCard(CARD_ID, BASE_PATH)
 | `.addDynamicRow(name, fields, options?)` / `.addDynamicColumn(name, fields, options?)` | 添加指标平台动态维度组 |
 | `.addDynamicMetric(name, fields, options?)` / `.addDynamicMetricAdditional(name, fields, options?)` | 添加指标平台动态指标组 |
 | `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |
-| `.setShowTitle()` / `.setShowLegend()` / `.setDataLabel()` / `.setAxis()` / `.setTableSetting()` / `.setRawSettings()` | 常用图表设置，和普通 CardBuilder 一致 |
-| `.setProps(obj)` / `.setRawProps(key, value)` | 设置指标卡片 `meta.chartMain.props` |
+| `.setCardSetting()` | 卡片背景、主题跟随、内边距和内容间距 |
+| `.setShowTitle()` / `.setCardTitleStyle()` | 卡片标题显隐和样式配置 |
+| `.setShowLegend()` / `.setChartLegend()` | 图例配置 |
+| `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
+| `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
+| `.setLineSetting()` | 折线显示配置 |
+| `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
+| `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格配置 |
+| `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
+| `.setRawSettings()` | 原始设置 |
+| `.setProps(obj)` | 设置指标卡片 `meta.chartMain.props` |
 | `.setConfig(obj)` / `.setRawConfig(key, value)` | 设置指标卡片 `meta.chartMain.config` |
-| `.setSummary(obj)` | 设置指标卡片 `meta.summary` |
+| `.setSummary(metric(...), options?)` | 设置指标卡片 `meta.summary`；旧的原始对象签名继续兼容 |
+| `.setSummaryStyle(config)` / `.setSpecialValue(config)` | 汇总样式和特殊值配置 |
 | `.setColumns(columns)` | 设置指标卡片 `content.columns` / `dsInfo.columns` |
 | `.addMetricAdditional()` / `.addColorBy()` / `.addSize()` / `.addTooltip()` / `.addSplit()` | 添加副轴、颜色、大小、提示、拆分区域字段 |
 | `.build()` | 构建指标卡片 |
@@ -183,7 +201,7 @@ var card = createCard(ChartType.BASIC_COLUMN, "区域销售额")
     .setShapeColorType(ShapeColorType.TransparentGradient);
 ```
 
-支持的图表：`BASIC_COLUMN`、`BASIC_BAR`、`GROUPED_COLUMN`、`GROUPED_BAR`、`GROUPED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`、`BULLET_BAR`。
+支持的图表：`BASIC_COLUMN`、`BULLET_COLUMN`、`BASIC_BAR`、`BULLET_BAR`、`GROUPED_COLUMN`、`GROUPED_BAR`、`GROUPED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`。
 
 多指标示例：
 
@@ -203,77 +221,9 @@ registerMetricChart(card.build());
 - `KPI_CARD`：展示主指标 + 对比指标，例如同比、环比、目标差异；使用时应同时配置 `.addMetric(...)` 和 `.addCompare(...)`。
 - 没有对比指标时优先用 `SINGLE_VALUE`，即使卡片放在看板顶部 KPI 区。
 
-#### Axis Config（`.setAxis(config)`）
+#### 图表属性配置
 
-`config` 对象可包含 `categoryAxis`（X 类目轴）、`mainAxis`（Y 主轴）、`secondaryAxis`（Y 副轴）：
-
-```javascript
-.setAxis({
-    categoryAxis: {
-        visible: true,
-        showTitle: true, title: "月份",
-        autoRotate: 45,
-        labelFontSize: 12,
-        showAxisLine: true
-    },
-    mainAxis: {
-        visible: true,
-        showTitle: true, title: "销售额",
-        min: 0, max: 100000,
-        autoExtremes: false,
-        showGridLine: true,
-        labelFontSize: 11
-    },
-    secondaryAxis: {
-        visible: true,
-        showTitle: true, title: "利润率",
-        labelFontSize: 11
-    }
-})
-```
-
-| 属性 | 适用轴 | 说明 |
-|------|--------|------|
-| `visible` | 所有 | 是否显示轴（`false` 隐藏轴） |
-| `showTitle` | 所有 | 是否显示轴标题 |
-| `title` | 所有 | 轴标题文字 |
-| `titleFontSize` / `titleColor` / `titleBold` | 所有 | 标题字体样式 |
-| `unit` | mainAxis/secondaryAxis | 单位（如"万元"），显示在标题旁 |
-| `min` / `max` | mainAxis/secondaryAxis | 固定轴范围（需 `autoExtremes: false`） |
-| `autoExtremes` | mainAxis/secondaryAxis | `true`（默认）自动计算范围 |
-| `showGridLine` | mainAxis/secondaryAxis | 是否显示网格线 |
-| `reverseValue` | mainAxis/secondaryAxis | 反转轴方向 |
-| `labelFontSize` / `labelColor` | 所有 | 刻度标签字体 |
-| `autoRotate` | categoryAxis | 标签旋转角度（0/45/90） |
-| `textLength` | categoryAxis | 标签截断字符长度 |
-| `step` | categoryAxis | 标签间隔（每 N 个显示一个） |
-| `showAxisLine` | categoryAxis | 是否显示轴线 |
-
-#### Auxiliary Line Config（`.setAuxiliaryLine(config)`）
-
-辅助线/参考线配置。`config` 对象按轴分组：
-
-```javascript
-.setAuxiliaryLine({
-    mainAxis: [
-        { name: "目标线", color: "#FF0000", valueType: "FIXED", fixedValue: "50000" },
-        { name: "平均值", color: "#0088FF", valueType: "CALCULATED", calculatedValue: "AVG" }
-    ],
-    secondaryAxis: [
-        { name: "基准线", color: "#00AA00", valueType: "FIXED", fixedValue: "0.3" }
-    ]
-})
-```
-
-每条辅助线的属性：
-
-| 属性 | 说明 |
-|------|------|
-| `name` | 辅助线名称（显示在图例中） |
-| `color` | 颜色（hex 字符串如 `"#FF0000"`） |
-| `valueType` | `"FIXED"`（固定值）或 `"CALCULATED"`（聚合计算） |
-| `fixedValue` | 当 `valueType="FIXED"` 时的固定数值（字符串格式） |
-| `calculatedValue` | 当 `valueType="CALCULATED"` 时的聚合类型：`"AVG"`（平均值）、`"MAX"`、`"MIN"`、`"MEDIAN"`、`"SUM"` |
+图表属性的字段、枚举、默认值和联动规则见 `references/chart-properties.md`。编写对应 setter 前必须先读该文档。
 
 #### Conditional Format Config（`.setConditionalFormat(config)`）
 
@@ -1570,6 +1520,8 @@ project/
 | `FieldType` | `STRING`, `INT`, `LONG`, `DOUBLE`, `FLOAT`, `DATE`, `BOOL`, `DECIMAL` | 字段数据类型 |
 | `SortOrder` | `ASC`, `DESC` | 排序方向 |
 | `Granularity` | `NONE`, `YEAR`, `QUARTER`, `MONTH`, `WEEK`, `DAYOFWEEK`, `DAY`, `HOUR`, `MINUTE`, `SECOND` | 日期粒度 |
+| `GrandTotalPosition` | `LEFT`, `RIGHT`, `TOP`, `BOTTOM` | 表格总计位置；行总计用左右，列总计用上下 |
+| `ContentSpaceSize` | `SMALL`, `MIDDLE`, `LARGE` | 卡片内容间距 |
 | `DynamicFieldOrder` | `PRESET`, `CLICK` | 动态字段默认顺序；`PRESET` 按候选顺序，`CLICK` 按用户选择顺序 |
 | `FilterType` | `IN`, `NOT_IN`, `GT`, `GE`, `LT`, `LE`, `EQ`, `NE`, `BT`（区间）, `CONTAINS`, `NOT_CONTAINS`, `STARTSWITH`, `ENDSWITH`, `IS_NULL`, `NOT_NULL` | 筛选条件类型 |
 | `FilterLevel` | `DETAIL`（明细）, `AGGREGATION`（聚合）, `RESULT`（结果） | 筛选级别 |