@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-list-data-query.md

@@ -5,14 +5,14 @@ source_doc: "bos-runtime-plugin 报表示例"
 last_updated: "2026-04-03"
 status: "approved"
 scene_name: "报表数据查询插件"
-related_apis: ["AbstractReportListDataPlugin", "query", "getColumns", "ReportQueryParam", "DataSet", "ReportColumn", "Algo", "ORM", "QFilter", "BusinessDataServiceHelper"]
+related_apis: ["AbstractReportListDataPlugin", "query", "getColumns", "ReportQueryParam", "DataSet", "ReportColumn", "Algo", "QueryServiceHelper.queryDataSet", "QFilter", "BusinessDataServiceHelper"]
 topic: "报表数据查询"
 ---
 
 # 场景：报表数据查询插件
 
 ## 适用情况
-实现报表的数据查询逻辑，包括通过 ORM 查询数据库、通过 Algo 构建内存数据集、动态添加报表列等。适用于分组报表左右列表取数、树形报表明细取数、自定义数据源报表等场景。报表数据查询插件从 `AbstractReportListDataPlugin` 派生。
+实现报表的数据查询逻辑，包括通过 `QueryServiceHelper` 查询数据库、通过 Algo 构建内存数据集、动态添加报表列等。适用于分组报表左右列表取数、树形报表明细取数、自定义数据源报表等场景。报表数据查询插件从 `AbstractReportListDataPlugin` 派生。
 
 ## 事件/方法说明
 
@@ -21,7 +21,7 @@ topic: "报表数据查询"
 - `ReportColumn.setFieldKey(key)`：设置列标识，必须与 DataSet 中的字段名一致
 - `ReportColumn.setCaption(LocaleString)`：设置列标题
 - `ReportColumn.setFieldType(type)`：设置列类型（TYPE_TEXT、TYPE_BASEDATA 等）
-- `ORM.create().queryDataSet(...)`：通过 ORM 查询数据库返回 DataSet
+- `QueryServiceHelper.queryDataSet(...)`：查询数据库并返回 DataSet；DCS 禁止 `kd.bos.orm.ORM`（`CVE-KD-2026-0508`）
 - `Algo.create(key).createDataSet(input)`：通过 Algo 构建内存 DataSet
 - `BusinessDataServiceHelper.loadSingleFromCache(...)`：从缓存加载基础资料
 
@@ -39,7 +39,7 @@ public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns)
 ## 代码示例
 `extracted` `needs-verification`
 
-通过 ORM 查询数据库并动态添加列：
+通过查询服务读取数据并动态添加列：
 
 ```java
 package kd.bos.plugin.sample.report.bizcase;
@@ -51,24 +51,24 @@ import kd.bos.entity.report.AbstractReportColumn;
 import kd.bos.entity.report.AbstractReportListDataPlugin;
 import kd.bos.entity.report.ReportColumn;
 import kd.bos.entity.report.ReportQueryParam;
-import kd.bos.orm.ORM;
 import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
 public class ReportListDataQuerySample extends AbstractReportListDataPlugin {
 
     @Override
     public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
-        ORM orm = ORM.create();
+        List<QFilter> filters = queryParam.getFilter().getHeadFilters();
         String selectedField = "number,name,parent as pid,isleaf,id as rowid";
-        return orm.queryDataSet(getClass().getName(),
+        return QueryServiceHelper.queryDataSet(getClass().getName(),
                 "kdtest_basedata_tree",
                 selectedField,
-                queryParam.getFilter().getHeadFilters().toArray(new QFilter[0]),
+                filters.toArray(new QFilter[filters.size()]),
                 queryParam.getSortInfo());
     }
 
     @Override
-    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) {
+    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) throws Throwable {
         super.getColumns(columns);
         ReportColumn numberColumn = new ReportColumn();
         numberColumn.setCaption(new LocaleString("工号"));
@@ -122,7 +122,7 @@ public class ReportAlgoDataSample extends AbstractReportListDataPlugin {
     }
 
     @Override
-    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) {
+    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) throws Throwable {
         super.getColumns(columns);
         Set<String> keys = new HashSet<>(columns.size());
         for (AbstractReportColumn col : columns) {
@@ -201,7 +201,7 @@ public class ReportGroupRightDataSample extends AbstractReportListDataPlugin {
     }
 
     @Override
-    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) {
+    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) throws Throwable {
         super.getColumns(columns);
         ReportColumn col = new ReportColumn();
         col.setFieldKey("orgnumber");
@@ -220,4 +220,4 @@ public class ReportGroupRightDataSample extends AbstractReportListDataPlugin {
 - 动态生成的列不要设置 `dataIndex`，只需设置 `fieldKey` 并确保和 DataSet 中的字段名一致
 - 基础资料类型列需设置 `entityId`（引用实体标识）和 `displayProp`（显示属性）
 - 分组报表中，右侧列表的 `selectedObj` 参数为左侧选中行的数据对象
-- ORM 查询的 `selectFields` 支持 `as` 别名语法
+- 查询的 `selectFields` 支持 `as` 别名语法

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-merge-column.md

@@ -7,7 +7,7 @@ status: "approved"
 scene_name: "报表列合并"
 trigger_event: "setMergeColums"
 scene_keywords: ["setMergeColums", "ReportColumnMerge", "报表合并", "列合并", "packageData", "noMergeKey", "AbstractReportFormPlugin"]
-related_apis: ["AbstractReportFormPlugin.setMergeColums", "AbstractReportFormPlugin.packageData", "PackageDataEvent.getNoMergeKey"]
+related_apis: ["AbstractReportFormPlugin.setMergeColums", "AbstractReportFormPlugin.packageData", "PackageDataEvent.getNoMergeKey", "ReportExportInitializeEvent.setMergeColumnRules"]
 ---
 
 # 场景：报表列合并
@@ -18,6 +18,7 @@ related_apis: ["AbstractReportFormPlugin.setMergeColums", "AbstractReportFormPlu
 ## 事件含义
 - `setMergeColums`：在报表渲染前触发，向 `columns` 列表中添加需要合并的字段标识
 - `packageData`：在数据打包时触发，可以通过 `getNoMergeKey()` 排除特定行的合并
+- `exportInitialize`：导出开始时触发；`setMergeColumnRules(rules)` 设置导出文件如何合并单元格，这不由界面上的合并决定
 
 ## 涉及的核心对象（必读）
 | 对象 | 用途 | 文档路径 |
@@ -82,10 +83,14 @@ public class XxxMergeReportPlugin extends AbstractReportFormPlugin {
     @Override
     public void packageData(PackageDataEvent packageDataEvent) {
         super.packageData(packageDataEvent);
+        // source 是单元格所在的列；强转前先判断类型
+        if (!(packageDataEvent.getSource() instanceof ReportColumn)) {
+            return;
+        }
         ReportColumn column = (ReportColumn) packageDataEvent.getSource();
         // 当文本列的值为"小计"时，排除该行的合并
         if ("text_field".equals(column.getFieldKey())
-                && "小计".equals(packageDataEvent.getFormatValue().toString())) {
+                && "小计".equals(String.valueOf(packageDataEvent.getFormatValue()))) {
             // 将当前列加入不合并列表，该行不参与合并
             packageDataEvent.getNoMergeKey().add(column.getFieldKey());
         }
@@ -103,9 +108,9 @@ import kd.bos.entity.report.FilterItemInfo;
 import kd.bos.entity.report.ReportColumn;
 import kd.bos.entity.report.ReportQueryParam;
 import kd.bos.metadata.entity.report.ReportColumnFactory;
-import kd.bos.orm.ORM;
 import kd.bos.orm.query.QCP;
 import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -124,11 +129,10 @@ public class XxxReportQueryPlugin extends AbstractReportListDataPlugin {
                         info.getValue()));
             }
         });
-        ORM orm = ORM.create();
         String selectField = "text_field, integer_field, datetime_field";
-        return orm.queryDataSet(getClass().getName(),
+        return QueryServiceHelper.queryDataSet(getClass().getName(),
                 "target_entity", selectField,
-                filters.toArray(new QFilter[0]), null);
+                filters.toArray(new QFilter[filters.size()]), null);
     }
 
     @Override
@@ -148,9 +152,43 @@ public class XxxReportQueryPlugin extends AbstractReportListDataPlugin {
 }
 ```
 
+### 示例4：导出文件合并单元格
+```java
+import java.util.ArrayList;
+import java.util.List;
+
+import kd.bos.report.events.MergeColumnRule;
+import kd.bos.report.events.ReportExportInitializeEvent;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class XxxExportMergeReportPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    public void exportInitialize(ReportExportInitializeEvent event) {
+        super.exportInitialize(event);
+        List<MergeColumnRule> rules = new ArrayList<>(1);
+
+        // 分组字段：分组值相同的行构成一个合并区间
+        List<String> groupColumns = new ArrayList<>(2);
+        groupColumns.add("type");
+        groupColumns.add("amount");
+
+        // 合并字段：在每个区间内合并，不管它们自己相邻行的值是否相同
+        List<String> mergeColumns = new ArrayList<>(2);
+        mergeColumns.add("amount");
+        mergeColumns.add("currency");
+
+        rules.add(new MergeColumnRule(groupColumns, mergeColumns));
+        event.setMergeColumnRules(rules);
+    }
+}
+```
+
 ## 注意事项
 - `setMergeColums` 中添加的字段标识必须与报表列定义中的 `fieldKey` 一致
 - 合并规则：相邻行中指定列的值完全相同时自动合并，值不同时断开
 - `packageData` 中通过 `getNoMergeKey().add()` 可以排除特定行的合并，适用于小计行、合计行等
 - 列合并仅影响显示效果，不影响数据查询和导出
+- 导出文件改按 `exportInitialize` 的规则合并。一个合并字段只能属于一条规则。合并跟随分组字段：只要分组字段的值相同，合并字段就合并，不会比较合并字段自己相邻行的值——所以值也必须相同的合并字段要同时列入分组字段，就像示例4中的 `amount`
+- 强转前用 `instanceof ReportColumn` 检查 `packageDataEvent.getSource()`，可能为 null 的值用 `String.valueOf(...)` 比较
 - 报表表单插件（`AbstractReportFormPlugin`）和报表数据查询插件（`AbstractReportListDataPlugin`）需要配合使用

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-print-data.md

@@ -0,0 +1,163 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "标品报表案例 10"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表打印数据"
+related_apis: ["AfterLoadDataEvent.getDataSource", "AfterLoadDataEvent.setDataRowSets", "CustomDataLoadEvent.getDataSource", "CustomDataLoadEvent.getCustomDataRows", "MainDataSource.getPageId", "CustomDataSource.getPageId", "CustomDataSource.getPkId", "CustomDataSource.getDsName", "CustomDataSource.getQueryField", "DataRowSet.put", "ReportView.getReportList", "ReportListModel.getRowData", "ReportListModel.getRowCount", "DynamicObject.getString", "DynamicObject.get"]
+topic: "报表打印"
+---
+
+# 场景：报表打印数据
+
+## 适用情况
+报表通过打印模板打印，但报表没有可供打印引擎加载的实体数据：它的行在报表页面的列表模型里。打印插件（`printplugin`，继承 `kd.bos.print.core.plugin.AbstractPrintPlugin`）从该模型取出行，交给模板的数据源——主数据源决定打印多少页，自定义数据源填充每一页。示例按物料分页打印：每页一个页头和该物料的行。
+
+## 事件/方法说明
+
+- `afterLoadData(AfterLoadDataEvent)`：对主数据源（`getDataSource() instanceof MainDataSource`），`getPageId()` 是报表页面的标识；`setDataRowSets(rows)` 为每个打印页设置一行
+- `loadCustomData(CustomDataLoadEvent)`：每个自定义数据源、每一页触发一次；`getDataSource()` 是 `CustomDataSource`，其 `getDsName()` 是它在模板中的名称，`getPkId()` 是该页所属主数据行的 `id`，`getPageId()` 是报表页面，`getQueryField()` 是模板使用的字段；把行加到 `getCustomDataRows()` 中
+- `SessionManager.getCurrent().getView(pageId)`：报表页面的视图；`((ReportView) view).getReportList().getReportModel()` 是它的列表模型
+- `ReportListModel.getRowCount()` / `getRowData(startIndex, length)`：报表的行，以列名为键的 `DynamicObject`
+- `DataRowSet.put(fieldKey, new TextField(text))`：一个打印行，每个模板字段一个值
+
+## 方法签名
+```java
+public class MyReportPrintPlugin extends AbstractPrintPlugin
+
+@Override
+public void afterLoadData(AfterLoadDataEvent evt)
+
+@Override
+public void loadCustomData(CustomDataLoadEvent evt)
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+每个物料打印一页，页头和行都取自报表页面的模型：
+
+```java
+package kd.bos.plugin.sample.report.print;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+import kd.bos.cache.ThreadCache;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.mvc.SessionManager;
+import kd.bos.mvc.report.ReportListModel;
+import kd.bos.mvc.report.ReportView;
+import kd.bos.print.core.data.DataRowSet;
+import kd.bos.print.core.data.datasource.CustomDataSource;
+import kd.bos.print.core.data.datasource.MainDataSource;
+import kd.bos.print.core.data.datasource.PrtDataSource;
+import kd.bos.print.core.data.field.TextField;
+import kd.bos.print.core.plugin.AbstractPrintPlugin;
+import kd.bos.print.core.plugin.event.AfterLoadDataEvent;
+import kd.bos.print.core.plugin.event.CustomDataLoadEvent;
+
+public class StockDetailReportPrintPlugin extends AbstractPrintPlugin {
+
+    // 页 id -> {首行, 行数}，留给同一请求中的自定义数据源使用
+    private static final String PAGE_RANGES = "StockDetailReportPrintPlugin_pageRanges";
+    private static final String PAGE_HEAD = "printhead";
+    private static final String[] DETAIL_FIELDS = {"billno", "bizdate", "qty", "amount"};
+
+    @Override
+    public void afterLoadData(AfterLoadDataEvent evt) {
+        super.afterLoadData(evt);
+        PrtDataSource source = evt.getDataSource();
+        if (!(source instanceof MainDataSource)) {
+            return;
+        }
+        ReportListModel model = reportModel(((MainDataSource) source).getPageId());
+        if (model == null) {
+            return;
+        }
+        DynamicObjectCollection rows = model.getRowData(0, model.getRowCount());
+        Map<String, int[]> ranges = new HashMap<>(16);
+        List<DataRowSet> pages = new ArrayList<>(16);
+        int start = 0;
+        for (int i = 1; i <= rows.size(); i++) {
+            boolean pageEnds = i == rows.size()
+                    || !Objects.equals(rows.get(i).getString("material"), rows.get(start).getString("material"));
+            if (pageEnds) {
+                // 主数据行的 "id" 会作为自定义数据源的 pkId 传回
+                String pageId = String.valueOf(start);
+                DataRowSet page = new DataRowSet();
+                page.put("id", new TextField(pageId));
+                pages.add(page);
+                ranges.put(pageId, new int[]{start, i - start});
+                start = i;
+            }
+        }
+        ThreadCache.put(PAGE_RANGES, ranges);
+        evt.setDataRowSets(pages);
+    }
+
+    @Override
+    public void loadCustomData(CustomDataLoadEvent evt) {
+        super.loadCustomData(evt);
+        CustomDataSource source = evt.getDataSource();
+        ReportListModel model = reportModel(source.getPageId());
+        Object ranges = ThreadCache.get(PAGE_RANGES);
+        if (model == null || !(ranges instanceof Map) || source.getPkId() == null) {
+            return;
+        }
+        int[] range = (int[]) ((Map<?, ?>) ranges).get(String.valueOf(source.getPkId()));
+        if (range == null) {
+            return;
+        }
+        // 起始行与行数
+        DynamicObjectCollection rows = model.getRowData(range[0], range[1]);
+        List<DataRowSet> printRows = evt.getCustomDataRows();
+        if (PAGE_HEAD.equals(source.getDsName())) {
+            DataRowSet head = new DataRowSet();
+            head.put("material", new TextField(rows.get(0).getString("material")));
+            printRows.add(head);
+            return;
+        }
+        // 明细行：只给模板要的字段
+        List<String> wanted = source.getQueryField();
+        int seq = 1;
+        for (DynamicObject row : rows) {
+            DataRowSet printRow = new DataRowSet();
+            printRow.put("seq", new TextField(String.valueOf(seq++)));
+            for (String field : DETAIL_FIELDS) {
+                if (wanted == null || wanted.contains(field)) {
+                    Object value = row.get(field);
+                    printRow.put(field, new TextField(value == null ? "" : String.valueOf(value)));
+                }
+            }
+            printRows.add(printRow);
+        }
+    }
+
+    // 报表没有实体行：打印它页面列表模型里的内容
+    private static ReportListModel reportModel(String pageId) {
+        Object view = SessionManager.getCurrent().getView(pageId);
+        if (!(view instanceof ReportView)) {
+            return null;
+        }
+        Object model = ((ReportView) view).getReportList().getReportModel();
+        return model instanceof ReportListModel ? (ReportListModel) model : null;
+    }
+}
+```
+
+## 注意事项
+- 打印插件是注册在打印模板上的 `printplugin` 类，不是报表插件；报表页面只负责发起打印。它的指南是 `print-plugin-guide.md`
+- 主数据源决定打印多少页：每页一个 `DataRowSet`，它的 `id` 会以 `getPkId()` 传回给该页的每个自定义数据源。标品代码把 `id` 标注为页行必须携带的值
+- `getRowData(startIndex, length)` 接收起始行和行数；页范围把两者都记下来
+- `ThreadCache` 把页范围从主数据源带给同一个打印请求中的自定义数据源。它只在一个线程上有效：如果打印在另一个线程上加载数据，页范围就丢了——标品的兜底是由打印发起方直接把列表模型放进 `ThreadCache`
+- 模板字段与插件字段按名称对应；`getQueryField()` 列出模板的字段，模板没有的字段就跳过。新增打印字段要同时改模板和插件
+- 数字以文本打印：在 `new TextField(...)` 之前用用户的格式（`InteServiceHelper.getUserFormat(userId)`，再用 `FormatFactory.get(FormatTypes.Number)` 或 `FormatTypes.Currency`，配上行上的精度与货币符号）格式化；标品默认不打印零值
+- 主数据源要读取模型的所有行来分页，所以超大报表要注意内存
+- 旧版 API `kd.bos.entity.plugin.AbstractPrintServicePlugin.customPrintDataEntities` 在一个方法里用 `DynamicObject` 行完成同样的事；新开发使用 `AbstractPrintPlugin`（`kd.bos.print.core.*`）
+- 8.0 SDK 同时声明了 `DataRowSet.put(String, Field)` 和 `DataRowSet.add(String, Field)`；8.0.1 参考记载的是 `put`，标品示例写的是 `add`。本页用有文档记载的 `put`

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-row-data-toolbar.md

@@ -0,0 +1,188 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "报表插件示例 示例2；标品报表案例 03"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表工具栏按钮与行数据"
+related_apis: ["ReportList.getReportModel", "ReportList.getTotalRecords", "ReportList.setSelectedAll", "IReportListModel.getRowData", "ReportListModel.getRowData", "IPageCache.put", "IPageCache.get", "ListShowParameter.setBillFormId", "ListShowParameter.setListFilterParameter", "QFilter.of", "DynamicObject.getDynamicObject", "DynamicObject.getPkValue"]
+topic: "报表表单插件"
+---
+
+# 场景：报表工具栏按钮与行数据
+
+## 适用情况
+报表工具栏按钮作用于报表行：打开当前行背后的单据、处理所有选中行、由某一行生成单据。`reportform` 插件把按钮路由到 `itemClick`，找到行（`itemClick` 本身不带行），再从报表模型读出该行——每一行都以取数插件 DataSet 的列名为键。
+
+## 事件/方法说明
+
+- `addItemClickListeners("toolbarap")`：把工具栏按钮路由到 `itemClick`；不注册，任何按钮都到不了插件。在 `registerListener` 中调用
+- `itemClick(ItemClickEvent)`：`evt.getItemKey()` 是被点击的工具栏项标识
+- `ReportList.addCellClickListener(CellClickListener)`：`cellClick(CellClickEvent)` 给出被点击的行，`e.getRow()`
+- `getPageCache()`：页面级字符串缓存（`put(key, value)` / `get(key)`），把单元格点击时的行号带到按钮点击时
+- `reportList.getReportModel().getRowData(rowIndex)`：以 `DynamicObject` 返回一行
+- `ReportList.setSelectedAll(true)`：允许用户全选结果中的所有行；在 `beforeQuery` 中设置
+- `IReportListModel.getRowData(startIndex, length, onlyWithSelectedRows)`：一段行，最后一个参数为 `true` 时只取选中行
+- `ReportList.getTotalRecords()`：结果的总行数
+
+## 方法签名
+```java
+@Override
+public void registerListener(EventObject e)
+
+@Override
+public void itemClick(ItemClickEvent evt)
+
+@Override
+public void beforeQuery(ReportQueryParam queryParam)
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+当前行：缓存被点击的行，再打开它背后的单据列表：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.Date;
+import java.util.EventObject;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.report.IReportListModel;
+import kd.bos.form.IPageCache;
+import kd.bos.form.ShowType;
+import kd.bos.form.control.events.CellClickEvent;
+import kd.bos.form.control.events.CellClickListener;
+import kd.bos.form.control.events.ItemClickEvent;
+import kd.bos.list.ListFilterParameter;
+import kd.bos.list.ListShowParameter;
+import kd.bos.orm.query.QFilter;
+import kd.bos.report.ReportList;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class ToolbarReportFormPlugin extends AbstractReportFormPlugin {
+
+    private static final String TOOLBAR_KEY = "toolbarap";
+    private static final String REPORT_LIST_KEY = "reportlistap";
+    private static final String ROW_INDEX = "rowIndex";
+
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        // 把工具栏按钮路由到 itemClick
+        this.addItemClickListeners(TOOLBAR_KEY);
+        // itemClick 不带当前行：记住用户最后点击的行
+        ReportList reportList = this.getControl(REPORT_LIST_KEY);
+        IPageCache pageCache = this.getPageCache();
+        reportList.addCellClickListener(new CellClickListener() {
+            @Override
+            public void cellClick(CellClickEvent event) {
+                pageCache.put(ROW_INDEX, String.valueOf(event.getRow()));
+            }
+
+            @Override
+            public void cellDoubleClick(CellClickEvent event) {
+            }
+        });
+    }
+
+    @Override
+    public void itemClick(ItemClickEvent evt) {
+        super.itemClick(evt);
+        if ("viewbillbtn".equals(evt.getItemKey())) {
+            showBillList();
+        }
+    }
+
+    private void showBillList() {
+        String rowIndex = this.getPageCache().get(ROW_INDEX);
+        if (rowIndex == null || rowIndex.isEmpty()) {
+            this.getView().showTipNotification(ResManager.loadKDString("请先选择一行数据。", "ToolbarReportFormPlugin_0", "xxx-report"));
+            return;
+        }
+        ReportList reportList = this.getControl(REPORT_LIST_KEY);
+        IReportListModel model = reportList.getReportModel();
+        // 行以取数插件 DataSet 的列名为键
+        DynamicObject row = model.getRowData(Integer.parseInt(rowIndex));
+        // 基础资料列取出来是 DynamicObject，主键用 getPkValue()
+        Object companyId = row.getDynamicObject("companycol").getPkValue();
+        Date startDate = row.getDate("startdatecol");
+        Date endDate = row.getDate("enddatecol");
+
+        ListShowParameter parameter = new ListShowParameter();
+        parameter.setFormId("bos_list");
+        parameter.setBillFormId(row.getString("billformidcol"));
+        parameter.getOpenStyle().setShowType(ShowType.MainNewTabPage);
+        ListFilterParameter listFilter = new ListFilterParameter();
+        listFilter.setFilter(QFilter.of("company = ? and bizdate >= ? and bizdate <= ?", companyId, startDate, endDate));
+        parameter.setListFilterParameter(listFilter);
+        this.getView().showForm(parameter);
+    }
+}
+```
+
+所有选中行：查询前开启全选，点击时读出选中行：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.EventObject;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.report.IReportListModel;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.form.control.events.ItemClickEvent;
+import kd.bos.report.ReportList;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class SelectAllReportFormPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        this.addItemClickListeners("toolbarap");
+    }
+
+    @Override
+    public void beforeQuery(ReportQueryParam queryParam) {
+        super.beforeQuery(queryParam);
+        ReportList reportList = this.getControl("reportlistap");
+        // 允许用户全选结果中的所有行
+        reportList.setSelectedAll(true);
+    }
+
+    @Override
+    public void itemClick(ItemClickEvent evt) {
+        super.itemClick(evt);
+        if (!"processbtn".equals(evt.getItemKey())) {
+            return;
+        }
+        ReportList reportList = this.getControl("reportlistap");
+        IReportListModel model = reportList.getReportModel();
+        // 起始行、行数、是否仅选中行
+        DynamicObjectCollection selected = model.getRowData(0, reportList.getTotalRecords(), true);
+        if (selected == null || selected.isEmpty()) {
+            this.getView().showTipNotification(ResManager.loadKDString("请选择要处理的行。", "SelectAllReportFormPlugin_0", "xxx-report"));
+            return;
+        }
+        for (DynamicObject row : selected) {
+            // ……按列名处理每一个选中行
+        }
+    }
+}
+```
+
+## 注意事项
+- 工具栏按钮是元数据：报表工具栏上的一个项，通常绑定 donothing 操作；它的标识就是 `evt.getItemKey()` 的返回值
+- 用 `addItemClickListeners("toolbarap")` 在 `registerListener` 中注册工具栏监听；不注册，`itemClick` 永远不会触发。编译边界会拒绝类中缺少对应 `add*` 调用的 `itemClick`、`cellClick` 或 `hyperLinkClick` 覆写（`PLUGIN_SOURCE_LISTENER_UNREGISTERED`），也会拒绝在 `initialize` 中添加的监听（`PLUGIN_SOURCE_LIFECYCLE_MISUSE`）
+- `itemClick` 不带当前行。把单元格点击的行号存进 `getPageCache()`——它只属于当前报表页面——并且像所有依赖行的按钮一样，没点行时给出提示
+- 两个插件之间的契约是列名：`getRowData` 以取数插件 DataSet 的列名为每行的键，表单插件读取的列必须是已声明的报表列——不用于展示时设为隐藏——因为行数据按已声明的列打包
+- 基础资料列返回 `DynamicObject`；主键用 `getPkValue()` 读取
+- `getRowData(int, int, boolean)` 在 8.0 SDK 中是 `IReportListModel` 的 default 方法，所以直接在 `getReportModel()` 返回的模型上调用，无需强转。第二个参数是行数（8.0.1 参考中的 `length`）：报表示例把它说成结束行，从第 0 行开始时两者相同——从其他行开始时传 `end - start`，标品打印插件就是这样做的
+- `setSelectedAll(true)` 在查询前（`beforeQuery` 中）执行；开启后，报表示例用 `getRowData(0, reportList.getTotalRecords(), true)` 读出所有选中行
+- 要把值传给另一个页面，用打开参数的自定义参数（`report-hyperlink-drill.md`），不要用页面缓存：页面缓存只属于当前页面
+- 用户可见文本通过 `ResManager.loadKDString(文本, 资源标识, 模块)` 输出