Raycast脚本命令中的参数使用详解

什么是脚本参数

在Raycast脚本命令中，参数(Arguments)是一种强大的功能，它允许用户在执行脚本时输入自定义内容。通过参数，你可以创建更加灵活和交互式的脚本命令，比如设置待办事项、执行特定搜索或传递配置信息等。

参数的基本配置

要为脚本添加参数，需要在脚本的元数据中使用argument[1..3]声明。每个参数都是一个JSON对象，包含多个配置字段：

#!/bin/bash

# @raycast.argument1 { "type": "text", "placeholder": "输入搜索内容" }

参数类型(type)

Raycast支持三种参数类型：

1. text：普通文本输入框
2. password：密码输入框（输入内容会显示为星号）
3. dropdown：下拉选择框

常用配置字段

配置项	说明	是否必填	适用版本
type	参数类型(text/password/dropdown)	是	1.64.0+
placeholder	输入框占位提示文字	是	1.2.0+
optional	是否可选参数(默认false)	否	1.3.0+
percentEncoded	是否对参数值进行URL编码	否	1.4.0+
data	下拉选项数据(仅dropdown类型需要)	条件必填	1.64.0+

参数类型详解

1. 文本输入参数

最基本的参数类型，适用于大多数需要用户输入的场景：

# @raycast.argument1 { 
#   "type": "text", 
#   "placeholder": "输入城市名称",
#   "percentEncoded": true
# }

2. 密码输入参数

当需要输入敏感信息时使用，输入内容会被隐藏：

# @raycast.argument1 { 
#   "type": "password", 
#   "placeholder": "输入API密钥"
# }

3. 下拉选择参数

提供预定义的选项供用户选择，适合有限选项的场景：

# @raycast.argument1 {
#   "type": "dropdown",
#   "placeholder": "选择语言",
#   "data": [
#     {"title": "中文", "value": "zh"},
#     {"title": "English", "value": "en"}
#   ]
# }

参数使用技巧

1. 参数数量限制：目前最多支持3个参数，如需更多可考虑使用交互式脚本

2. 自动聚焦：输入脚本别名后按空格，Raycast会自动将焦点移到第一个输入框

3. URL编码：对于需要直接拼接到URL中的参数，建议启用percentEncoded

4. 可选参数：合理使用optional标记非必要参数，提升用户体验

实际应用示例

下面是一个完整的航班搜索脚本示例，展示了两个参数的用法：

#!/bin/bash

# 必需参数
# @raycast.schemaVersion 1
# @raycast.title 航班搜索
# @raycast.mode silent

# 可选参数
# @raycast.icon ✈️
# @raycast.packageName 网络搜索

# 参数配置
# @raycast.argument1 { 
#   "type": "text", 
#   "placeholder": "出发城市", 
#   "percentEncoded": true 
# }
# @raycast.argument2 { 
#   "type": "text", 
#   "placeholder": "到达城市", 
#   "optional": true, 
#   "percentEncoded": true 
# }

# 脚本逻辑
if [ -z "$2" ]; then
  open "https://www.google.com/search?q=flights%20from%20$1"
else
  open "https://www.google.com/search?q=flights%20from%20$1%20to%20$2"
fi

最佳实践建议

1. 清晰的占位文本：使用简洁明了的placeholder说明参数用途

2. 合理的参数顺序：将必填参数放在前面，可选参数放在后面

3. 类型选择：根据输入内容性质选择合适的参数类型

4. 错误处理：在脚本中对参数进行验证，提供友好的错误提示

5. 性能考虑：对于dropdown类型，避免加载过多选项影响性能

通过合理使用参数功能，你可以创建出更加灵活、用户友好的Raycast脚本命令，极大提升工作效率。