外设元素参考

本文档是外设 Schema 配置中所有可用 UI 元素的参考手册，可作为工具书随时查阅。

通用属性

所有配置元素共享以下基础属性：

基础标识属性

属性必需说明示例
ID✅唯一标识符，用于代码中获取变量值"ID": "Mode"
label✅界面显示的名称"label": "I2C Speed Mode"
placeholder-输入框为空时的提示文本"placeholder": "Enter value"

值控制属性

属性说明示例
value默认值"value": "MyDevice"
min最小值"min": 0
max最大值"max": 400000

状态控制属性

属性说明示例
disabled是否禁用"disabled": true
visible是否可见"visible": true

可见性与禁用条件语法

McuStudio 使用特殊的表达式语法来控制元素的可见性和禁用状态：

基本语法

// 简单条件
visible: true
disabled: false

// 引用当前元素值
visible: "@get: $root.EnableWatchDog.value === true"

// 引用其他元素值
disabled: "@get: $root.NbrOfConversion.value <= 1"

// 字符串比较
disabled: "@get: $root.ContinuousConvMode.value === 'enable'"

// 组合条件 (&&)
disabled: "@get: $root.ContinuousConvMode.value === 'enable' || $root.ScanConvMode.value === 'disable'"

// 组合条件 (||)
visible: "@get: $root.EnableInjectedConversions.value === 'enable' && $root.InjectedNbrOfConversion.value > 0"

// 引用其他外设
visible: '@get: ADC0.enabled() && ADC1.enabled()'

跨元素依赖模式

// 下拉选项的条件禁用
options: [
  {
    label: 'Enable',
    value: 'enable',
    disabled: '@get: $root.NbrOfConversion.value <= 1'  // 单通道时禁用
  },
  {
    label: 'Disable',
    value: 'disable',
    disabled: '@get: $root.NbrOfConversion.value > 1'   // 多通道时禁用
  }
]

输入类元素

1. 输入框 (Input)

用于输入文本或数字：

ClockSpeed: {
  label: 'I2C Speed Frequency (Hz)',
  type: 'input',
  value: '100000',
  disabled: false,
  placeholder: '',
  min: 0,
  max: 400000,
  isformat: true,
  format: 'Decimal'           // Decimal / Hexadecimal
}

2. 数字输入框 (Number)

专用于数字输入，带增减按钮：

NbrOfConversion: {
  label: 'Number Of Conversion',
  type: 'number',
  value: '1',
  disabled: false,
  placeholder: '',
  min: 1,
  max: 16
}

选择类元素

3. 下拉选择 (Select)

用于从多个选项中选择一项：

I2CSpeedMode: {
  label: 'I2C Speed Mode',
  type: 'select',
  value: 'StandardMode',
  disabled: false,
  placeholder: '',
  options: [
    {
      label: 'Standard Mode',
      value: 'StandardMode',
      disabled: false
    },
    {
      label: 'Fast Mode',
      value: 'FastMode',
      disabled: false
    }
  ]
}

4. 复选框 (Checkbox)

用于布尔值选择：

IN0: {
  label: 'IN0',
  type: 'checkbox',
  value: false,               // false = 未勾选, true = 已勾选
  disabled: false
}

5. 日期选择 (DatePicker)

用于日期输入（较少使用）：

Date: {
  label: 'Date',
  type: 'datepick',
  value: '2026-01-01'
}

信息展示类元素

6. 文本 (Text)

用于显示静态文本信息：

Description: {
  label: 'Description',
  type: 'text',
  value: 'This peripheral controls the USART module.'
}

7. 标签 (Span)

用于显示只读标签，通常用于引脚名等不可修改的字段：

Pin: {
  label: 'Pin',
  type: 'span',
  value: 'PA0'
}

8. 表格 (Table)

用于结构化数据展示，如 GPIO 引脚配置表：

GPIO: {
  label: 'GPIO Configuration',
  type: 'table',
  head: {
    name: {
      label: 'Pin',
      type: 'text'
    },
    mode: {
      label: 'Mode',
      type: 'select',
      options: [ /* ... */ ]
    },
    speed: {
      label: 'Speed',
      type: 'select',
      options: [ /* ... */ ]
    }
  },
  body: {
    // 表格数据由脚本动态填充
  }
}

9. 列表 (List)

用于可增减的列表数据：

Channels: {
  label: 'Channels',
  type: 'list',
  template: {
    // 每项的模板
  }
}

布局容器类元素

10. Tab 面板

用于在不同功能面板之间切换：

// Tab 面板在外设 UI 顶层定义
{
  Parameter: {
    label: 'Parameter',
    // ... 元素
  },
  NVIC: {
    label: 'NVIC Settings',
    // ... 元素
  },
  DMA: {
    label: 'DMA Settings',
    // ... 元素
  }
}

11. 折叠面板 (Collapse)

用于将相关元素分组，可折叠/展开：

AdvanceSettings: {
  label: 'Advanced Settings',
  type: 'collapse',
  children: [
    {
      label: 'Clock Polarity',
      type: 'select',
      options: [ /* ... */ ]
    },
    {
      label: 'Clock Phase',
      type: 'select',
      options: [ /* ... */ ]
    }
  ]
}

元素配置最佳实践

  1. ID 命名规范：使用驼峰命名，见名知义（如 BaudRate、WordLength）
  2. 标签使用中文：label 使用中文，方便用户理解
  3. 默认值合理：设置符合大多数使用场景的默认值
  4. 条件控制精准：使用 visible 和 disabled 防止无效配置
  5. 输入验证：使用 min/max 限制数值范围
  6. 选项完整：Select 的选项应覆盖所有可能的有效值