> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 编码/解码格式化器

> ArcScript 中用于编码、解码、哈希和转义字符串值的格式化器。

## base64decode(\[outputencoding])

将属性值转换为 Base64 解码字符串。

格式化器会将 Base64 值解码为字节，然后按 **outputencoding** 指定的编码返回这些字节。

* **outputencoding**：可选字符串，用于指定输出编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。
  * `utf-8`：以 UTF-8 文本形式返回解码后的字节。
  * `hex`：以大写十六进制字符串形式返回解码后的字节。
  * `base64`：以 Base64 字符串形式返回解码后的字节。

如果解码后的值是二进制数据（例如 GUID 或哈希值），请使用 `hex` 或 `base64`。如果格式化器以 `utf-8` 返回不是有效 UTF-8 文本的字节，这些字节会损坏。

### 示例

以下示例解码 Base64 值，并以十六进制字符串形式返回结果。

```xml theme={null}
['dGVzdA==' | base64decode('hex')]
```

此代码返回 `74657374`。

## base64encode(\[inputencoding])

将属性值转换为 Base64 编码字符串。

格式化器会使用 **inputencoding** 指定的编码将值转换为字节，然后对这些字节进行 Base64 编码。

* **inputencoding**：可选字符串，用于指定输入编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。
  * `utf-8`：将值视为 UTF-8 文本。
  * `hex`：将值视为十六进制字符串。值的字符数必须为偶数，否则格式化器会失败并报错“Invalid HEX-encoded data.”。
  * `base64`：将值视为 Base64 字符串。

### 示例

以下示例对十六进制字符串进行 Base64 编码。

```xml theme={null}
['74657374' | base64encode('hex')]
```

此代码返回 `dGVzdA==`。

以下示例生成 Base64 格式的 GUID。`guid(false)` 调用返回不带短划线的 GUID，因此它是有效的十六进制字符串。

```xml theme={null}
[guid(false) | base64encode('hex')]
```

此代码返回类似 `mIikiosjR421TscXkTXfVg==` 的值。当脚本需要生成大量 GUID 时，这种方法比使用 [encDecode](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/operations/op-enc-decode.md) 操作逐个转换值要快得多。

## csvescape()

从匹配值的列返回 CSV 数据，并将每个元素作为单独结果输出。

### 示例

在以下示例中，[csv 函数](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/function-formatters.md#csv-value) 和 `csvescape` 选项都会从示例 CSV 文档中输出。

```xml theme={null}
<arc:call op="csvListRecords">
Standard output: [csv('column1')], [csv('column2')], [csv('column3')]
Output with csvescape(): [csv('column1') | csvescape()], [csv('column2') | csvescape()], [csv('column3') | csvescape()]
</arc:call>
```

运行此代码会显示 CSV 标题下第一行的以下输出。

```
Standard output: entry1, entry2, entry3
Output with csvescape(): "entry1", "entry2", "entry3"
```

## hexdecode(\[outputencoding])

将属性值转换为十六进制解码字符串。

格式化器会将十六进制值解码为字节，然后按 **outputencoding** 指定的编码返回这些字节。空值返回空结果。字符数为奇数的十六进制值会失败并报错“Invalid HEX-encoded data.”。

* **outputencoding**：可选字符串，用于指定输出编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。
  * `utf-8`：以 UTF-8 文本形式返回解码后的字节。
  * `hex`：以大写十六进制字符串形式返回解码后的字节。
  * `base64`：以 Base64 字符串形式返回解码后的字节。

### 示例

以下示例解码十六进制值，并以 Base64 字符串形式返回结果。

```xml theme={null}
['9888a48a8b23478db54ec7179135df56' | hexdecode('base64')]
```

此代码返回 `mIikiosjR421TscXkTXfVg==`。

## hexencode(\[uppercase]\[, inputencoding])

将属性值转换为十六进制编码字符串。

格式化器会使用 **inputencoding** 指定的编码将值转换为字节，然后对这些字节进行十六进制编码。空值返回空结果。

* **uppercase**：可选布尔值，用于指定是否使用大写十六进制字符。默认值为 `true`。将此值设置为 `false` 可返回小写十六进制。
* **inputencoding**：可选字符串，用于指定输入编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。
  * `utf-8`：将值视为 UTF-8 文本。
  * `hex`：将值视为十六进制字符串。值的字符数必须为偶数，否则格式化器会失败并报错“Invalid HEX-encoded data.”。
  * `base64`：将值视为 Base64 字符串。

> [!NOTE]
>
> **inputencoding** 是第二个参数，因此要使用它，还必须传入 **uppercase**。例如，`hexencode('base64')` 不会设置输入编码，格式化器会将 `'base64'` 读取为 **uppercase** 的值。请使用 `hexencode(false, 'base64')` 或 `hexencode(true, 'base64')`。

### 示例

以下示例对 Base64 值进行十六进制编码，并返回小写十六进制。

```xml theme={null}
['mIikiosjR421TscXkTXfVg==' | hexencode(false, 'base64')]
```

此代码返回 `9888a48a8b23478db54ec7179135df56`。

以下示例使用 `iso-8859-1` 字符编码对文本进行十六进制编码。

```xml theme={null}
['é' | hexencode(true, 'iso-8859-1')]
```

此代码返回 `E9`。

## jsonescape()

将属性值转换为 JSON 转义的单行字符串。

## md5hash(\[encodetobase64]\[, inputencoding])

计算属性值的 MD5 哈希值。

* **encodetobase64**：可选布尔值，用于指定是否将结果转换为 Base64 编码字符串。默认值为 `true`。
* **inputencoding**：可选字符串，用于指定输入编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。

## sha1hash(\[encodetobase64]\[, inputencoding])

计算属性值的 SHA-1 哈希值。

* **encodetobase64**：可选布尔值，用于指定是否将结果转换为 Base64 编码字符串。默认值为 `true`。
* **inputencoding**：可选字符串，用于指定输入编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。

## sha2hash(\[algorithm]\[, encodetobase64]\[, inputencoding])

计算属性值的 SHA-2 哈希值。

* **algorithm**：可选字符串，用于指定要使用的 SHA-2 算法。允许的值为 `SHA-256`、`SHA-384` 或 `SHA-512`。默认值为 `SHA-256`。
* **encodetobase64**：可选布尔值，用于指定是否将结果转换为 Base64 编码字符串。默认值为 `true`。
* **inputencoding**：可选字符串，用于指定输入编码。允许的值为 `utf-8`、`hex`、`base64` 或其他字符编码的名称（例如 `iso-8859-1`）。这些值不区分大小写。默认值为 `utf-8`。

## sqlescape()

将属性值转换为 SQL 转义的单行字符串。

* **dbtype**：要编码的数据库类型。允许的值为 `SQL` 或 `SQLite`。默认值为 `SQL`。

## urldecode()

将属性值转换为 URL 解码字符串。

## urlencode()

将属性值转换为 URL 编码字符串。

## xmldecode()

将属性值转换为 XML 解码字符串。

## xmlencode()

将属性值转换为 XML 编码字符串。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.