验证名称-值参量

名称-值参量将名称与传递给函数的值相关联。名称-值参量：

可以按任何顺序传递给函数
始终为可选
必须在所有位置参量和重复参量之后声明
不能出现在使用 Repeating 属性的 arguments 代码块中
必须使用唯一名称，即便使用多个名称-值结构体时也是如此
不能与位置参量同名

使用圆点表示法在 arguments 代码块中声明名称-值参量以定义结构体的字段。例如，名为 NameValueArgs 的结构体定义两个名称-值参量 Name1 和 Name2。您可以使用任何有效的 MATLAB^® 标识符作为结构体名称。

arguments
    NameValueArgs.Name1
    NameValueArgs.Name2
end

结构体名称必须出现在函数签名中。

function myFunction(NameValueArgs)

使用名称-值结构体中的字段名称调用该函数。

myFunction(Name1=value1,Name2=value2)

在 R2021a 之前，将名称作为字符串或字符向量传递，并以逗号分隔名称和值。这两种语法在以后的版本中都有效。

函数签名中使用的结构体名称是函数工作区中包含传递给该函数的名称和值的结构体的名称。

function result = myFunction(NameValueArgs)
    arguments
        NameValueArgs.Name1
        NameValueArgs.Name2
    end

    % Function code
    result = NameValueArgs.Name1 * NameValueArgs.Name2;
end

r = myFunction(Name1=3,Name2=7)

r =

    21

当不存在多义性时，名称-值参量支持部分名称匹配。例如，将 LineWidth 和 LineStyle 定义为其两个名称-值参量的函数接受 LineW 和 LineS，但使用 Line 会导致错误。一般情况下，推荐使用全名，以提高代码可读性和避免意外行为。

相同的名称-值参量可以在一个函数调用中重复而不会报错，但最后一个指定的版本是 MATLAB 使用的版本。例如，以下对 plot 的调用指定了 Color 的值两次。MATLAB 以红色显示图。

plot(x,y,Color="blue",LineStyle="--",Color="red")

名称-值参量的默认值

您可以为每个名称指定一个默认值。如果没有指定默认值，并且调用函数时不带该名称-值参量，则该字段不存在于名称-值结构体中。如果没有向函数传递名称-值参量，MATLAB 仍会创建结构体，但它没有字段。

要确定在函数调用中传递了哪些名称-值参量，请使用 isfield 函数。

例如，以下函数定义两个必需位置参量（width 和 height）和两个名称-值参量（LineStyle 和 LineWidth）。在此示例中，options 结构体有两个字段（LineStyle 和 LineWidth），其中包含默认值或在调用函数时指定为名称-值参量的值。

function myRectangle(width,height,options)
    arguments
        width double
        height double
        options.LineStyle (1,1) string = "-"
        options.LineWidth (1,1) {mustBeNumeric} = 1
    end

    % Function code
    ...
end

所有以下语法均为调用此函数的有效方式。

myRectangle(4,5)
myRectangle(4,5,LineStyle=":",LineWidth=2)
myRectangle(4,5,LineWidth=2,LineStyle=":")
myRectangle(4,5,LineStyle=":")
myRectangle(4,5,LineWidth=2)

在 R2021a 之前，将名称作为字符串或字符向量传递，并以逗号分隔名称和值。例如：

myRectangle(4,5,"LineStyle",":","LineWidth",2)
myRectangle(4,5,"LineWidth",2,"LineStyle",":")

同时使用重复参量和名称-值参量

如果函数定义了重复参量，则您必须在重复参量代码块之后另加一个 arguments 代码块来声明名称-值参量。例如，此函数接受两个重复参量 x 和 y。在指定 x 和 y 的所有重复项后，您可以指定一个名称-值参量，它将值 lin 或 log 赋给 PlotType 名称。

要确定函数调用是否包含 PlotType 参量，请使用 isfield 函数检查 scale 结构体中是否存在 PlotType 字段。

function myLinLog(x,y,scale)
    arguments(Repeating)
        x (1,:) double
        y (1,:) double
    end
    arguments
        scale.PlotType (1,1) string
    end
    z = reshape([x;y],1,[]);
    if isfield(scale,"PlotType")
        if scale.PlotType == "lin"
            plot(z{:})
        elseif scale.PlotType =="log"
            loglog(z{:})
        end
    end
end

以带或不带名称-值参量的方式调用此函数。

myLinLog(1:5,1:5)
myLinLog(1:5,1:5,1:10,1:100:1000)
myLinLog(1:5,1:5,1:10,1:100:1000,PlotType="log")

在 R2021a 之前，将名称作为字符串或字符向量传递，并以逗号分隔名称和值。例如：

myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")

多个名称-值结构体

函数参量代码块可以包含多个名称-值结构体。但是，字段名称在所有结构体中必须唯一。此函数有两个名称-值结构体：lineOptions 和 fillOptions。这些结构体不能有相同的字段名称。

myRectangle 函数中的参量是：

width 和 height 是 double 类型的必需位置参量。
lineOptions.LineStyle 是标量字符串，默认值为 "-"。
lineOptions.LineWidth 是标量数值，默认值为 1。
fillOptions.Color 是字符串。
fillOptions.Pattern 对其值没有任何限制。

function myRectangle(width,height,lineOptions,fillOptions)
    arguments
        width double
        height double
        lineOptions.LineStyle (1,1) string = "-"
        lineOptions.LineWidth (1,1) {mustBeNumeric} = 1
        fillOptions.Color string
        fillOptions.Pattern
    end

    % Function Code
    ...
end

名称-值参量的稳健处理

在函数中实现名称-值参量的最佳做法是在参量块中定义它们。使用参量块就无需编写自己的代码来解析名称-值参量，参量块还有助于为 R2021a 中引入的 "name",value 语法和 name=value 语法实现稳健的参量解析。

强制应用有效名称

在参量块中定义名称-值参量可确保名称是有效的标识符。这还有助于确保您的参量同时适用 "name",value 和 name=value 语法。例如，使用无效标识符的名称-值参量用在逗号分隔语法中是没问题的：

myFunction(data,"allow-empty",true)

但是，使用 allow-empty=true 语法执行同一调用则会引发错误。在参量块中定义名称-值参量可确保您定义的名称是有效的 MATLAB 变量名称，并且符合 name=value 语法。

避免因文本输入而导致的意外结果

同时包含可选文本输入和名称-值参量的函数存在 MATLAB 误将文本输入解释为名称-值参量名称的风险。以下函数包括两个可选的文本输入和一个名称-值参量。

function mySignal(tag,unit,opts)
    arguments
        tag = "0"
        unit = "ampere"
        opts.Magnifier {mustBeMember(opts.Magnifier,["small","medium","big"])}
    end
end

用户输入以下函数调用是为了将 tag 的值设置为 "Mag" 并将 unit 的值设置为 "coulomb"：

mySignal("Mag","coulomb")

但是，MATLAB 通过部分匹配将 "Mag" 解析为名称-值参量 Magnifer。"coulomb" 不是该名称的有效值，因此函数出错。

避免这种情况的一种方法是通过删除 tag 的默认值，使其成为必需的参量：

function mySignal(tag,unit,opts)
    arguments
        tag
        unit = "ampere"
        opts.Magnifier {mustBeMember(opts.Magnifier,["small","medium","big"])}
    end
end

由于 MATLAB 不会将必需的输入解析为名称-值参量，同一函数调用现在将值 tag 设置为 "Mag"，并且不会出错。

另一种方法是将所有三个输入都作为名称-值参量。这有助于避免用户在指定输入时出错，因为每个值都与一个名称相关联，并且用户指定输入的顺序不会影响最终结果。

基于类属性的名称-值参量

MATLAB 提供了一个方便的函数语法，允许您使用类的公共属性作为名称-值参量的名称。要将类定义的所有可设置属性（即具有公共 SetAccess 的所有属性）指定为名称-值参量，请在 arguments 代码块中使用以下语法：

structName.?ClassName

一个函数只能使用一次 "structName.? ClassName" 语法。因此，即便使用不同的类和结构体名称，一个函数也只能定义一个从类中获取字段名称的名称-值结构体。

如果类通过属性验证来限制可以赋给属性的值，则函数会将验证应用于单独的名称-值参量。有关属性验证的信息，请参阅验证属性值。

例如，此函数有两个必需参量 x 和 y，并且接受 matlab.graphics.chart.primitive.Bar 类的任何公共属性的名称和值。

function myBar(x,y,propArgs)
    arguments
        x (:,:) double
        y (:,:) double
        propArgs.?matlab.graphics.chart.primitive.Bar
    end
    propertyCell = namedargs2cell(propArgs);
    bar(x,y,propertyCell{:})
end

使用必需输入以及任何可设置属性的名称-值对组来调用此函数。

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,FaceColor="magenta",BarLayout="grouped")

在 R2021a 之前，将名称作为字符串或字符向量传递，并以逗号分隔名称和值。例如：

myBar(x,y,"FaceColor","magenta","BarLayout","grouped")

覆盖特定属性

您可以通过在参量代码块中用特定名称-值参量重新定义属性名称来覆盖类属性验证。

structName.?ClassName
structName.PropertyName (dim1,dim2,...) ClassName {fcn1,fcn2,...}

特定名称-值参量验证将覆盖类为单独指定的属性名称定义的验证。

例如，以下函数将名称-值参量定义为 matlab.graphics.chart.primitive.Bar 类的属性。该函数还覆盖属性名称 FaceColor 以仅允许这些特定值：red 或 blue。

matlab.graphics.chart.primitive.Bar 类的 FaceColor 的默认值不是允许值（red 或 blue）。因此，覆盖声明必须赋予一个默认值，该默认值满足 mustBeMember 验证函数施加的限制。也就是说，默认值必须为 red 或 blue。

此函数使用 namedargs2cell 函数将名称-值结构体转换为名称与值相互交错的元胞数组。

function myBar(x,y,propArgs)
    arguments
        x (:,:) double
        y (:,:) double
        propArgs.?matlab.graphics.chart.primitive.Bar
        propArgs.FaceColor {mustBeMember(propArgs.FaceColor,{'red','blue'})} = "blue"
    end
    propertyCell = namedargs2cell(propArgs);
    bar(x,y,propertyCell{:})
end

使用两个必需参量 x 和 y 调用函数。您还可以视需要传递 bar 函数支持的任何名称-值对组以及 FaceColor 的值，该值可以是 red 或 blue。FaceColor 不允许使用其他值。

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,FaceColor="red",BarLayout="grouped")

另请参阅

namedargs2cell | arguments