xmlImportOptions

为 XML 文件导入选项对象

自 R2021a 起

全页展开

说明

通过 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 对象的其他属性。

示例

输入参量

全部展开

`numVars` — 变量的数目
正整数标量

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

属性

全部展开

变量属性

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

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

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

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

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

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

数据类型: char | string | cell

`VariableNamingRule` — 保留变量名称的标志
`"modify"` (默认) | `"preserve"`

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

"modify" - 将无效变量名称（由 isvarname 函数确定）转换为有效的 MATLAB 标识符。
"preserve" - 保留作为无效 MATLAB 标识符的变量名称，如包含空白和非 ASCII 字符的变量名称。

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

数据类型: char | string

`VariableTypes` — 变量的数据类型
字符向量元胞数组 | 字符串数组

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

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

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

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

`SelectedVariableNames` — 要导入的变量子集
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组 | 数值索引数组

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

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 属性中指定的变量。

`VariableOptions` — 类型特定的变量导入选项
由变量导入选项对象组成的数组

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

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

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

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

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

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

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

`VariableDescriptionsSelector` — 变量描述 XPath 表达式
字符向量 | 字符串标量

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

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

`VariableSelectors` — 表变量 XPath 表达式
字符向量元胞数组 | 字符串数组

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

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

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

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

`VariableUnitsSelector` — 变量单位 XPath 表达式
字符向量 | 字符串标量

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

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

表属性

`RowNamesSelector` — 表行名称 XPath 表达式
字符向量 | 字符串标量

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

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

`RowSelector` — 表行 XPath 表达式
字符向量 | 字符串标量

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

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

`TableSelector` — 表数据 XPath 表达式
字符向量 | 字符串标量

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

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

`RegisteredNamespaces` — 注册的 XML 命名空间前缀集
字符串数组

注册的 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"]

替代规则

`MissingRule` — 管理缺失数据的过程
`'fill'` (默认) | `'error'` | `'omitrow'` | `'omitvar'`

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

缺失规则	行为
`'fill'`	用 `FillValue` 属性的内容替代缺失的数据。 `FillValue` 属性在要导入的变量的 `VariableImportOptions` 对象中指定。有关访问 `FillValue` 属性的详细信息，请参阅 `setvaropts`。
`'error'`	停止导入并显示一条错误消息，指出缺失的记录和字段。
`'omitrow'`	忽略包含缺失数据的行。
`'omitvar'`	忽略包含缺失数据的变量。

示例: opts.MissingRule = 'omitrow';

数据类型: char | string

`ImportErrorRule` — 处理导入错误的过程
`'fill'` (默认) | `'error'` | `'omitrow'` | `'omitvar'`

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

导入错误规则	行为
`'fill'`	用 `FillValue` 属性的内容替代出现错误的数据。 `FillValue` 属性在要导入的变量的 `VariableImportOptions` 对象中指定。有关访问 `FillValue` 属性的详细信息，请参阅 `setvaropts`。
`'error'`	停止导入并显示一条错误消息，指出导致出错的记录和字段。
`'omitrow'`	忽略发生错误的行。
`'omitvar'`	忽略发生错误的变量。

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

`RepeatedNodeRule` — 处理重复 XML 节点的过程
`'addcol'` (默认) | `'ignore'` | `'error'`

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

重复节点规则	行为
`'addcol'`	在表中的变量标题下为重复节点添加列。将 `'RepeatedNodeRule'` 的值指定为 `'addcol'` 不会在表中为重复节点创建单独变量。
`'ignore'`	跳过导入重复节点。
`'error'`	显示错误消息并中止导入操作。

示例: 'RepeatedNodeRule','ignore'

示例

全部折叠

使用导入选项读取 XML 文件

打开实时脚本

为 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>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>19</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
   </Student>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>20</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
    </Student>
    <Student ID="54600">
        <Name FirstName="Dania" LastName="Burt" />
        <Age>22</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">22 Angie Drive</Street>
            <City>Los Angeles</City>
            <State>CA</State>
        </Address>
        <Major>Mechanical Engineering</Major>
        <Minor>Architecture</Minor>
   </Student>
    <Student ID="453197">
        <Name FirstName="Rikki" LastName="Gunn" />
        <Age>21</Age>
        <Year>Junior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">65 Decatur Lane</Street>
            <City>Trenton</City>
            <State>ME</State>
        </Address>
        <Major>Economics</Major>
        <Minor>Art History</Minor>
   </Student>
</Students>

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

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

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

T = readtable("students.xml",opts)

T=7×1 table
       Var1   
    __________

    {'Priya' }
    {'Conor' }
    {'Morgan'}
    {'Salim' }
    {'Salim' }
    {'Dania' }
    {'Rikki' }

以表的形式读取 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>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>19</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
   </Student>
   <Student ID="S201351">
        <Name FirstName="Salim" LastName="Copeland" />
        <Age>20</Age>
        <Year>Sophomore</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">3388 Moore Avenue</Street>
            <City>Fort Worth</City>
            <State>TX</State>
        </Address>
        <Major>Business</Major>
        <Minor>Japanese Language</Minor>
    </Student>
    <Student ID="54600">
        <Name FirstName="Dania" LastName="Burt" />
        <Age>22</Age>
        <Year>Senior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">22 Angie Drive</Street>
            <City>Los Angeles</City>
            <State>CA</State>
        </Address>
        <Major>Mechanical Engineering</Major>
        <Minor>Architecture</Minor>
   </Student>
    <Student ID="453197">
        <Name FirstName="Rikki" LastName="Gunn" />
        <Age>21</Age>
        <Year>Junior</Year>
        <Address>
            <Street xmlns="https://www.mathworks.com">65 Decatur Lane</Street>
            <City>Trenton</City>
            <State>ME</State>
        </Address>
        <Major>Economics</Major>
        <Minor>Art History</Minor>
   </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=7×1 table
          Street       
    ___________________

    "591 Spring Lane"  
    "4641 Pearl Street"
    "30 Highland Road" 
    "3388 Moore Avenue"
    "3388 Moore Avenue"
    "22 Angie Drive"   
    "65 Decatur Lane"

提示

使用 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 中推出

另请参阅

detectImportOptions | readtable | readtimetable

xmlImportOptions

说明

创建对象

语法

描述

输入参量

numVars — 变量的数目 正整数标量

属性

变量属性

VariableNames — 变量名称 字符向量元胞数组 | 字符串数组

VariableNamingRule — 保留变量名称的标志 "modify" (默认) | "preserve"

VariableTypes — 变量的数据类型 字符向量元胞数组 | 字符串数组

SelectedVariableNames — 要导入的变量子集 字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组 | 数值索引数组

VariableOptions — 类型特定的变量导入选项 由变量导入选项对象组成的数组

VariableDescriptionsSelector — 变量描述 XPath 表达式 字符向量 | 字符串标量

VariableSelectors — 表变量 XPath 表达式 字符向量元胞数组 | 字符串数组

VariableUnitsSelector — 变量单位 XPath 表达式 字符向量 | 字符串标量

表属性

RowNamesSelector — 表行名称 XPath 表达式 字符向量 | 字符串标量

RowSelector — 表行 XPath 表达式 字符向量 | 字符串标量

TableSelector — 表数据 XPath 表达式 字符向量 | 字符串标量

RegisteredNamespaces — 注册的 XML 命名空间前缀集 字符串数组

替代规则

MissingRule — 管理缺失数据的过程 'fill' (默认) | 'error' | 'omitrow' | 'omitvar'

ImportErrorRule — 处理导入错误的过程 'fill' (默认) | 'error' | 'omitrow' | 'omitvar'

RepeatedNodeRule — 处理重复 XML 节点的过程 'addcol' (默认) | 'ignore' | 'error'

示例

使用导入选项读取 XML 文件

以表的形式读取 XML 文件

提示

版本历史记录

另请参阅

`numVars` — 变量的数目
正整数标量

`VariableNames` — 变量名称
字符向量元胞数组 | 字符串数组

`VariableNamingRule` — 保留变量名称的标志
`"modify"` (默认) | `"preserve"`

`VariableTypes` — 变量的数据类型
字符向量元胞数组 | 字符串数组

`SelectedVariableNames` — 要导入的变量子集
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组 | 数值索引数组

`VariableOptions` — 类型特定的变量导入选项
由变量导入选项对象组成的数组

`VariableDescriptionsSelector` — 变量描述 XPath 表达式
字符向量 | 字符串标量

`VariableSelectors` — 表变量 XPath 表达式
字符向量元胞数组 | 字符串数组

`VariableUnitsSelector` — 变量单位 XPath 表达式
字符向量 | 字符串标量

`RowNamesSelector` — 表行名称 XPath 表达式
字符向量 | 字符串标量

`RowSelector` — 表行 XPath 表达式
字符向量 | 字符串标量

`TableSelector` — 表数据 XPath 表达式
字符向量 | 字符串标量

`RegisteredNamespaces` — 注册的 XML 命名空间前缀集
字符串数组

`MissingRule` — 管理缺失数据的过程
`'fill'` (默认) | `'error'` | `'omitrow'` | `'omitvar'`

`ImportErrorRule` — 处理导入错误的过程
`'fill'` (默认) | `'error'` | `'omitrow'` | `'omitvar'`

`RepeatedNodeRule` — 处理重复 XML 节点的过程
`'addcol'` (默认) | `'ignore'` | `'error'`