本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 代码
<a name="actions-code"></a>

Quick Automate 中的代码操作允许您使用 Python 代码块实现自定义逻辑，这超出了标准自动化操作所支持的范围。它们非常适合复杂的数据转换和计算，并且可以在受限的 Python 环境中运行以维护安全。

**两种类型的代码操作：**
+ **单行表达式：**快速的单行操作，可在不返回值的情况下修改变量
+ **自定义代码块：**用于带有参数和返回值的复杂逻辑的 Multi-line Python 函数

**何时使用代码操作：**

在需要时使用代码块：
+ 执行标准操作中不提供的复杂数据转换
+ 实现自定义业务逻辑或计算
+ 处理或操作数据结构（列表、字典、JSON）
+ 以自定义方式处理日期、时间和时区
+ 解析或格式化具有复杂模式的字符串
+ 通过将多个操作整合到一个代码块中来优化自动化性能

**何时不使用代码操作：**

在以下情况下避免使用代码块：
+ 您的用例已经存在标准自动化操作
+ 该操作非常简单，可以进行内置操作
+ 你需要与外部 API 进行交互（改用 REST API 集成）
+ 您需要访问文件系统或数据库（使用适当的集成）

**如何访问代码操作：**

代码块可通过多个接口使用：
+ **操作面板（推荐）：**
  + 在自动化生成器中打开您的自动化
  + 点击右侧的动作面板
  + 在 “代码操作” 部分下找到 “自定义代码块”
  + 将代码块拖放到您的自动化工作流程中
+ **使用助手构建：**
  + 当助手确定需要自定义代码时，可在计划生成期间使用
  + 助手会自动为复杂操作推荐代码块
  + 您可以通过描述您的自定义逻辑需求来请求代码块

**可用操作：**

## 单行表达式
<a name="single-line-expressions"></a>

单行表达式执行单行 Python 语句，这些语句在不返回值的情况下执行操作。它们非常适合快速修改现有变量，例如追加到列表、更新字典或执行修改状态的简单计算。

**特性：**
+ 表达式（必填）：要执行的 Python 表达式（例如，“my\_list.append（'新项目'）”）

**示例：**
+ **追加到清单**

  ```
  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
```

**Built-in Python 函数和导入**

所有标准的 Python 内置函数都无需导入即可使用（len、str、int 等）

**已批准的标准库（安全性受限）**

代码块只能导入以下标准库：
+ `base64`-Base64 encoding/decoding
+ `datetime`-日期和时间操作
+ `json`-JSON 解析和生成
+ `math`-数学函数
+ `re`-正则表达式
+ `zoneinfo`-时区处理

**注意**  
无法导入除上面列出的标准库之外的标准库。
无法安装或导入第三方库。 `pip install`在代码块中不支持。

**限制**
+ Python 环境受限，库访问权限有限。执行环境基于 Python 3.10 的一个子集。 RestrictedPython
+ 代码块无法调用其他代码块或操作

**最佳实践**
+ 保持代码块的简单性和针对性
+ 使用描述性函数名称
+ 如果可用，请始终首选预先构建的操作
+ 彻底测试您的代码块（因为有针对性的调试选项有限）

**使用案例**示例
+ 数学运算（计算圆形属性-半径作为参数

  ```
  def function
  (radius):
  
      return {
          "radius": radius,
          "diameter": 2 * radius,
          "circumference": round(2 * math.pi * radius, 2),
          "area": round(math.pi * radius ** 2, 2)
      }
  ```
+ 获取最新消息 date/time

  ```
  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"
          }
  ```