Main Content

wordDocumentImportOptions

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

    说明

    通过 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 属性的详细信息,请参阅 getvaropts

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

    示例: opts.MissingRule = 'omitrow';

    数据类型: char | string

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

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

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

    导入错误规则行为
    'fill'

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

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

    '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"显示错误消息并中止导入操作。

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

    导入错误规则行为
    "placetop"

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

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

    "placebottom"

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

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

    "duplicate"

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

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

    对象函数

    示例

    全部折叠

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