wordDocumentImportOptions
说明
通过 WordDocumentImportOptions
对象,您可以指定 MATLAB® 如何从 Microsoft® Word 文档文件中导入结构化表格数据。此对象包含的属性可以控制数据导入过程,包括如何处理错误和缺失的数据。
创建对象
您可以使用 wordDocumentImportOptions
函数(下文介绍)或 detectImportOptions
函数创建 WordDocumentImportOptions
对象:
使用
wordDocumentImportOptions
根据导入要求定义导入属性。使用
detectImportOptions
根据filename
中指定的 Microsoft Word 文档的内容检测并填充导入属性。opts = detectImportOptions(filename)
语法
描述
输入参量
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
属性中指定的变量。
数据类型: uint16
| uint32
| uint64
| char
| string
| cell
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
。
指定为 | 描述 |
---|---|
| 指定包含数据的第一个行。使用
|
| 指定包含数据的行范围。 数组 |
| 使用包含 包含多个行范围的有效数组必须满足以下条件:
指定多个行范围时,仅在指定数组中最后一个行范围的结尾时使用 |
示例: 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
行到文件末尾之间的所有行。
数据类型: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
RowNamesColumn
— 行名称的位置
0
(默认) | 正整数标量
行名称的位置,指定为正整数标量。RowNamesColumn
属性指定包含行名称的列的位置。
如果 RowNamesColumn
指定为 0,则不导入行名称。否则,将从指定的列中导入行名称。
示例: opts.RowNamesColumn = 2;
数据类型: single
| double
| uint8
| uint16
| uint32
| uint64
VariableNamesRow
— 包含变量名称的行
0
(默认) | 非负整数
包含变量名称的行,指定为非负整数。VariableNamesRow
属性指定变量名称所在的行号。
如果 VariableNamesRow
为 0
,则不导入变量名称。否则,将从指定的行中导入变量名称。
示例: opts.VariableNamesRow = 6;
数据类型: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
VariableUnitsRow
— 包含变量单位的行
0
(默认) | 非负整数
包含变量单位的行,指定为非负整数。
如果 VariableUnitsRow
为 0
,则软件不会导入变量单位。否则,软件从指定的行导入变量单位。
数据类型: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
VariableDescriptionsRow
— 包含变量描述的行
0
(默认) | 非负整数
包含变量描述的行,指定为非负整数。
如果 VariableDescriptionsRow
为 0
,则软件不会导入变量描述。否则,软件将从指定的行导入变量描述。
数据类型: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
替代规则
MissingRule
— 管理缺失数据的过程
'fill'
(默认) | 'error'
| 'omitrow'
| 'omitvar'
管理缺失数据的过程,指定为下表中的值之一。
缺失规则 | 行为 |
---|---|
'fill' | 用
|
'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' | 用
|
'error' | 停止导入并显示一条错误消息,指出导致出错的记录和字段。 |
'omitrow' | 忽略发生错误的行。 |
'omitvar' | 忽略发生错误的变量。 |
示例: opts.ImportErrorRule = 'omitvar';
数据类型: char
| string
ExtraColumnsRule
— 处理附加列的过程
'addvars'
| 'ignore'
| 'wrap'
| 'error'
处理数据中的附加列的过程,指定为下表中的值之一。
附加列规则 | 行为 |
---|---|
'addvars' | 要导入附加列,需要创建新变量。如果有 |
'ignore' | 忽略附加列数据。 |
'wrap' | 将附加列数据换行到新记录中。此操作不会更改变量的数量。 |
'error' | 显示错误消息并中止导入操作。 |
数据类型: char
| string
MergedCellColumnRule
— 处理具有合并列的单元格的过程
"placeleft"
(默认) | "placeright"
| "duplicate"
| "omitrow"
| "error"
处理具有合并列的单元格的过程,指定为下表中的值之一。
导入规则 | 行为 |
---|---|
"placeleft" | 将数据放在最左边的单元格中,并用
|
"placeright" | 将数据放在最右边的单元格中,并用
|
"duplicate" | 在所有单元格中复制数据。 |
"omitrow" | 忽略出现合并单元格的行。 |
"error" | 显示错误消息并中止导入操作。 |
示例: "MergedCellColumnRule","placeright"
MergedCellRowRule
— 处理具有合并行的单元格的过程
"placetop"
(默认) | "placebottom"
| "duplicate"
| "omitvar"
| "error"
处理具有合并行的单元格的过程,指定为下表中的值之一。
导入规则 | 行为 |
---|---|
"placetop" | 将数据放在顶部单元格中,并用
|
"placebottom" | 将数据放在底部单元格中,并用
|
"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: [1-by-5 matlab.io.VariableImportOptions] 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 中推出
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)