自定义代码建议和自动填充
R2026a要为您的函数和类自定义代码建议和自动填充，请向 MATLAB® 提供有关您的函数签名的信息。函数签名说明函数可接受的语法和允许的数据类型。MATLAB 使用此信息在编辑器、实时编辑器和命令行窗口中显示代码建议和自动填充。在名为 functionSignatures.json 的 JSON 格式文件中定义此函数信息。MATLAB 能够根据 arguments 代码块中包含的信息为具有 arguments 代码块的函数提供代码补全和建议。无需 functionSignatures.json 文件即可获得此信息。MATLAB Online 不支持自定义代码建议和自动填充。
要使 MATLAB 检测函数签名信息，请将 functionSignatures.json 放入包含函数代码的 resources 文件夹中。如果为类方法或命名空间函数定义信息，请将 functionSignatures.json 放在最外层类或命名空间文件夹的父文件夹中的 resources 文件夹中。例如，要为 myClass 的方法定义信息，请将 functionSignatures.json 放在这些类和命名空间结构体的 myFolder 中的 resources 文件夹中：
myFolder/+myNamespace/@myClass myFolder/+myNamespace/+mySubnamespace/@myClass
对于位于类文件夹或命名空间文件夹之外的类，请将 functionSignatures.json 放在包含类代码的 resources 文件夹中。您可以在同一个文件中为多个函数定义签名。
functionSignatures.json 文件只包含一个 JSON 对象。JSON 使用花括号来定义对象，并以名称-值对组集合的形式引用对象。由于这些术语在函数签名的语境下使用过多，因而此处使用“属性”而非“名称”。functionSignatures.json 中的 JSON 对象包含架构版本（可选）和函数对象列表。每个函数对象都包含一个签名对象列表，每个签名对象包含一个参量对象数组。JSON 使用方括号来定义数组。
要指定架构版本（可选），请使用 _schemaVersion 作为第一个属性，使用版本号作为其值。将版本号指定为 major#.minor#.patch#1.0.0。如果文件未指定架构版本，则 MATLAB 假定版本为 1.0.0。
如果 functionSignatures.json 包含语法错误，MATLAB 在读取文件时会在命令行窗口中显示错误消息。使用 validateFunctionSignaturesJSON 函数根据 JSON 架构和 MATLAB 函数签名架构验证 functionSignatures.json 文件。
函数对象
要为函数定义信息，请创建一个与函数名称相同的属性。它的值是签名对象。
{
"functionName1": { signatureObj1 },
"functionName2": { signatureObj2 }
}要为类构造函数、类方法或命名空间函数定义信息，请使用函数或方法的全名。例如，定义类构造函数、类方法 myMethod 和命名空间函数 myFunction。
{
"myClass.myClass": { signatureObj },
"myClass.myMethod": { signatureObj },
"myNamespace.myFunction": { signatureObj }
}通过定义具有相同属性（函数或方法名称）的多个函数对象，可以为同一个函数或方法定义多个函数签名。有关详细信息，请参阅多个签名。
签名对象
签名对象定义函数的输入和输出参量以及支持的平台。每个属性的值（platforms 属性除外）都是一个参量对象数组。
{
"functionName1":
{
"inputs": [ argumentObj1, argumentObj2 ]
}
}如果在 JSON 文件中指定实例方法，如 myClass.myMethod，则 inputs 中的元素之一必须为 myClass 的对象。通常，此对象是第一个元素。当您使用圆点表示法 (b = myObj.myMethod(a)) 或函数表示法 (b = myMethod(myObj,a)) 语法调用指定方法时，MATLAB 支持针对该方法的代码建议和自动填充。
JSON 文件中的每个签名都可以包括以下属性。
| 属性 | 描述 | 值的 JSON 数据类型 |
|---|---|---|
inputs | 函数输入参量的列表。MATLAB 将此属性用于代码建议和自动填充。 | 参量对象数组 |
outputs | 函数输出参量列表。MATLAB 使用此属性来优化代码建议和自动填充。 | 参量对象数组 |
platforms | 支持该函数的平台的列表。如果平台不支持该函数，MATLAB 不会显示自定义代码建议和自动填充。 默认是所有平台。列表的元素必须与 | 逗号分隔值的字符串 |
参量对象
参量对象定义每个输入和输出参量的信息。
{
"functionName1":
{
"inputs":
[
{"name":"in1", "kind":"required", "type":["numeric"]},
{"name":"in2", "kind":"required", "type":["numeric","integer","scalar"]}
]
}
}各个输入在 JSON 文件中的显示顺序非常重要。例如，在对 functionName1 函数的调用中，in1 必须出现在 in2 之前。
每个参量对象可以包含以下属性。
对于更复杂的函数签名，各个参量对象均可使用以下属性。
创建函数签名文件
此示例说明如何为函数创建自定义代码建议和自动填充。
创建一个函数，其签名将在后续步骤中由 JSON 文件加以描述。以下函数接受：
两个必需参量
一个可选的位置参量（通过
varargin）两个可选的名称-值参量（通过
varargin）
此处使用 myFunc 来演示代码建议，其中不包含参量检查。
% myFunc Example function % This function is called with any of these syntaxes: % % myFunc(in1, in2) accepts 2 required arguments. % myFunc(in1, in2, in3) also accepts an optional 3rd argument. % myFunc(___, NAME, VALUE) accepts one or more of the following name-value % arguments. This syntax can be used in any of the previous syntaxes. % * 'NAME1' with logical value % * 'NAME2' with 'Default', 'Choice1', or 'Choice2' function myFunc(reqA,reqB,varargin) % Initialize default values NV1 = true; NV2 = 'Default'; posA = []; if nargin > 3 if rem(nargin,2) posA = varargin{1}; V = varargin(2:end); else V = varargin; end for n = 1:2:size(V,2) switch V{n} case 'Name1' NV1 = V{n+1}; case 'Name2' NV2 = V{n+1} otherwise error('Error.') end end end end
在 myFunc 所在的文件夹的 resources 文件夹中，在名为 functionSignatures.json 的文件中创建以下函数签名描述。输入名称与 myFunc 主体中的名称不匹配，但与帮助文本一致。
{
"_schemaVersion": "1.0.0",
"myFunc":
{
"inputs":
[
{"name":"in1", "kind":"required", "type":["numeric"], "purpose":"ID of item"},
{"name":"in2", "kind":"required", "type":["numeric"], "purpose":"# Items"},
{"name":"in3", "kind":"ordered", "type":["numeric"], "purpose":"Input Value"},
{"name":"Name1", "kind":"namevalue", "type":["logical","scalar"],"purpose":"Option"},
{"name":"Name2", "kind":"namevalue", "type":["char", "choices={'Default','Choice1','Choice2'}"]}
]
}
}
MATLAB 使用此函数签名描述来提供代码建议和自动填充。
如何使用函数签名信息
MATLAB 使用 JSON 文件中的函数签名信息在您键入时显示匹配的语法。您也可以通过按下 Tab 键来自动填充部分键入的文本。在命令行窗口中，MATLAB 不使用 JSON 文件显示与键入匹配的语法。
要体验一下代码建议，可从脚本或实时脚本调用 myFunc。建议会显示取自 JSON 文件的名称和用途。MATLAB 会指示参量是否为可选以及是否有多个建议（如第三个位置参量或一个名称-值参量）。名称-值参量选项会列出。
向函数调用添加名称-值参量时，MATLAB 基于 JSON 文件提供选项。由于 'Name1' 定义为逻辑标量，因此 MATLAB 会自动填充选项（true 或 false）。MATLAB 基于 JSON 文件显示 'Name2' 参量的三个值。
多个签名
如果一个函数有许多语法，则可以在代码建议中将语法分组为多个函数签名（不考虑函数实现）。要为多个签名提供代码建议和自动填充，请在 JSON 文件中创建具有相同属性的多个函数对象。
以如下函数为例，它根据第二个输入的类采用不同代码路径。此函数仅用作代码建议的示例，因此不执行任何计算或错误检查。
function anotherFunc(arg1,arg2,arg3) switch class(arg2) case 'double' % Follow code path 1 case {'char','string'} % Follow code path 2 otherwise error('Invalid syntax.') end end
从代码建议的角度来看，将函数视为具有两个函数签名。第一个签名接受两个必需的数值。第二个签名接受一个必需的数值，然后是一个字符或字符串，最后是一个必需的数值。要定义多个函数签名，请使用相同的属性（函数名称）在 JSON 文件中定义多个函数对象。
{
"_schemaVersion": "1.0.0",
"anotherFunc":
{
"inputs":
[
{"name":"input1", "kind":"required", "type":["numeric"]},
{"name":"input2", "kind":"required", "type":["numeric"]}
]
},
"anotherFunc":
{
"inputs":
[
{"name":"input1", "kind":"required", "type":["numeric"]},
{"name":"input2", "kind":"required", "type":[["char"],["string"]]},
{"name":"input3", "kind":"required", "type":["numeric"]}
]
}
}您也可以使用参量对象的 mutuallyExclusiveGroup 属性定义多个函数签名。通常情况下，实现多个函数对象更容易且更易读，但使用互斥组能够重用常见参量对象，如 input1。
{
"_schemaVersion": "1.0.0",
"anotherFunc":
{
"inputs":
[
{"name":"input1", "kind":"required", "type":["numeric"]},
{"mutuallyExclusiveGroup":
[
[
{"name":"input2", "kind":"required", "type":["numeric"]}
],
[
{"name":"input2", "kind":"required", "type":[["char"],["string"]]},
{"name":"input3", "kind":"required", "type":["numeric"]}
]
]
}
]
}
}另请参阅
validateFunctionSignaturesJSON
