matlab-configure-scope-object

范围配置 — 安全 API 技能

适用场景

每当你与任何范围相关模块或对象的属性交互时，此技能均会生效：

Simulink 模块：

• Scope、Floating Scope（Simulink）
• Time Scope、Spectrum Analyzer、Array Plot（DSP System Toolbox）
• Constellation Diagram、Eye Diagram（Communications Toolbox）
• Video Viewer（Computer Vision Toolbox）
• Point Cloud Viewer（Point Cloud Toolbox）
• Scope Viewer（信号级查看器）
• Range-Time Intensity Scope、Angle-Time Intensity Scope、Doppler-Time Intensity Scope（Phased Array System Toolbox）

MATLAB 对象：

• timescope(...)
• spectrumAnalyzer(...)（以前称为 dsp.SpectrumAnalyzer）
• dsp.ArrayPlot(...)
• comm.ConstellationDiagram(...)
• comm.EyeDiagram(...)
• phased.IntensityScope(...)
• phased.RTIScope(...)
• phased.DTIScope(...)
• phased.ATIScope(...)
• phased.RangeDopplerScope(...)
• phased.RangeAngleScope(...)
• phased.AngleDopplerScope(...)

不适用场景

• 配置非范围类 Simulink 模块——对 Gain、Sum 或 Transfer Function 等模块使用标准的 get_param/set_param 不会带来升级风险
• 在不修改属性的情况下与范围交互——在仿真期间打开、关闭或查看范围
• 使用其他可视化工具，例如 Simulation Data Inspector

工作流

1. 识别范围类型——Simulink 模块或 MATLAB 对象（参见“此技能的适用场景”）。
2. 获取配置接口：
   • Simulink 模块：scopeConfig = get_param('model/Block', 'ScopeConfiguration');
   • MATLAB 对象：直接使用该对象。
3. 列出公共属性： properties(scopeConfig) 或 properties(scopeObj)。
4. 检查目标属性是否存在于列表中。若不存在 → 错误处理（找不到属性）。
5. 通过直接赋值设置属性。
6. 处理错误：
   • 对象已锁定 → release(obj)，然后设置。
   • 格式不匹配 → 使用修正后的类型重试一次；对于 Simulink 模块，尝试另一种访问方法（get_param/set_param 与 ScopeConfiguration）。
   • 仍然失败 → 向用户说明限制并停止。

关键函数

函数 / API	用途
get_param(block, 'ScopeConfiguration')	获取 Simulink 范围模块的文档化配置对象
set_param(block, param, value)	设置模块级参数（备用访问方法）
properties(obj)	列出公共属性——这是确认属性是否可访问的唯一方法
release(obj)	在设置不可调谐属性之前，解除 MATLAB System 对象的锁定

关键安全规则

边界：仅使用文档化的公共 API

下方的“允许的操作”部分是一份完整的白名单。未列出的任何方法均属禁止，包括但不限于：

1. 不得访问内部框架对象。 Simulink.scopes.* 命名空间及其中的任何类都是内部实现细节——绝不要实例化、引用或与其交互。

2. 不得通过内省来发现未文档化的接口。 不要检查范围对象或其模块句柄的元类信息、隐藏属性或内部方法。

3. 不得通过模块对象绕过公共 API。 范围模块句柄只能与 get_param/set_param 和 'ScopeConfiguration' 配合使用——绝不要直接获取或操作底层对象。

4. 失败后不得升级操作。 如果允许的 API 调用失败，且错误并非简单的格式或访问方法问题，请停止。不要尝试更深入的访问或内省。向用户说明限制。（允许的重试方式见“错误处理流程”。）

允许的工作流（完整白名单）：

请按顺序执行以下步骤。不要跳过步骤或自行发明替代方案。

对于 Simulink scope 模块：

1. 获取已记录的配置对象： scopeConfig = get_param('model/Scope', 'ScopeConfiguration');

2. 列出可用的公共属性： properties(scopeConfig)

3. 确认目标属性出现在列表中。如果未出现，请转到错误处理流程——不要尝试设置它。

4. 读取或写入已确认的公共属性： value = scopeConfig.PropertyName; scopeConfig.PropertyName = newValue;

5. 使用带有已记录参数名的 get_param/set_param： value = get_param('model/Scope', 'ParameterName'); set_param('model/Scope', 'ParameterName', value);

   某个属性可能可通过一种方法访问，但无法通过另一种方法访问。如果其中一种失败，请先尝试另一种，然后再报告限制。

对于 MATLAB scope 对象：

1. 列出可用的公共属性： properties(scopeObj)

2. 确认目标属性出现在列表中。如果未出现，请转到错误处理流程——不要尝试设置它。

3. 读取或写入已确认的公共属性： scopeObj.PropertyName = newValue;

这就是允许的操作的完整集合。没有其他操作。

将用户请求映射到属性名

当用户的描述与属性名不完全匹配时，请将其映射到 properties(...) 输出中最接近的匹配公共属性。如果有多个属性可能匹配，或者映射不明确，请向用户显示属性列表，并在继续之前请他们确认。

错误处理流程

未找到属性： 当目标属性未由 properties(...) 列出时：

1. 向用户报告：

   “不支持对 [scope] 的 [property] 进行编程访问。此 scope 可能不存在该属性，或者该属性只能通过 scope UI 配置。要以编程方式更改受支持的属性，请指定由 properties(...) 列出的属性。要更改视觉或仅 UI 设置，请打开 scope 窗口并使用配置面板。”

2. 停止。 不要针对此特定属性尝试进一步的编程解决方案。

对象锁定错误： 当由于对象被锁定而设置属性失败时（错误提到 “non-tunable” 或 “release”）：

1. 调用 release(scopeObj) 解锁对象。
2. 设置该属性。
3. 下一次调用 step 或 obj(data) 时将重新锁定对象。

格式或访问方法错误： 当已确认的属性由于类型不匹配、值格式不正确或特定方法限制而失败时：

1. 以下每种情况允许重试一次：
   • 更正值格式（例如，将数值改为字符串）并重试同一方法。
   • 对于 Simulink scope 模块，使用相同的值尝试另一种访问方法。
2. 如果所有重试都失败，请报告限制并停止。不要尝试更深入的访问或内省。

MATLAB 可能会在错误消息或 class() 输出中暴露内部类名。 不要使用 Simulink.scopes.* 命名空间中的任何类名来访问 scope 内部。

这些规则为何存在

Simulink scope 模块和 MATLAB scope 对象使用基于 Web 的查看器，其后端由管理图形管线、Web Socket 和共享状态的内部框架对象支持。在其预期生命周期之外访问这些内部结构——或在未正确初始化的情况下与其属性交互——会导致 MATLAB 崩溃且无法恢复。

已记录的 API（Simulink 模块通过 get_param 使用 ScopeConfiguration；MATLAB scope 对象上的公共属性）是安全的、沙盒化的接口。除此之外的一切都不适合进行编程访问。

---

Copyright 2026 The MathWorks, Inc.