xmlImportOptions

为 XML 文件导入选项对象

全页展开

说明

通过 XMLImportOptions 对象，您可以指定 MATLAB® 如何从 XML 文件导入结构化表格数据。此对象包含的属性可以控制数据导入过程，包括如何处理错误和缺失的数据。

创建对象

您可以使用 xmlImportOptions 函数（下文介绍）或 detectImportOptions 函数创建 XMLImportOptions 对象：

  • 使用 xmlImportOptions 根据导入要求定义导入属性。

  • 使用 detectImportOptions 根据 filename 中指定的 XML 文件的内容检测并填充导入属性。

    opts = detectImportOptions(filename)

语法

opts = xmlImportOptions
opts = xmlImportOptions('NumVariables',numVars)
opts = xmlImportOptions(___,Name,Value)

描述

opts = xmlImportOptions 使用一个变量创建 XMLImportOptions 对象。

opts = xmlImportOptions('NumVariables',numVars) 使用 numVars 中指定的变量数目创建该对象。

opts = xmlImportOptions(___,Name,Value) 使用一个或多个名称-值参量指定 XMLImportOptions 对象的其他属性。

示例

输入参量

全部展开

变量的数目，指定为正整数标量。

属性

全部展开

变量属性

变量名称，指定为字符向量元胞数组或字符串数组。VariableNames 属性包含导入变量时要使用的名称。

如果数据中包含 N 个变量，但未指定变量名称，VariableNames 属性中将包含 {'Var1','Var2',...,'VarN'}。

要支持无效的 MATLAB 标识符作为变量名称，例如包含空白和非 ASCII 字符的变量名称，请将 VariableNamingRule 的值设置为 'preserve'。

示例: opts.VariableNames 返回当前（检测到的）变量名称。

示例: opts.VariableNames(3) = {'Height'} 将第三个变量的名称更改为 Height。

数据类型: char | string | cell

保留变量名称的标志，指定为 "modify" 或 "preserve"。

  • "modify" - 将无效变量名称（由 isvarname 函数确定）转换为有效的 MATLAB 标识符。

  • "preserve" - 保留作为无效 MATLAB 标识符的变量名称，如包含空白和非 ASCII 字符的变量名称。

从 R2019b 开始，变量名称和行名称可以包含任何字符，包括空格和非 ASCII 字符。此外，它们可以由任何字符（而不仅仅是字母）开头。变量名称和行名称可以不是有效的 MATLAB 标识符（由 isvarname 函数决定）。要保留这些变量名称和行名称，请将 VariableNamingRule 的值设置为 "preserve"。当 VariableNamingRule 的值从 "modify" 更改为 "preserve" 时，变量名称不会刷新。

数据类型: char | string

变量的数据类型，指定为字符向量元胞数组，或包含一组有效数据类型名称的字符串数组。VariableTypes 属性指定导入变量时要使用的数据类型。

要更新 VariableTypes 属性，请使用 setvartype 函数。

示例: opts.VariableTypes 返回当前变量数据类型。

示例: opts = setvartype(opts,'Height',{'double'}) 将变量 Height 的数据类型更改为 double。

要导入的变量子集，指定为字符向量、字符串标量、字符向量元胞数组、字符串数组或数值索引数组。

SelectedVariableNames 必须是 VariableNames 属性中包含的名称的子集。默认情况下，SelectedVariableNames 包含 VariableNames 属性中的所有变量名称，也就是说将导入所有变量。

可以使用 SelectedVariableNames 属性只导入相关变量。使用 SelectedVariableNames 属性指定变量子集，然后使用 readtable 只导入该子集。

要支持无效的 MATLAB 标识符作为变量名称，例如包含空白和非 ASCII 字符的变量名称，请将 VariableNamingRule 的值设置为 'preserve'。

示例: opts.SelectedVariableNames = {'Height','LastName'} 只为导入操作选择两个变量，即 Height 和 LastName。

示例: opts.SelectedVariableNames = [1 5] 只为导入操作选择两个变量，即第一个变量和第五个变量。

示例: T = readtable(filename,opts) 返回一个表，其中只包含在 opts 对象的 SelectedVariableNames 属性中指定的变量。

数据类型: uint16 | uint32 | uint64 | char | string | cell

类型特定的变量导入选项，以变量导入选项对象数组形式返回。此数组为 VariableNames 属性中指定的每个变量包含一个对应的对象。数组中的每个对象均包含一些属性，支持导入特定数据类型的数据。

变量选项支持以下数据类型：数值、文本、logical、datetime 或 categorical。

要查询变量的当前（或检测到的）选项，请使用 getvaropts 函数。

要为变量设置和自定义选项，请使用 setvaropts 函数。

示例: opts.VariableOptions 返回 VariableImportOptions 对象的集合，每个对象对应于数据中的一个变量。

示例: getvaropts(opts,'Height') 返回 Height 变量的 VariableImportOptions 对象。

示例: opts = setvaropts(opts,'Height','FillValue',0) 将变量 Height 的 FillValue 属性设置为 0。

变量描述 XPath 表达式，指定为字符向量或字符串标量，读取函数使用它来选择表变量描述。您必须将 VariableDescriptionsSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'VariableDescriptionsSelector','/RootNode/ChildNode'

表变量 XPath 表达式，指定为字符向量元胞数组或字符串数组，读取函数使用它来选择表变量。您必须将 VariableSelectors 指定为有效的 XPath 版本 1.0 表达式。

示例: 'VariableSelectors',{'/RootNode/ChildNode'}

示例: 'VariableSelectors',"/RootNode/ChildNode"

示例: 'VariableSelectors',["/RootNode/ChildNode1","/RootNode/ChildNode2"]

变量单位 XPath，指定为字符向量或字符串标量，读取函数使用它来选择表变量单位。您必须将 VariableUnitsSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'VariableUnitsSelector','/RootNode/ChildNode'

表属性

表行名称 XPath 表达式，指定为字符向量或字符串标量，读取函数使用它来选择表行的名称。您必须将 RowNamesSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'RowNamesSelector','/RootNode/ChildNode'

表行 XPath 表达式，指定为字符向量或字符串标量，读取函数使用它来选择输出表的各个行。您必须将 RowSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'RowSelector','/RootNode/ChildNode'

表数据 XPath 表达式，指定为字符向量或字符串标量，读取函数使用它来选择输出表数据。您必须将 TableSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'TableSelector','/RootNode/ChildNode'

注册的 XML 命名空间前缀集，指定为由 RegisteredNamespaces 和前缀数组组成的以逗号分隔的对组。读取函数在计算 XML 文件的 XPath 表达式时使用这些前缀。将命名空间前缀及其关联的 URL 指定为 N×2 字符串数组。RegisteredNamespaces 还可以用于计算由选择器名称-值参量（例如 readstruct 的 StructSelector 或 readtable 和 readtimetable 的 VariableSelectors）指定的 XPath 表达式。

默认情况下，读取函数会自动检测要注册以用于 XPath 计算的命名空间前缀，但您也可以使用 RegisteredNamespaces 名称-值参量注册新命名空间前缀。当 XML 节点有命名空间 URL 但在 XML 文件中没有声明的命名空间前缀时，您可以注册新命名空间前缀。

例如，对名为 example.xml 的不包含命名空间前缀的 XML 文件计算 XPath 表达式。将 'RegisteredNamespaces' 指定为 ["myprefix", "https://www.mathworks.com"] 以将前缀 myprefix 赋给 URL https://www.mathworks.com。

T = readtable("example.xml", "VariableSelector", "/myprefix:Data",...
 "RegisteredNamespaces", ["myprefix", "https://www.mathworks.com"])

示例: 'RegisteredNamespaces',["myprefix", "https://www.mathworks.com"]

替代规则

管理缺失数据的过程，指定为下表中的值之一。

缺失规则行为
'fill'

用 FillValue 属性的内容替代缺失的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息，请参阅 setvaropts。

'error'停止导入并显示一条错误消息，指出缺失的记录和字段。
'omitrow'忽略包含缺失数据的行。
'omitvar'忽略包含缺失数据的变量。

示例: opts.MissingRule = 'omitrow';

数据类型: char | string

处理导入错误的过程，指定为下表中的值之一。

导入错误规则行为
'fill'

用 FillValue 属性的内容替代出现错误的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息，请参阅 setvaropts。

'error'停止导入并显示一条错误消息，指出导致出错的记录和字段。
'omitrow'忽略发生错误的行。
'omitvar'忽略发生错误的变量。

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

处理表的给定行中重复 XML 节点的过程，指定为 'addcol'、'ignore' 或 'error'。

重复节点规则

行为

'addcol'

在表中的变量标题下为重复节点添加列。将 'RepeatedNodeRule' 的值指定为 'addcol' 不会在表中为重复节点创建单独变量。

'ignore'

跳过导入重复节点。

'error'显示错误消息并中止导入操作。

示例: 'RepeatedNodeRule','ignore'

示例

全部折叠

打开实时脚本

为 XML 文件创建 XML 导入选项，指定要导入的变量，然后读取数据。

XML 文件 students.xml 有三个名为 Student 的同级节点，每个节点都包含相同的子节点和属性。

type students.xml
<?xml version="1.0" encoding="utf-8"?>
<Students>
    <Student ID="S11305">
        <Name FirstName="Priya" LastName="Thompson" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">591 Spring Lane</Street>
            <City>Natick</City>
            <State>MA</State>
      </Address>
      <Major>Computer Science</Major>
      <Minor>English Literature</Minor>
   </Student>
   <Student ID="S23451">
        <Name FirstName="Conor" LastName="Cole" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">4641 Pearl Street</Street>
            <City>San Francisco</City>
            <State>CA</State>
        </Address>
        <Major>Microbiology</Major>
        <Minor>Public Health</Minor>
    </Student>
    <Student ID="S119323">
        <Name FirstName="Morgan" LastName="Yang" />
        <Age>21</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">30 Highland Road</Street>
            <City>Detriot</City>
            <State>MI</State>
        </Address>
        <Major>Political Science</Major>
   </Student>
</Students>

从文件创建一个 XMLImportOptions 对象。将 VariableSelectors 的值指定为 //@FirstName 以选择要作为表变量导入的 FirstName 元素节点。

opts = xmlImportOptions("VariableSelectors","//@FirstName");

使用 readtable 以及选项对象导入指定的变量。

T = readtable("students.xml",opts)
T=3×1 table
       Var1   
    __________

    {'Priya' }
    {'Conor' }
    {'Morgan'}
打开实时脚本

将 XML 文件的内容导入表中。

students.xml 文件有三个名为 Student 的同级节点，每个节点都包含相同的子节点和属性。 

type students.xml
<?xml version="1.0" encoding="utf-8"?>
<Students>
    <Student ID="S11305">
        <Name FirstName="Priya" LastName="Thompson" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">591 Spring Lane</Street>
            <City>Natick</City>
            <State>MA</State>
      </Address>
      <Major>Computer Science</Major>
      <Minor>English Literature</Minor>
   </Student>
   <Student ID="S23451">
        <Name FirstName="Conor" LastName="Cole" />
        <Age>18</Age>
        <Year>Freshman</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">4641 Pearl Street</Street>
            <City>San Francisco</City>
            <State>CA</State>
        </Address>
        <Major>Microbiology</Major>
        <Minor>Public Health</Minor>
    </Student>
    <Student ID="S119323">
        <Name FirstName="Morgan" LastName="Yang" />
        <Age>21</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">30 Highland Road</Street>
            <City>Detriot</City>
            <State>MI</State>
        </Address>
        <Major>Political Science</Major>
   </Student>
</Students>

首先，使用 detectImportOptions 创建一个 XMLImportOptions 对象来检测 XML 文件的各个方面。通过将 VariableSelectors 名称-值参量指定为 Street 元素节点的 XPath 表达式，仅将街道名称读入表中。通过设置 RegisteredNamespaces 名称-值参量，将自定义命名空间前缀注册到现有命名空间 URL。

opts = detectImportOptions("students.xml",RegisteredNamespaces=["myPrefix","https://www.mathworks.com"], ...
    VariableSelectors="//myPrefix:Street");

然后，使用 readtable 和导入选项对象导入指定的变量。 

T = readtable("students.xml",opts)
T=3×1 table
          Street       
    ___________________

    "591 Spring Lane"  
    "4641 Pearl Street"
    "30 Highland Road"

提示

  • 使用 XPath 选择器指定要导入 XML 输入文档的哪些元素。例如，假设您要导入 XML 文件 myFile.xml，该文件具有以下结构：

    <data>
    <table category="ones">
        <var>1</var>
        <var>2</var>
    </table>
    <table category="tens">
        <var>10</var>
        <var>20</var>
    </table>
</data>
    下表提供 XPath 选择器名称-值参量（例如 VariableSelectors 或 TableSelector）支持的 XPath 语法。

    选取操作语法示例结果
    选择其名称与您要选择的节点匹配的每个节点，而无论它在文档中的位置如何。在名称前加两个正斜杠 (//) 前缀。 
    data = readtable('myFile.xml', 'VariableSelectors', '//var')
    		 
    data =

  4×1 table

    var
    ___

     1 
     2 
    10 
    20
    读取属于元素节点的属性的值。在属性前加 at 符号 (@) 前缀。 
    data = readtable('myFile.xml', 'VariableSelectors', '//table/@category')
    		 
    data =

  2×1 table

    categoryAttribute
    _________________

         "ones"      
         "tens"
    在一组节点中选择一个特定节点。在方括号 ([]) 中提供要选择的节点的索引。 
    data = readtable('myFile.xml', 'TableSelector', '//table[1]')
    		 
    data =

  2×1 table

    var
    ___

     1 
     2
    指定运算的优先级。在要首先计算的表达式前后添加圆括号。 
    data = readtable('myFile.xml', 'VariableSelectors', '//table/var[1]')
    		 
    data =

  2×1 table

    var
    ___

     1 
    10 
    data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')
    		 
    data =

  table

    var
    ___

     1

版本历史记录

在 R2021a 中推出

另请参阅

| |