# kingdee.extensions

**Repository Path**: yeahfeng/kingdee.extensions

## Basic Information

- **Project Name**: kingdee.extensions
- **Description**: 金蝶云星空（K3 Cloud）二次开发扩展类库。
面向金蝶云星空 BOS 插件、WebApi 服务、报表服务等场景，提供一批开箱即用的扩展方法，
用于简化单据操作、字段取值、控件操作、下推/选单、报表查询、WebApi 调用等高频开发动作。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dihl.Kingdee.Extensions

金蝶云星空（K3 Cloud）二次开发扩展类库。

> 面向金蝶云星空 BOS 插件、WebApi 服务、报表服务等场景，提供一批开箱即用的扩展方法，
> 用于简化单据操作、字段取值、控件操作、下推/选单、报表查询、WebApi 调用等高频开发动作。

## 目录

- [初衷](#初衷)
- [环境要求](#环境要求)
- [如何引用](#如何引用)
- [功能一览](#功能一览)
- [使用示例](#使用示例)
  - [单据加载、赋值、保存](#1-单据加载赋值保存)
  - [单据提交、审核](#2-单据提交审核)
  - [自动下推](#3-自动下推)
  - [单据体下推](#4-单据体下推)
  - [一串操作一气呵成：OperationSeries](#5-一串操作一气呵成operationseries)
  - [单据字段快速取值](#6-单据字段快速取值)
  - [视图控件操作](#7-视图控件操作)
  - [弹出单据 / 动态表单 / 列表](#8-弹出单据--动态表单--列表)
  - [WebApi 调用](#9-webapi-调用)
  - [SQL 查询](#10-sql-查询)
  - [报表取数](#11-报表取数)
  - [系统参数](#12-系统参数)
  - [发送消息](#13-发送消息)
- [常量定义](#常量定义)
- [多版本支持](#多版本支持)

---

## 初衷

在使用金蝶云星空 BOS 进行二次开发时，经常需要编写大量重复的样板代码：

- 保存、提交、审核单据时，要手动组装 `OperateOption`（忽略警告、忽略交互弹窗）；
- 判断操作结果是否成功、取出错误信息，每次都要写一堆 `GetFatalErrorResults` 的遍历代码；
- 从 `DynamicObject` / 单据视图取值时，要写繁琐的判空、转换代码；
- 自动下推时，要手动创建 `ListSelectedRow`、查询转换规则、组装 `PushArgs`；
- 配置了工作流模板的单据，提交还得分情况处理，否则直接 `Submit` 会失败。

本类库将这些高频、易错的操作封装成简单直观的扩展方法，让开发者只需关心业务本身，
几行代码即可完成“加载 → 赋值 → 保存 → 提交 → 审核”的完整链路，同时统一了
“忽略警告 / 忽略交互弹窗”等行为，避免因弹窗或警告导致的后台操作失败。

## 环境要求

- .NET Framework 4.0 及以上
- 金蝶云星空 K3Cloud 运行环境（引用 `Kingdee.BOS.*` 系列程序集）
- 可选依赖：`Newtonsoft.Json`、`BouncyCastle.Crypto`

## 如何引用

将 `code/Dihl.Kingdee.Extensions` 项目（或编译出的 `Dihl.Kingdee.Extensions.dll`）加入你的插件工程即可。
所有扩展方法均在命名空间 `Kingdee.BOS.CD` 下：

```csharp
using Kingdee.BOS.CD;
```

类库默认将编译产物输出到 `K3Cloud/bin/` 目录，方便直接部署。

## 功能一览

| 分类 | 主要扩展 | 说明 |
| ---- | ---- | ---- |
| 单据操作 | `BillExtensions` / `BillSaveExtensions` / `BillSubmitExtensions` / `BillAuditExtensions` / `BillUnAuditExtensions` / `BillDeleteExtensions` / `BillEnableExtensions` / `BillForbidExtensions` / `BillDraftExtensions` | 创建视图、加载数据、暂存/保存/提交/审核/反审核/删除/禁用/反禁用，自动处理工作流模板与操作选项 |
| 下推 / 选单 | `BillPushExtensions` / `BillDrawExtensions` | 整单下推、指定单据体下推、选单，自动查找转换规则 |
| 批量操作 | `BillOperationSeriesExtensions` / `ProcessOperationType` | 一次调用按顺序执行 暂存→保存→提交→审核 |
| 字段取值 | `DynamicObjectExtensions` / `BillValueExtensions` / `DynamicFormViewValueExtensions` | 从数据包、视图取各类类型字段值，含基础资料、多选基础资料 |
| 视图控件 | `DynamicFormViewControllExtensions` | 设置控件值/可见/可用/宽高/颜色/图片等 |
| 弹出界面 | `DynamicFormViewShowViewExtensions` / `ShowParameter` | 弹出动态表单、单据、列表、移动端界面 |
| WebApi | `WebApiServiceCallExtensions` | 服务内调用保存/提交/审核/下推/分配/查询 |
| WebApi 服务 | `MyAbstractWebApiBusinessService` / `WebApiUnifyResult` | WebApi 服务基类与统一返回结构 |
| 数据库 | `DBUtilsExtensions` | 执行 SQL、批量执行、临时表、批量插入/更新 |
| 报表 | `ReportExtensions` 及各类 `*ReportExtensions` / `ReportVo` | 获取报表过滤模型、报表数据、报表临时表清理 |
| 系统参数 | `SystemParamerExtensions` | 获取系统参数 |
| 消息 | `SMSExtensions` | 发送站内消息 |
| 加密 | `Crypto/AES.cs`、`Crypto/AesCrypto.cs`、`Crypto/MD5.cs` | AES、MD5 加解密 |
| 时间 | `DateTimeExtensions` / `TimeExtensions` | 日期时间辅助 |
| 其他 | `DataRowExtensions` / `StringExtensions` / `ENGRouteExtensions` / `OperationReportExtensions` / `OperationResultExtensions` / `ConvertRuleExtensions` / `OrganizationExtensions` / `NetWorkCtrlRecordsExtensions` / `FormMetadataExtensions` | 各类便捷方法 |
| 常量 | `BillIdDefine` / `CdFormIdConst` / `FieldIdDefine` / `BillStatus` / `OperationNumber` / `ProcessOperationType` / `EnumFinType` / `EnumReportType` / `HttpMethod` | 单据标识、字段、状态、操作类型等常量定义 |

## 使用示例

### 1. 单据加载、赋值、保存

```csharp
// 创建一张新单据视图
IBillView bill = Context.CreateBillView("SAL_SaleOrder");

// 按内码加载已有单据
bill.Model.DataObject = Context.LoadSingle(bill, 100123);

// 单据头赋值
bill.SetValue("FApproveDate", DateTime.Today);
bill.SetValue("FNote", "备注说明");

// 基础资料赋值（支持 内码 / 编码 两种方式）
bill.SetItemValueByID("FSupplierId", 123456);
bill.SetItemValueByNumber("FMaterialId", "M001");

// 单据体新增一行并赋值
var entry = bill.Model.GetEntity("FEntity").DynamicObjectCollection.CreateDynamicObject();
entry.SetValue("FMaterialId", 123456);
entry.SetValue("FQty", 10);

// 保存
var result = bill.Save();
if (!result.IsSuccess())
{
    var msg = result.GetErrorMsg();   // 失败时取出错误信息
}
```

也可以不经过视图，直接用 `Context` 保存数据包：

```csharp
var dodo = Context.CreateDynamicObjectByFormId("SAL_SaleOrder");
// ... 给 dodo 赋值 ...
var result = Context.Save("SAL_SaleOrder", dodo);
```

### 2. 单据提交、审核

```csharp
// 提交：自动判断单据是否配置工作流模板，配置了走工作流提交
var submitResult = bill.Submit();

// 不带视图，直接用内码提交 / 审核
var submitResult2 = Context.Submit(bill.BusinessInfo, 100123);
var auditResult  = Context.Audit(bill.BusinessInfo, 100123);

// 支持批量
var auditResult2 = Context.Audit(bill.BusinessInfo, new object[] { 100123, 100124, 100125 });
```

> 内部已统一 `SetIgnoreWarning(true)` 与 `SetIgnoreInteractionFlag(true)`，
> 后台操作不会再被“警告确认”或“交互式弹窗”卡住。

### 3. 自动下推

```csharp
// 整单下推：销售订单 → 销售出库单
ConvertOperationResult result = Context.DoPush(
    "SAL_SaleOrder",
    new List<long> { 100123, 100124 },
    "SAL_OUTSTOCK",
    "",        // targetBillTypeId，留空使用默认单据类型
    "");       // ruleKey，留空自动找默认/第一个转换规则

// 取出下推生成的下游单据数据包
List<DynamicObject> targetBills = result.GetPushTargetData();
```

### 4. 单据体下推

```csharp
// 只下推销售订单的指定单据体行
ConvertOperationResult result = bill.DoPush(
    "FEntity",                     // 单据体标识
    new List<long> { 140032, 140033 },  // 单据体行内码
    "SAL_OUTSTOCK");
```

### 5. 一串操作一气呵成：OperationSeries

```csharp
// 暂存 + 保存 + 提交 + 审核，一步到位；任一步失败即中断并返回
ProcessOperationResult result = Context.OperationSeries(
    "SAL_SaleOrder",
    dataObject,
    ProcessOperationType.ProcDraft | ProcessOperationType.ProcSave
        | ProcessOperationType.ProcSubmit | ProcessOperationType.ProcAudit);

if (!result.IsSuccess)
{
    Logger.Info("OperationSeries 失败，当前步骤：" + result.CurType);
}
```

### 6. 单据字段快速取值

从 `DynamicObject` 取值（自动判空与类型转换，不会抛异常）：

```csharp
long   orderId = dataObject.GetId();              // 单据内码
string billNo  = dataObject.GetBillNo();          // 单据编号
string status  = dataObject.GetDocumentStatus();  // 单据状态

decimal qty = entry.GetDecimal("FQty");
DateTime date = entry.GetDateTime("FDate");
long supplierId = entry.GetObjectLong("FSupplierId");   // 基础资料内码
string materialNumber = entry.GetObjectString("FMaterialId", "Number"); // 基础资料编码
```

从单据视图取值（含单据体行）：

```csharp
string note = view.GetString("FNote");
decimal qty = view.GetDecimal("FQty", 0);   // 第 0 行
long supplierId = view.GetObjectLong("FSupplierId");
```

多选基础资料：

```csharp
List<long> ids = dataObject.GetMultiObjectLong("FMultMaterials", "Id", 0);
```

### 7. 视图控件操作

```csharp
view.SetCtrlValue("FNote", "hello");
view.SetCtrlVisible("FBtn", false);
view.SetCtrlEnabled("FEdit", false);
view.SetCtrlWidth("FPanel", 300);
view.SetCtrlForecolor("FEdit", "#FF0000");
view.SetCtrlBackcolor("FEdit", "#FFFF00");
view.SetCtrlImage("FPic", "/image/logo.png");
view.SetCtrlListEditable("FEntity", false);   // 单据体整单只读
```

### 8. 弹出单据 / 动态表单 / 列表

```csharp
// 弹出动态表单并传参、回调
view.ShowFormNormal("MY_SimpleForm", new Dictionary<string, object>
{
    { "BizId", 100123 }
}, (formResult) =>
{
    // 处理返回结果
});

// 弹出指定单据（只读查看）
view.ShowBillFormNormal("SAL_SaleOrder", 100123, OperationStatus.VIEW);

// 弹出列表并回调选择结果
view.ShowListFormNormal(new NormalListShowParameter
{
    FormId = "SAL_SaleOrder",
    MultiSelect = true,
    Filter = "FDATE >= '2024-01-01'"
}, (rows) =>
{
    // rows: ListSelectedRowCollection 选中的行
});
```

### 9. WebApi 调用

在服务端代码中直接复用 WebApi 的服务实现：

```csharp
// 保存
var ret = Context.ApiSave("SAL_SaleOrder", new ApiSaveVo
{
    CreateOrgId = 0,
    Model = billDataJson  // 单据数据 JSON
});

// 提交
var ret2 = Context.ApiSubmit("SAL_SaleOrder", new ApiSubmitVo
{
    CreateOrgId = 0,
    Numbers = new List<string> { "SO20240001" }
});

// 审核
var ret3 = Context.ApiAudit("SAL_SaleOrder", new ApiAuditVo
{
    CreateOrgId = 0,
    Ids = new List<long> { 100123 }
});

// 查询
List<List<object>> rows = Context.ApiExecuteBillQuery(new ApiBillQueryVo
{
    FieldKeys = "FBillNo,FDate,FSupplierId.FNumber",
    FilterString = "FBillNo = 'SO20240001'",
    Limit = 100
});

if (ret.Result.ResponseStatus.IsSuccess)
{
    // 成功
}
```

如果是在**自定义 WebApi 服务**中，可以继承封装好的基类，并使用统一返回结构：

```csharp
[ServiceExport]
public class MyService : MyAbstractWebApiBusinessService
{
    public MyService(KDServiceContext context) : base(context) { }

    public string DoSomething()
    {
        var check = CheckContext();        // 校验登录状态
        if (check != null)
            return JsonConvert.SerializeObject(check);

        var result = WebApiUnifyResultProvider.OnSuccess("操作成功");
        return JsonConvert.SerializeObject(result);
    }
}
```

### 10. SQL 查询

```csharp
// 查询数据包集合
var docs = Context.ExecuteDynamicObject("/*dialect*/select * from T_SAL_SaleOrder where FID = 100123");

// 查询单值（带默认值，不会抛异常）
int count = Context.ExecuteScalar<int>(
    "/*dialect*/select count(1) from T_SAL_SaleOrder", 0);

// 执行非查询
int affected = Context.Execute("/*dialect*/update ... ");

// 批量执行
Context.ExecuteBatch(sqlList, 500);

// 临时表
var tempTable = Context.CreateTemporaryTableName();
Context.DropTempTable(tempTable);
```

### 11. 报表取数

```csharp
// 获取报表过滤模型
var model = Context.GetReportFilterModel(
    "HS_INOUTSTOCKSUMMARYRPT",    // 报表标识
    "HS_INOUTSTOCKSUMMARYFILTER"); // 过滤框标识

// 加载默认方案后取数
var reportData = Context.GetReportData(model, filterParameter, EnumReportType.Report);

// 取报表临时表名，可直接用 SQL 读取明细
string tableName = reportData.GetReportTableName();

// 用完记得释放临时表
reportData.Dispose();
```

### 12. 系统参数

```csharp
string param = Context.GetSystemParamterString(
    orgId, "SAL_SaleOrder", "SalesOrderParam", acctBookId);
```

### 13. 发送消息

```csharp
Context.SendMessageGeneral(
    "SAL_SaleOrder",   // 相关单据标识
    100123,            // 单据内码
    "标题",
    "消息内容",
    senderId,          // 发送人
    receiverId);       // 接收人
```

## 常量定义

| 常量类 | 说明 |
| ---- | ---- |
| `CdFormIdConst` | 常用单据标识，如 `物料 = "BD_MATERIAL"`、`销售订单 = "SAL_SaleOrder"`、`生产订单 = "PRD_MO"` 等 |
| `BillIdDefine` | 单据标识常量（消息单、报表、核算体系等） |
| `FieldIdDefine` | 常用字段标识，如 `DocumentStatus = "FDocumentStatus"` |
| `BillStatus` | 单据状态值，如 `Audit = "C"`（已审核）、`Submit = "B"`（审核中） |
| `OperationNumber` | 操作编号，如 `Save` / `Submit` / `Audit` / `UnAudit` |
| `ProcessOperationType` | 批量操作类型（位枚举）：`ProcDraft` / `ProcSave` / `ProcSubmit` / `ProcAudit` |
| `EnumFinType` / `EnumReportType` | 财务类型 / 报表类型 |
| `HttpMethod` | HTTP 方法常量 |

## 多版本支持

工程通过不同的编译配置适配多个云星空版本，并在代码中用条件编译符号区分实现：

| 配置 | 条件编译符号 | 说明 |
| ---- | ---- | ---- |
| Debug / Release | （无） | 默认版本 |
| `7_3_Debug` / `7_3_Release` | `K3_7_3` | 7.3 版本（该版本未提供工作流模板提交接口） |
| `8_2_Debug` / `8_2_Release` | `K3_8_2_20240104` | 8.2 版本 |
| `9_0_Debug` | `K3_9_0` | 9.0 版本 |

例如 7.3 版本没有 `MFGCommonUtil.SubmitWithWorkFlow` 接口，类库会在 `K3_7_3` 编译符号下直接抛出明确提示，避免误用。