wordDocumentImportOptions

Microsoft Word 文档文件的导入选项对象

自 R2021b 起

全页展开

说明

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

创建对象

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

使用 wordDocumentImportOptions 根据导入要求定义导入属性。
使用 detectImportOptions 根据 filename 中指定的 Microsoft Word 文档的内容检测并填充导入属性。
```
opts = detectImportOptions(filename)
```

语法

opts = wordDocumentImportOptions

opts = wordDocumentImportOptions('NumVariables',numVars)

opts = wordDocumentImportOptions(___,Name,Value)

描述

opts = wordDocumentImportOptions 使用一个变量创建 WordDocumentImportOptions 对象。

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

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

示例

输入参量

全部展开

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

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

属性

全部展开

变量属性

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

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

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

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

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

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

数据类型: char | string | cell

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

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

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

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

`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。

位置属性

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

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

下表显示用于在 Microsoft Word 文档文件中选择表的一些示例 XPath 表达式。

描述	`TableSelector`
包含文本“Cash dividends”的表	`"//w:tbl[contains(.,'Cash dividends')]"`
行数超过 10 的第二个表	`"//w:tbl[count(w:tr)>10][2]"`
标题单元格与“Description”完全匹配的表	`"//w:tbl[w:tr[1]/w:tc='Description']"`

示例: 'TableSelector',"//w:tbl[contains(.,'Cash dividends')]"

`DataRows` — 数据位置
正整数标量 | 正整数标量数组

数据位置，指定为正整数标量或由正整数标量组成的 N-×-2 数组。使用以下形式之一指定 DataRows。

指定为	描述
`n`	指定包含数据的第一个行。使用 `n` 指定值会将 `DataRows` 属性的值设置为 `[n inf]`。导入函数读取从第 `n` 行到文件结尾之间的所有行。 `n` 必须是大于零的正整数。
`[n1 n2]`	指定包含数据的行范围。`n1` 是包含数据的第一个行，`n2` 是包含数据的最后一个行。数组 `[n1 n2]` 中的值必须为非零正整数，且 `n2` 必须大于 `n1`。
`[n1 n2; n3 n4;...]`	使用包含 `N` 个不同行范围的 `N`×`2` 数组来指定要读取的多个行范围。包含多个行范围的有效数组必须满足以下条件：以升序指定行范围，也就是说，数组中指定的第一个行范围出现在文件中的其他行范围之前。仅包含不重叠的行范围。指定多个行范围时，仅在指定数组中最后一个行范围的结尾时使用 `Inf`。例如，`[1 3; 5 6; 8 Inf]`。

指定为

描述

n

指定包含数据的第一个行。使用 n 指定值会将 DataRows 属性的值设置为 [n inf]。导入函数读取从第 n 行到文件结尾之间的所有行。

n 必须是大于零的正整数。

[n1 n2]

指定包含数据的行范围。n1 是包含数据的第一个行，n2 是包含数据的最后一个行。

数组 [n1 n2] 中的值必须为非零正整数，且 n2 必须大于 n1。

[n1 n2; n3 n4;...]

使用包含 N 个不同行范围的 N×2 数组来指定要读取的多个行范围。

包含多个行范围的有效数组必须满足以下条件：

以升序指定行范围，也就是说，数组中指定的第一个行范围出现在文件中的其他行范围之前。
仅包含不重叠的行范围。

指定多个行范围时，仅在指定数组中最后一个行范围的结尾时使用 Inf。例如，[1 3; 5 6; 8 Inf]。

示例: opts.DataRows = 5 将 DataRows 属性设置为值 [5 inf]。读取从第 5 行开始到文件结尾之间的所有数据行。

示例: opts.DataRows = [2 6] 将属性设置为读取第 2 行到第 6 行。

示例: opts.DataRows = [1 3; 5 6; 8 inf] 将属性设置为读取第 1 行、第 2 行、第 3 行、第 5 行、第 6 行以及从第 8 行到文件结尾之间的所有行。

`RowNamesColumn` — 行名称的位置
`0` (默认) | 正整数标量

行名称的位置，指定为正整数标量。RowNamesColumn 属性指定包含行名称的列的位置。

如果 RowNamesColumn 指定为 0，则不导入行名称。否则，将从指定的列中导入行名称。

示例: opts.RowNamesColumn = 2;

`VariableNamesRow` — 包含变量名称的行
`0` (默认) | 非负整数

包含变量名称的行，指定为非负整数。VariableNamesRow 属性指定变量名称所在的行号。

如果 VariableNamesRow 为 0，则不导入变量名称。否则，将从指定的行中导入变量名称。

示例: opts.VariableNamesRow = 6;

`VariableUnitsRow` — 包含变量单位的行
`0` (默认) | 非负整数

包含变量单位的行，指定为非负整数。

如果 VariableUnitsRow 为 0，则软件不会导入变量单位。否则，软件从指定的行导入变量单位。

`VariableDescriptionsRow` — 包含变量描述的行
`0` (默认) | 非负整数

包含变量描述的行，指定为非负整数。

如果 VariableDescriptionsRow 为 0，则软件不会导入变量描述。否则，软件将从指定的行导入变量描述。

替代规则

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

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

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

示例: opts.MissingRule = 'omitrow';

数据类型: char | string

`EmptyRowRule` — 处理空行的方式
`"skip"` (默认) | `"read"` | `"error"`

处理数据中的空行的方式，指定为 "skip"、"read" 或 "error"。导入函数将空白解释为空。

空行规则	行为
`"skip"`	跳过空行。
`"read"`	导入空行。导入函数根据在 `VariableOptions`、`MissingRule` 中指定的值和其他相关属性来解析空行。
`"error"`	显示错误消息并中止导入操作。

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

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

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

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

`ExtraColumnsRule` — 处理附加列的过程
`'addvars'` | `'ignore'` | `'wrap'` | `'error'`

处理数据中的附加列的过程，指定为下表中的值之一。

附加列规则	行为
`'addvars'`	要导入附加列，需要创建新变量。如果有 `N` 个附加列，将以 `'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN'` 的形式导入新变量。导入附加列数据，就好像其 `VariableTypes` 是 `char` 一样。
`'ignore'`	忽略附加列数据。
`'wrap'`	将附加列数据换行到新记录中。此操作不会更改变量的数量。
`'error'`	显示错误消息并中止导入操作。

数据类型: char | string

`MergedCellColumnRule` — 处理具有合并列的单元格的过程
`"placeleft"` (默认) | `"placeright"` | `"duplicate"` | `"omitrow"` | `"error"`

处理具有合并列的单元格的过程，指定为下表中的值之一。

导入规则	行为
`"placeleft"`	将数据放在最左边的单元格中，并用 `FillValue` 属性的内容填充其余单元格。 `FillValue` 属性在要导入的变量的 `VariableImportOptions` 对象中指定。有关访问 `FillValue` 属性的详细信息，请参阅 `getvaropts`。
`"placeright"`	将数据放在最右边的单元格中，并用 `FillValue` 属性的内容填充其余单元格。 `FillValue` 属性在要导入的变量的 `VariableImportOptions` 对象中指定。有关访问 `FillValue` 属性的详细信息，请参阅 `getvaropts`。
`"duplicate"`	在所有单元格中复制数据。
`"omitrow"`	忽略出现合并单元格的行。
`"error"`	显示错误消息并中止导入操作。

示例: "MergedCellColumnRule","placeright"

`MergedCellRowRule` — 处理具有合并行的单元格的过程
`"placetop"` (默认) | `"placebottom"` | `"duplicate"` | `"omitvar"` | `"error"`

处理具有合并行的单元格的过程，指定为下表中的值之一。

导入规则	行为
`"placetop"`	将数据放在顶部单元格中，并用 `FillValue` 属性的内容填充其余单元格。 `FillValue` 属性在要导入的变量的 `VariableImportOptions` 对象中指定。有关访问 `FillValue` 属性的详细信息，请参阅 `getvaropts`。
`"placebottom"`	将数据放在底部单元格中，并用 `FillValue` 属性的内容填充其余单元格。 `FillValue` 属性在要导入的变量的 `VariableImportOptions` 对象中指定。有关访问 `FillValue` 属性的详细信息，请参阅 `getvaropts`。
`"duplicate"`	在所有单元格中复制数据。
`"omitvar"`	忽略发生合并行的变量。
`"error"`	显示错误消息并中止导入操作。

示例: "MergedCellRowRule","duplicate"

对象函数

示例

全部折叠

为 Microsoft Word 文档文件创建导入选项

打开实时脚本

为 Microsoft Word 文档文件创建导入选项，指定要导入的表，然后读取数据。

文件 MaintenanceReport.docx 包含两个表。第二个表的最后一行包含一个其合并列与表变量不匹配的单元格。

创建一个 WordDocumentImportOptions 对象：

从表中读取五个变量。
使用 XPath 查询 "//w:tbl[contains(.,'Description')]" 读取包含单词“Description”的第一个表。
从第一行读取变量名称。
跳过读取包含合并列的单元格的行。

opts = wordDocumentImportOptions( ...
    'NumVariables',5, ...
    'TableSelector',"//w:tbl[contains(.,'Description')]", ...
    'VariableNamesRow',1, ...
    'MergedCellColumnRule','omitrow')

opts = 
  WordDocumentImportOptions with properties:

   Replacement Properties:
                MissingRule: "fill"
            ImportErrorRule: "fill"
               EmptyRowRule: "skip"
       MergedCellColumnRule: "omitrow"
          MergedCellRowRule: "placetop"
           ExtraColumnsRule: "addvars"

   Variable Import Properties: Set types by name using setvartype
              VariableNames: ["Var1"    "Var2"    "Var3"    "Var4"    "Var5"]
              VariableTypes: ["char"    "char"    "char"    "char"    "char"]
      SelectedVariableNames: ["Var1"    "Var2"    "Var3"    "Var4"    "Var5"]
            VariableOptions: Show all 5 VariableOptions 
	Access VariableOptions sub-properties using setvaropts/getvaropts
         VariableNamingRule: "preserve"

   Location Properties:
              TableSelector: "//w:tbl[contains(.,'Description')]"
                   DataRows: [1 Inf]
           VariableNamesRow: 1
           VariableUnitsRow: 0
    VariableDescriptionsRow: 0
             RowNamesColumn: 0

使用带有选项对象的 readtable 函数从 Microsoft Word 文档文件中读取表。

filename = "MaintenanceReport.docx";
T = readtable(filename,opts)

T=4×5 table
                                  Description                                         Category             Urgency           Resolution            Cost   
    _______________________________________________________________________    ______________________    ___________    ____________________    __________

    {'Description'                                                        }    {'Category'          }    {'Urgency'}    {'Resolution'      }    {'Cost'  }
    {'Items are occasionally getting stuck in the scanner spools.'        }    {'Mechanical Failure'}    {'Medium' }    {'Readjust Machine'}    {'$45'   }
    {'Loud rattling and banging sounds are coming from assembler pistons.'}    {'Mechanical Failure'}    {'Medium' }    {'Readjust Machine'}    {'$35'   }
    {'There are cuts to the power when starting the plant.'               }    {'Electronic Failure'}    {'High'   }    {'Full Replacement'}    {'$16200'}

版本历史记录

在 R2021b 中推出

另请参阅

detectImportOptions | readtable | readtimetable

wordDocumentImportOptions

说明

创建对象

语法

描述

输入参量

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

属性

变量属性

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

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

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

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

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

位置属性

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

DataRows — 数据位置 正整数标量 | 正整数标量数组

RowNamesColumn — 行名称的位置 0 (默认) | 正整数标量

VariableNamesRow — 包含变量名称的行 0 (默认) | 非负整数

VariableUnitsRow — 包含变量单位的行 0 (默认) | 非负整数

VariableDescriptionsRow — 包含变量描述的行 0 (默认) | 非负整数

替代规则

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

EmptyRowRule — 处理空行的方式 "skip" (默认) | "read" | "error"

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

ExtraColumnsRule — 处理附加列的过程 'addvars' | 'ignore' | 'wrap' | 'error'

MergedCellColumnRule — 处理具有合并列的单元格的过程 "placeleft" (默认) | "placeright" | "duplicate" | "omitrow" | "error"

MergedCellRowRule — 处理具有合并行的单元格的过程 "placetop" (默认) | "placebottom" | "duplicate" | "omitvar" | "error"

对象函数

示例

为 Microsoft Word 文档文件创建导入选项

版本历史记录

另请参阅

主题

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

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

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

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

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

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

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

`DataRows` — 数据位置
正整数标量 | 正整数标量数组

`RowNamesColumn` — 行名称的位置
`0` (默认) | 正整数标量

`VariableNamesRow` — 包含变量名称的行
`0` (默认) | 非负整数

`VariableUnitsRow` — 包含变量单位的行
`0` (默认) | 非负整数

`VariableDescriptionsRow` — 包含变量描述的行
`0` (默认) | 非负整数

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

`EmptyRowRule` — 处理空行的方式
`"skip"` (默认) | `"read"` | `"error"`

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

`ExtraColumnsRule` — 处理附加列的过程
`'addvars'` | `'ignore'` | `'wrap'` | `'error'`

`MergedCellColumnRule` — 处理具有合并列的单元格的过程
`"placeleft"` (默认) | `"placeright"` | `"duplicate"` | `"omitrow"` | `"error"`

`MergedCellRowRule` — 处理具有合并行的单元格的过程
`"placetop"` (默认) | `"placebottom"` | `"duplicate"` | `"omitvar"` | `"error"`