> ## 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-Hant/scripting/operations/op-enc-decode.md) 操作逐一轉換值要快得多。

## csvescape()

從匹配值的列傳回 CSV 資料，並將每個元素作為單獨結果輸出。

### 範例

在以下範例中，[csv 函式](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/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.