# Windows/.NET 专属函数

文档类型：函数事实页
是否可直接用于生成代码：是；本页函数只按 Windows/.NET/COM 环境生成调用
遇到不确定时：先回到 [../index.md](../index.md) 重新确认平台；目标不是 Windows/.NET/COM 环境时再改查 [base.md](base.md)、[system.md](system.md) 或 [platform.md](platform.md)

这一页只列出 Windows/.NET/COM 专属函数。非 Windows/.NET/COM 环境不要从本页生成调用。

## 模块范围

- 说明：Windows/.NET/COM 专属函数；包含 .NET 环境辅助函数和 Windows COM/OLE 函数
- 函数事实数：12

## 基础函数

### `floatN(value, digits)`

用途：将浮点数按指定小数位数四舍五入。

参数个数：2
返回值：数值

| 参数位置 | 参数名   | 必填 | 接收类型 | 说明           |
| -------- | -------- | ---- | -------- | -------------- |
| 1        | `value`  | 是   | 实数     | 输入数值       |
| 2        | `digits` | 是   | 整数     | 保留的小数位数 |

### `floatToStrEx(value, digits)`

用途：将浮点数格式化为字符串，保留指定小数位数。

参数个数：2
返回值：字符串

| 参数位置 | 参数名   | 必填 | 接收类型 | 说明           |
| -------- | -------- | ---- | -------- | -------------- |
| 1        | `value`  | 是   | 实数     | 输入数值       |
| 2        | `digits` | 是   | 整数     | 保留的小数位数 |

### `formatFloatExt(value[, format])`

用途：按扩展格式输出数值字符串，支持千分位与空值处理。

参数个数：1 到 2
返回值：字符串

| 参数位置 | 参数名   | 必填 | 接收类型    | 说明                             |
| -------- | -------- | ---- | ----------- | -------------------------------- |
| 1        | `value`  | 是   | 数值/字符串 | 输入数值；源文档示例也传入字符串 |
| 2        | `format` | 否   | 整数        | 格式参数（可选）                 |

### `webZero(value)`

用途：当数值为 0 时返回空字符串，否则返回数值字符串。

参数个数：1
返回值：字符串

| 参数位置 | 参数名  | 必填 | 接收类型 | 说明     |
| -------- | ------- | ---- | -------- | -------- |
| 1        | `value` | 是   | 数值     | 输入数值 |

### `roundTo5(value)`

用途：将数值按 0.5 的步长进行四舍五入。

参数个数：1
返回值：数值

| 参数位置 | 参数名  | 必填 | 接收类型 | 说明     |
| -------- | ------- | ---- | -------- | -------- |
| 1        | `value` | 是   | 数值     | 输入数值 |

### `simpleRoundTo2(value, digits)`

用途：按指定小数位数进行四舍五入（对负数同样生效）。

参数个数：2
返回值：数值

| 参数位置 | 参数名   | 必填 | 接收类型 | 说明           |
| -------- | -------- | ---- | -------- | -------------- |
| 1        | `value`  | 是   | 数值     | 输入数值       |
| 2        | `digits` | 是   | 整数     | 保留的小数位数 |

### `divValue(v1, v2)`

用途：当除数不为 0 时返回 `v1 / v2`，否则返回 `0`。

参数个数：2
返回值：数值

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明   |
| -------- | ------ | ---- | -------- | ------ |
| 1        | `v1`   | 是   | 数值     | 被除数 |
| 2        | `v2`   | 是   | 数值     | 除数   |

### `dataisequal(a, b)`

用途：判断两个数据是否相等。

参数个数：2
返回值：布尔值

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明       |
| -------- | ------ | ---- | -------- | ---------- |
| 1        | `a`    | 是   | 任意值   | 待比较数据 |
| 2        | `b`    | 是   | 任意值   | 待比较数据 |

## 系统相关函数

### `getOleObject(prog_id, flags, out_obj)`

用途：获取已注册的 OLE/COM 对象实例（仅 Windows）。

参数个数：3
返回值：是否获取成功（1/0）

| 参数位置 | 参数名    | 必填 | 接收类型 | 说明                                |
| -------- | --------- | ---- | -------- | ----------------------------------- |
| 1        | `prog_id` | 是   | 字符串   | COM ProgID（如 `Word.Application`） |
| 2        | `flags`   | 是   | 整数     | 选项标记（可选，通常为 `0`）        |
| 3        | `out_obj` | 是   | 任意值   | 输出对象变量                        |

### `createComObject(guid_or_prog_id, out_obj)`

用途：创建 Windows COM 对象实例（仅 Windows COM 环境）。

参数个数：2
返回值：是否创建成功（1/0）

| 参数位置 | 参数名            | 必填 | 接收类型 | 说明                                                                                               |
| -------- | ----------------- | ---- | -------- | -------------------------------------------------------------------------------------------------- |
| 1        | `guid_or_prog_id` | 是   | 字符串   | COM ProgID 或带花括号的 CLSID；例如 `Word.Application` 或 `{000209FF-0000-0000-C000-000000000046}` |
| 2        | `out_obj`         | 是   | 任意值   | 输出对象变量；调用前通常先设为 `nil`                                                               |

生成规则：

- 函数名使用 `CreateComObject`；不要写成 `CreateComObj`。
- 必须使用双参数形式，把 COM 对象写入第二个输出变量；不要生成单参调用。
- 仅在 Windows COM 环境生成；目标机器必须安装并注册对应 COM 组件，位数、权限和 Office 自动化环境必须匹配。
- 如果创建的是 Word COM 对象，用完后按对象能力调用 `obj.Quit()`，避免留下隐藏的 `WINWORD.EXE`。
- `guid_or_prog_id` 可传 ProgID，也可传带花括号 CLSID；不要传不带花括号的裸 CLSID 字符串。

### `ifThen3(left, right, greater_value, equal_value, less_value)`

用途：比较两个值，返回大/等/小对应结果。

参数个数：5
返回值：对应比较结果的值

| 参数位置 | 参数名          | 必填 | 接收类型 | 说明                  |
| -------- | --------------- | ---- | -------- | --------------------- |
| 1        | `left`          | 是   | 任意值   | 左值                  |
| 2        | `right`         | 是   | 任意值   | 右值                  |
| 3        | `greater_value` | 是   | 任意值   | `left > right` 时返回 |
| 4        | `equal_value`   | 是   | 任意值   | `left = right` 时返回 |
| 5        | `less_value`    | 是   | 任意值   | `left < right` 时返回 |

### `safeEval(expr)`

用途：安全执行表达式或表达式字符串，执行失败返回 nil。

参数个数：1
返回值：表达式结果或 nil

| 参数位置 | 参数名 | 必填 | 接收类型 | 说明                           |
| -------- | ------ | ---- | -------- | ------------------------------ |
| 1        | `expr` | 是   | 字符串   | 表达式（@）或表达式字符串（&） |