本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Code
<a name="actions-code"></a>

Quick Automate 中的程式碼動作可讓您使用 Python 程式碼區塊實作自訂邏輯，超越標準自動化動作支援的範圍。它們非常適合複雜的資料轉換和計算，並在受限的 Python 環境中執行，以維護安全性。

**兩種類型的程式碼動作：**
+ **單行表達式：**快速的單行操作，可修改變數而不傳回值
+ **自訂程式碼區塊：**具有參數和傳回值的複雜邏輯的多行 Python 函數

**何時使用程式碼動作：**

當您需要以下項目時，請使用程式碼區塊：
+ 執行標準動作中無法使用的複雜資料轉換
+ 實作自訂商業邏輯或計算
+ 處理或操作資料結構 （清單、字典、JSON)
+ 以自訂方式使用日期、時間和時區
+ 複雜模式的剖析或格式字串
+ 透過將多個動作合併為一個程式碼區塊來最佳化自動化效能

**不使用程式碼動作時：**

在下列情況下，避免程式碼區塊：
+ 您的使用案例已存在標準自動化動作
+ 操作簡單到足以執行內建動作
+ 您需要與外部 APIs互動 （改用 REST API 整合）
+ 您需要存取檔案系統或資料庫 （使用適當的整合）

**如何存取程式碼動作：**

程式碼區塊可透過多個界面取得：
+ **動作面板 （建議）：**
  + 在自動化建置器中開啟自動化
  + 按一下右側的動作面板
  + 在程式碼動作區段下找到「自訂程式碼區塊」
  + 將程式碼區塊拖放到您的自動化工作流程
+ **使用助理建置：**
  + 當助理判斷需要自訂程式碼時，可在計劃產生期間使用
  + 助理會自動建議複雜操作的程式碼區塊
  + 您可以透過描述您的自訂邏輯需求來請求程式碼區塊

**可用的動作：**

## 單行表達式
<a name="single-line-expressions"></a>

單行表達式會執行執行操作而不傳回值的單行 Python 陳述式。它們非常適合快速修改現有變數，例如附加到清單、更新字典，或執行修改狀態的簡單計算。

**屬性：**
+ 表達式 （必要）：要執行的 Python 表達式 （例如 "my\_list.append('new item')")

**範例**：
+ **附加至清單**

  ```
  my_list.append("1")
  my_list.append(new_item)
  ```
+ **移除清單項目**

  ```
  task_list.remove(completed_task)
  ```

## 自訂程式碼區塊
<a name="custom-code-block"></a>

自訂程式碼區塊是執行複雜邏輯、接受參數和傳回值的多行 Python 函數。當標準自動化動作和單行表達式不足以滿足您的需求時，它們是備用選項。

**屬性：**
+ **函數標題 （必要）**：程式碼區塊的名稱識別符 （例如 "Calculate\_Total")
+ **函數 （必要）：**包含自訂邏輯的 Python 程式碼區塊。
  + 步驟 1：定義參數
    + 按一下「編輯」按鈕以開啟程式碼編輯器
    + 在參數面板中，按一下「新增」以建立新的參數
    + 輸入符合您自動化變數的參數名稱
    + 參數可作為函數引數使用
  + 步驟 2：撰寫您的 Python 程式碼
+ **傳回值 （選用）：**儲存函數輸出的變數名稱
  + 遵循必要的程式碼區塊結構 （請參閱下文）
  + 在 函數中實作您的自訂邏輯
  + 僅使用核准的程式庫和內建函數
  + 如果您需要輸出資料，請包含傳回陳述式

**程式碼區塊結構**

所有程式碼區塊必須遵循此特定格式：

```
@code_block()
def your_function_name(parameter1, parameter2, parameter3):
-------------------------------------------------------------------------------------
    """
    Optional: Add a docstring describing what your function does
    """
    # Your custom logic here
    result = parameter1 + parameter2 + parameter3

    return result
```

**內建 Python 函數和匯入**

所有標準 Python 內建函數都可以在沒有匯入的情況下使用 (len、str、int 等）

**核准的標準程式庫 （受安全性限制）**

程式碼區塊只能匯入下列標準程式庫：
+ `base64` - Base64 編碼/解碼
+ `datetime` - 日期和時間操作
+ `json` - JSON 剖析和產生
+ `math` - 數學函數
+ `re` - 規則表達式
+ `zoneinfo` - 時區處理

**注意**  
無法匯入上面列出的標準程式庫以外的標準程式庫。
無法安裝或匯入第三方程式庫。程式碼區塊`pip install`不支援 。

**限制**
+ 具有有限程式庫存取權的受限 Python 環境。執行環境是以 RestrictedPython 為基礎，這是 Python 3.10 的子集。
+ 程式碼區塊無法叫用其他程式碼區塊或動作

**最佳實務**
+ 保持程式碼區塊簡單且專注
+ 使用描述性函數名稱
+ 在可用時，一律偏好預先建置的動作
+ 徹底測試程式碼區塊，因為重點偵錯選項有限）

**範例 ** 使用案例
+ 數學運算 （計算圓形屬性 - 半徑作為參數

  ```
  def function
  (radius):
  
      return {
          "radius": radius,
          "diameter": 2 * radius,
          "circumference": round(2 * math.pi * radius, 2),
          "area": round(math.pi * radius ** 2, 2)
      }
  ```
+ 取得目前日期/時間

  ```
  def function
  ():
  
      now = datetime.datetime.now()
  
      return {
          "current_date": now.strftime("%Y-%m-%d"),
          "current_time": now.strftime("%H:%M:%S"),
          "formatted": now.strftime("%B %d, %Y at %I:%M %p"),
          "iso_format": now.isoformat(),
          "timestamp": now.timestamp()
      }
  ```
+ 計算日期差異 - 開始日期和結束日期作為參數

  ```
  def function
  _(start_date_str, end_date_str):
  
  # Parse date strings (format: YYYY-MM-DD)_
      start = datetime.datetime.strptime(start_date_str, "%Y-%m-%d")
      end = datetime.datetime.strptime(end_date_str, "%Y-%m-%d")
  
      _# Calculate difference_
      difference = end - start
      return {
          "days": difference.days,
          "weeks": difference.days // 7,
          "start": start_date_str,
          "end": end_date_str    }
  ```
+ 使用規則表達式的模式比對和文字處理 （驗證電子郵件地址、電話號碼等）

  ```
  def function
  (email, phone, zip_code):
  
      email_pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
      phone_pattern = r'^\d{3}-\d{3}-\d{4}$'
      zip_pattern = r'^\d{5}(-\d{4})?$'
  
      return {
          "email_valid": bool(re.match(email_pattern, email)),
          "phone_valid": bool(re.match(phone_pattern, phone)),
          "zip_valid": bool(re.match(zip_pattern, zip_code))
      }
  ```
+ 清單操作 （篩選條件和轉換清單）

  ```
  def function
  (numbers, threshold):
  
      # Filter numbers above threshold and calculate statistics
      filtered = [n for n in numbers if n > threshold]
  
      if filtered:
          return {
              "filtered_numbers": filtered,
              "count": len(filtered),
              "sum": sum(filtered),
              "average": sum(filtered) / len(filtered),
              "min": min(filtered),
              "max": max(filtered)
          }
      else:
          return {
              "filtered_numbers": [],
              "count": 0,
              "message": "No numbers above threshold"
          }
  ```