Main Content

wordDocumentImportOptions

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

自 R2021b 起

    说明

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

    创建对象

    您可以使用 wordDocumentImportOptions 函数(下文介绍)或 detectImportOptions 函数创建 WordDocumentImportOptions 对象:

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

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

      opts = detectImportOptions(filename)

    描述

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

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

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

    示例

    输入参量

    全部展开

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

    属性

    全部展开

    变量属性

    变量名称,指定为字符向量元胞数组或字符串数组。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" 时,变量名称不会刷新。

    变量的数据类型,指定为字符向量元胞数组,或包含一组有效数据类型名称的字符串数组。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'} 只为导入操作选择两个变量,即 HeightLastName

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

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

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

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

    变量选项支持以下数据类型:数值、文本、logicaldatetimecategorical

    要查询变量的当前(或检测到的)选项,请使用 getvaropts 函数。

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

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

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

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

    位置属性

    表数据 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')]"

    数据位置,指定为正整数标量或由正整数标量组成的 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]

    示例: opts.DataRows = 5DataRows 属性设置为值 [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 属性指定包含行名称的列的位置。

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

    示例: opts.RowNamesColumn = 2;

    数据类型: single | double | uint8 | uint16 | uint32 | uint64

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

    如果 VariableNamesRow0,则不导入变量名称。否则,将从指定的行中导入变量名称。

    示例: opts.VariableNamesRow = 6;

    数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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

    如果 VariableUnitsRow0,则软件不会导入变量单位。否则,软件从指定的行导入变量单位。

    数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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

    如果 VariableDescriptionsRow0,则软件不会导入变量描述。否则,软件将从指定的行导入变量描述。

    数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    替代规则

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

    缺失规则行为
    'fill'

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

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

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

    示例: opts.MissingRule = 'omitrow';

    数据类型: char | string

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

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

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

    导入错误规则行为
    'fill'

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

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

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

    示例: opts.ImportErrorRule = 'omitvar';

    数据类型: char | string

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

    附加列规则行为
    'addvars'

    要导入附加列,需要创建新变量。如果有 N 个附加列,将以 'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN' 的形式导入新变量。导入附加列数据,就好像其 VariableTypeschar 一样。

    'ignore'忽略附加列数据。
    'wrap'将附加列数据换行到新记录中。此操作不会更改变量的数量。
    'error'显示错误消息并中止导入操作。

    数据类型: char | string

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

    导入规则行为
    "placeleft"

    将数据放在最左边的单元格中,并用 FillValue 属性的内容填充其余单元格。

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

    "placeright"

    将数据放在最右边的单元格中,并用 FillValue 属性的内容填充其余单元格。

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

    "duplicate"

    在所有单元格中复制数据。

    "omitrow"忽略出现合并单元格的行。
    "error"显示错误消息并中止导入操作。

    示例: "MergedCellColumnRule","placeright"

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

    导入规则行为
    "placetop"

    将数据放在顶部单元格中,并用 FillValue 属性的内容填充其余单元格。

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

    "placebottom"

    将数据放在底部单元格中,并用 FillValue 属性的内容填充其余单元格。

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

    "duplicate"

    在所有单元格中复制数据。

    "omitvar"忽略发生合并行的变量。
    "error"显示错误消息并中止导入操作。

    示例: "MergedCellRowRule","duplicate"

    对象函数

    示例

    全部折叠

    为 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 中推出