配置面板 (settings)

配置面板允许您为脚本添加可视化的配置表单，用户可以在 iClick 控制台中方便地修改这些配置，无需手动编辑配置文件。

基本用法

在 manifest.json 中添加 settings 字段：

{
  "settings": [
    {
      "key": "api_url",
      "name": "API 地址",
      "type": "text",
      "value": "https://api.example.com",
      "placeholder": "请输入 API 地址",
      "require": true
    }
  ]
}

通用字段说明

每个配置项都支持以下字段：

字段	类型	必需	说明
key	string	✅	配置项唯一标识符，用于在程序中读取配置值
name	string	✅	配置项显示名称，会显示在配置表单中
type	string	✅	配置项类型（见下方类型列表）
value	any	✅	默认值，类型应与 type 匹配
placeholder	string	可选	输入框占位符文本
require	boolean	可选	是否必填，默认为 false

配置类型

text - 单行文本框

适用于短文本输入，如 API Key、URL 等。

{
  "key": "api_key",
  "name": "API 密钥",
  "type": "text",
  "value": "",
  "placeholder": "请输入 API 密钥",
  "require": true
}

---

number - 数字输入框

适用于数字输入，如端口号、超时时间等。

{
  "key": "timeout",
  "name": "超时时间（秒）",
  "type": "number",
  "value": 30,
  "placeholder": "输入超时秒数"
}

---

checkbox - 复选框

适用于布尔值（开/关）选项。

{
  "key": "enable_log",
  "name": "启用日志",
  "type": "checkbox",
  "value": true
}

---

select - 下拉选择框

适用于从预定义选项中选择一个值。

{
  "key": "mode",
  "name": "运行模式",
  "type": "select",
  "value": "auto",
  "options": [
    { "label": "自动模式", "value": "auto" },
    { "label": "手动模式", "value": "manual" },
    { "label": "调试模式", "value": "debug" }
  ]
}

特殊字段：

• options: 选项数组，每个选项包含 label（显示文本）和 value（实际值）

---

textarea - 多行文本框

适用于长文本或多行内容输入。

{
  "key": "config_content",
  "name": "配置文件内容",
  "type": "textarea",
  "value": "",
  "placeholder": "输入配置文件内容（JSON 或其他格式）"
}

---

file - 文件选择器

允许用户选择一个文件。

{
  "key": "cert_file",
  "name": "证书文件",
  "type": "file",
  "value": "",
  "placeholder": "选择证书文件"
}

---

path - 文件夹选择器

允许用户选择一个文件夹路径。

{
  "key": "output_dir",
  "name": "输出目录",
  "type": "path",
  "value": "",
  "placeholder": "选择输出目录"
}

---

date - 日期选择器

允许用户选择日期。

{
  "key": "start_date",
  "name": "开始日期",
  "type": "date",
  "value": "2024-01-01",
  "placeholder": "选择开始日期"
}

值格式： YYYY-MM-DD

---

time - 时间选择器

允许用户选择时间。

{
  "key": "backup_time",
  "name": "备份时间",
  "type": "time",
  "value": "02:00:00",
  "placeholder": "选择备份时间"
}

值格式： HH:mm:ss

---

datetime - 日期时间选择器

允许用户选择日期和时间。

{
  "key": "schedule_time",
  "name": "计划执行时间",
  "type": "datetime",
  "value": "2024-01-01 12:00:00",
  "placeholder": "选择执行时间"
}

值格式： YYYY-MM-DD HH:mm:ss

配置文件自动生成

当用户在 iClick 控制台中修改并保存配置后，系统会自动在脚本包目录下生成 settings.json 文件。

文件位置：

%APPDATA%/iClick/Scripts/com.example.myscript/settings.json

生成的配置文件示例：

{
  "api_url": "https://api.example.com",
  "api_key": "your_api_key_here",
  "timeout": 30,
  "enable_log": true,
  "log_level": "info"
}

您的外部程序可以直接读取此文件获取用户配置的值。

完整示例

以下是一个包含多种配置类型的完整示例：

{
  "id": "com.example.advanced",
  "name": "高级配置示例",
  "version": "1.0.0",
  "author": "Example",
  
  "settings": [
    {
      "key": "api_url",
      "name": "API 服务器地址",
      "type": "text",
      "value": "https://api.example.com",
      "placeholder": "输入 API 地址",
      "require": true
    },
    {
      "key": "api_key",
      "name": "API 密钥",
      "type": "text",
      "value": "",
      "placeholder": "输入您的 API 密钥",
      "require": true
    },
    {
      "key": "port",
      "name": "端口号",
      "type": "number",
      "value": 8080,
      "placeholder": "输入端口号"
    },
    {
      "key": "timeout",
      "name": "请求超时（秒）",
      "type": "number",
      "value": 30
    },
    {
      "key": "enable_ssl",
      "name": "启用 SSL",
      "type": "checkbox",
      "value": true
    },
    {
      "key": "enable_log",
      "name": "启用日志",
      "type": "checkbox",
      "value": false
    },
    {
      "key": "log_level",
      "name": "日志级别",
      "type": "select",
      "value": "info",
      "options": [
        { "label": "调试 (Debug)", "value": "debug" },
        { "label": "信息 (Info)", "value": "info" },
        { "label": "警告 (Warning)", "value": "warning" },
        { "label": "错误 (Error)", "value": "error" }
      ]
    },
    {
      "key": "custom_script",
      "name": "自定义脚本",
      "type": "textarea",
      "value": "",
      "placeholder": "输入自定义脚本代码"
    },
    {
      "key": "config_file",
      "name": "配置文件",
      "type": "file",
      "value": "",
      "placeholder": "选择配置文件"
    },
    {
      "key": "work_dir",
      "name": "工作目录",
      "type": "path",
      "value": "",
      "placeholder": "选择工作目录"
    },
    {
      "key": "start_date",
      "name": "开始日期",
      "type": "date",
      "value": "2024-01-01"
    },
    {
      "key": "backup_time",
      "name": "每日备份时间",
      "type": "time",
      "value": "02:00:00"
    },
    {
      "key": "next_run",
      "name": "下次运行时间",
      "type": "datetime",
      "value": "2024-01-01 12:00:00"
    }
  ]
}

读取配置

您的外部程序可以读取自动生成的 settings.json 文件来获取用户配置。