Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

detectImportOptions

基于文件内容生成导入选项

说明

示例

opts = detectImportOptions(filename) 在文件中找到一个表并返回其导入选项。您可以修改选项对象,并将它与 readtable 一起使用以控制 MATLAB® 如何导入表格数据。返回的选项类型取决于文件扩展名。例如,如果 filename 为电子表格文件,该函数返回 SpreadsheetImportOptions 对象。但是,如果 filename 是文本文件,则该函数返回 DelimitedTextImportOptionsFixedWidthImportOptions 对象;如果 filename 是 XML 文件,则返回 XMLImportOptions 对象;如果 filename 是 HTML 文件,则返回 HTMLImportOptions 对象;如果 filenameMicrosoft® Word 文档,则返回 WordDocumentImportOptions 对象。

示例

opts = detectImportOptions(filename,Name,Value) 在由一个或多个 Name,Value 对组参量指定的附加参量的辅助下,在文件中查找表。

示例

全部折叠

使用导入选项对象配置 readtable 解释文件的方式。例如,使用导入选项对象仅从电子表格文件中读取指定的变量。

首先,通过使用 detectImportOptions 检测电子表格文件的各个方面(包括变量名称和类型),从文件创建一个导入选项对象。在本例中,detectImportOptions 会创建一个 SpreadsheetImportOptions 对象。

opts = detectImportOptions("patients.xls")
opts = 
  SpreadsheetImportOptions with properties:

   Sheet Properties:
                        Sheet: ''

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'

   Variable Import Properties: Set types by name using setvartype
                VariableNames: {'LastName', 'Gender', 'Age' ... and 7 more}
                VariableTypes: {'char', 'char', 'double' ... and 7 more}
        SelectedVariableNames: {'LastName', 'Gender', 'Age' ... and 7 more}
              VariableOptions: [1-by-10 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
           VariableNamingRule: 'modify'

   Range Properties:
                    DataRange: 'A2' (Start Cell)
           VariableNamesRange: 'A1'
                RowNamesRange: ''
           VariableUnitsRange: ''
    VariableDescriptionsRange: '' 
	To display a preview of the table, use preview

通过修改导入选项对象来指定要导入的变量。然后,使用 readtable 和导入选项对象导入指定的变量。显示表的前 5 行。

opts.SelectedVariableNames = ["Systolic","Diastolic"];
T = readtable("patients.xls",opts);
T(1:5,:)
ans=5×2 table
    Systolic    Diastolic
    ________    _________

      124          93    
      109          77    
      125          83    
      117          75    
      122          80    

使用导入选项对象配置 readtable 解释文件的方式。例如,使用导入选项对象仅读取文本文件的一部分内容。

首先,使用 detectImportOptions 创建一个导入选项对象来检测文本文件的各个方面,包括变量名称和类型、分隔符以及空白字符。在本例中,detectImportOptions 会创建一个 DelimitedTextImportOptions 对象。

opts = detectImportOptions("airlinesmall.csv")
opts = 
  DelimitedTextImportOptions with properties:

   Format Properties:
                    Delimiter: {','}
                   Whitespace: '\b\t '
                   LineEnding: {'\n'  '\r'  '\r\n'}
                 CommentStyle: {}
    ConsecutiveDelimitersRule: 'split'
        LeadingDelimitersRule: 'keep'
       TrailingDelimitersRule: 'ignore'
                EmptyLineRule: 'skip'
                     Encoding: 'ISO-8859-1'

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'
             ExtraColumnsRule: 'addvars'

   Variable Import Properties: Set types by name using setvartype
                VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
                VariableTypes: {'double', 'double', 'double' ... and 26 more}
        SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
              VariableOptions: [1-by-29 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
           VariableNamingRule: 'modify'

   Location Properties:
                    DataLines: [2 Inf]
            VariableNamesLine: 1
               RowNamesColumn: 0
            VariableUnitsLine: 0
     VariableDescriptionsLine: 0 
	To display a preview of the table, use preview

通过修改导入选项对象来指定要导入的变量子集。然后,使用 readtable 和导入选项对象导入数据子集。

opts.SelectedVariableNames = ["TaxiIn","TaxiOut"];
T = readtable("airlinesmall.csv",opts);

检测 Microsoft Word 文档文件的导入选项,指定要导入的表,然后读取数据。

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

使用 detectImportOptions 函数检测导入选项。通过将 TableIndex 设置为 2 来指定从第二个表中读取。

filename = "MaintenanceReport.docx";
opts = detectImportOptions(filename,'TableIndex',2)
opts = 
  WordDocumentImportOptions with properties:

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

   Variable Import Properties: Set types by name using setvartype
              VariableNames: ["Description"    "Category"    "Urgency"    "Resolution"    "Cost"]
              VariableTypes: ["string"    "string"    "string"    "string"    "string"]
      SelectedVariableNames: ["Description"    "Category"    "Urgency"    "Resolution"    "Cost"]
            VariableOptions: [1-by-5 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
         VariableNamingRule: "preserve"

   Location Properties:
              TableSelector: "(//w:tbl)[2]"
                   DataRows: [2 Inf]
           VariableNamesRow: 1
           VariableUnitsRow: 0
    VariableDescriptionsRow: 0
             RowNamesColumn: 0

要跳过读取包含具有合并列的单元格的行,请将 MergedCellColumnRule 属性设置为 'omitrow'

opts.MergedCellColumnRule = 'omitrow';

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

filename = "MaintenanceReport.docx";
T = readtable(filename,opts)
T=3×5 table
                                 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"

检测 HTML 文件的导入选项,指定要导入的表,然后读取数据。

从包含文本“readtable”的 URL https://www.mathworks.com/help/matlab/text-files.html 中检测第一个表的导入选项。使用 detectImportOptions 函数检测导入选项,并使用 XPath 查询 "//TABLE[contains(.,'readtable')]" 指定要读取的表。通过将 ReadVariableNames 设置为 false 来指定不读取变量名称。

url = "https://www.mathworks.com/help/matlab/text-files.html";
opts = detectImportOptions(url,'TableSelector',"//TABLE[contains(.,'readtable')]",'ReadVariableNames',false)
opts = 
  HTMLImportOptions with properties:

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

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

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

使用 readtable 函数读取表。

T = readtable(url,opts)
T=4×2 table
          Var1                      Var2            
    ________________    ____________________________

    "readtable"         "Create table from file"    
    "writetable"        "Write table to file"       
    "readtimetable"     "Create timetable from file"
    "writetimetable"    "Write timetable to file"   

通过指定导入选项将文本数据作为字符串数据类型导入。

为文件创建选项对象。

opts = detectImportOptions('outages.csv');

使用 readtable 指定要导入的变量,然后显示摘要。所选变量的数据类型是 char

opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts);
summary(T)
Variables:

    Region: 1468x1 cell array of character vectors

    Cause: 1468x1 cell array of character vectors

将文本数据作为 string 数据类型导入,然后通过指定 TextType 名称-值对组创建导入选项。

opts = detectImportOptions('outages.csv','TextType','string');

使用 readtable 指定要导入的变量,然后显示摘要。所选变量的数据类型现在是 string

opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts);
summary(T)
Variables:

    Region: 1468x1 string

    Cause: 1468x1 string

将 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"  

输入参数

全部折叠

要读取的文件的名称,指定为字符向量或字符串标量。

根据文件的位置,filename 可以采用下列形式之一。

位置

形式

当前文件夹或 MATLAB 路径上的文件夹

指定 filename 中文件的名称。

例如:'myFile.txt'

文件夹中的文件

如果该文件不在当前文件夹或 MATLAB 路径下的文件夹中,则在 filename 中指定完整或相对路径名。

例如:'C:\myFolder\myFile.xlsx'

例如:'\imgDir\myFile.txt'

Internet URL

如果文件指定为 Internet 统一资源定位器 (URL),则 filename 必须包含协议类型 'http://''https://'

例如:'http://hostname/path_to_file/my_data.csv'

远程位置

如果文件存储在远程位置,则 filename 必须包含用以下格式指定的文件的完整路径:

scheme_name://path_to_file/my_file.ext

根据远程位置,scheme_name 可以是下表中的值之一。

远程位置scheme_name
Amazon S3™s3
Windows Azure® Blob 存储wasb, wasbs
HDFS™hdfs

有关详细信息,请参阅处理远程数据

例如:'s3://bucketname/path_to_file/my_file.csv'

如果 filename 包含文件扩展名,则 detectImportOptions 基于扩展名确定文件格式。否则,您必须指定 'FileType' 名称-值对组以指示文件类型。

detectImportOptions 函数支持以下文件扩展名:.txt.dat.csv.xls.xlsb.xlsm.xlsx.xltm.xltx.ods.xml.docx.html.xhtml.htm

注意

只有在使用了 Windows® 版 Excel® 的平台上才支持文件扩展台 .xlsb.ods

数据类型: char | string

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN,其中 Name 是参量名称,Value 是对应的值。名称-值参量必须出现在其他参量之后,但参量对组的顺序无关紧要。

在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name 引起来。

示例: 'FileType','spreadsheet'

所有支持的文件类型

全部折叠

文件类型,指定为以逗号分隔的对组,该对组由 'FileType' 和下列值之一组成。

文件的导入选项
'spreadsheet'

返回 SpreadsheetImportOptions 对象。

'text'

根据文本文件的布局,返回 DelimitedTextImportOptionsFixedWidthImportOptions 对象。

'delimitedtext'

返回 DelimitedTextImportOptions 对象。对于用分隔符分隔列的文本文件,请使用此选项。

'fixedwidth'

返回 FixedWidthImportOptions 对象。对于具有等宽列的文本文件,请使用此选项。

'xml'

返回 XMLImportOptions 对象。对 XML 文件使用此选项。

'worddocument'

返回 WordDocumentImportOptions 对象。对 Microsoft Word 文档文件使用此选项。

'html'

返回 HTMLImportOptions 对象。对 HTML 文件使用此选项。

filename 不包含文件扩展名时,或当扩展名不是以下项之一时,请使用 'FileType' 名称-值对组参量:

  • .txt.dat.csv(文本文件)

  • .xls.xlsb.xlsm.xlsx.xltm.xltx.ods(电子表格文件)

  • .xml(XML 文件)

  • .docxMicrosoft Word 文档文件)

  • .html.xhtml.htm(HTML 文件)

只有在使用了 Windows 版 Excel 的平台上才支持文件扩展台 .xlsb.ods

示例: 'FileType','text'

数据类型: char | string

导入文本数据的类型,指定为以下值之一:

  • "string" - 将文本数据作为字符串数组导入。

  • "char" - 将文本数据作为字符向量导入。

示例: "TextType","char"

导入的日期和时间数据的类型,指定为以下值之一:

描述
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

如果将 "DatetimeType" 指定为 "text",则导入日期时间数据的类型取决于 "TextType" 参数中指定的值:

  • 如果 "TextType" 设置为 "char",则导入函数会以字符向量元胞数组的形式返回日期。

  • 如果 "TextType" 设置为 "string",则导入函数会以字符串数组形式返回日期。

"exceldatenum"

Excel 日期序列值

"exceldatenum" 仅适用于电子表格文件,对文本文件无效。日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

读取第一行以作为变量名称的指示符,指定为逗号分隔的对组,包含 'ReadVariableNames'truefalse。如果未指定,readtable 将自动检测是否存在变量名称。

指示符

描述

true

当要读取的区域的第一行包含表格的变量名称时使用。readtable 将使用检测到的变量名称为 T 中的每列创建一个变量。

false

当要读取的区域的第一行包含表格中的数据时使用。readtable 将创建 'Var1',...,'VarN' 形式的默认变量名称,其中 N 是变量的数量。

未指定 未指定时,导入函数会自动检测 truefalse,并相应地继续后续步骤。

数据类型: logical

保留变量名称的标志,指定为 "modify""preserve"

  • "modify" - 将无效变量名称(由 isvarname 函数确定)转换为有效的 MATLAB 标识符。

  • "preserve" - 保留作为无效 MATLAB 标识符的变量名称,如包含空白和非 ASCII 字符的变量名称。

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

数据类型: char | string

读取第一列以作为行名称的指示符,指定为逗号分隔的对组,包含 'ReadRowNames'falsetrue

指示符

描述

false

当要读取的区域第一列包含的是数据而不是表的行名称时使用。

true

当要读取的区域第一列包含表的行名称时使用。

未指定未指定时,导入函数假设为 false

数据类型: logical

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

缺失规则行为
'fill'

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

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

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

示例: opts.MissingRule = 'omitrow';

数据类型: char | string

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

导入错误规则行为
'fill'

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

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

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

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

HTTPHTTPS 请求选项,指定为 weboptions 对象。当指定的 filename 是包含协议类型 "http://""https://" 的 Internet URL 时,由 weboptions 对象确定如何导入数据。

文本和电子表格文件

全部折叠

需要的变量数目,指定为包含 'ExpectedNumVariables' 和正整数的逗号分隔对组。如果未指定,则导入函数会自动检测变量数目。

数据类型: single | double

文件中标题行的数目,指定为以逗号分隔的对组,其中包含 'NumHeaderLines' 和一个正整数。如果未指定,则导入函数会自动检测文件中标题行的数目。

示例: 'NumHeaderLines',7

数据类型: single | double

要从文本文件或电子表格文件中读取的数据部分,指定为以逗号分隔的对组,其中包含 'Range' 和采用以下形式之一的字符向量、字符串标量或数值向量。

指定 Range 的方式描述

起始单元格

'Cell'[row col]

将数据的起始单元格指定为字符向量、字符串标量或二元素数值向量。

  • 字符向量或字符串标量,其中包含使用 Excel A1 表示法的列字母和行号。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

  • 二元素数值向量,形式为 [row col],表示起始行和列。

根据起始单元格,导入函数通过从起始单元格开始导入,并在到达最后一个空行或页脚范围时结束,从而自动检测数据范围。

例如:'A5'[5 1]

矩形范围

'Corner1:Corner2'[r1 c1 r2 c2]

使用以下形式之一的矩形范围指定要读取的精确范围。

  • 'Corner1:Corner2' - 使用 Corner1Corner2 指定范围,这两个对角以 Excel A1 表示法定义要读取的区域。例如,'C2:N15'

  • [r1 c1 r2 c2] - 使用包含起始行、起始列、结束行和结束列的四元素数值向量指定范围。例如,[2 3 15 13]

导入函数只读取指定范围内包含的数据。指定范围内的任何空字段都作为缺失单元导入。

行范围或列范围

'Row1:Row2''Column1:Column2'

通过使用 Excel 行号标识起始行和结束行来指定范围。

根据指定的行范围,导入函数通过从第一个非空列开始读取,一直到数据的最后,从而自动检测列范围,并为每一列创建一个变量。

例如:'5:500'

也可以通过使用 Excel 列字母或列号标识起始列和结束列来指定范围。

根据指定的列范围,导入函数通过从第一个非空行开始读取,一直到数据的最后或页脚范围,从而自动检测行范围。

指定范围内的列数必须与 ExpectedNumVariables 属性中指定的数字匹配。

例如:'A:K'

起始行号

n

使用正标量行索引指定包含数据的第一行。

根据指定的行索引,导入函数通过从指定的第一行开始读取,一直到数据的最后或页脚范围,从而自动检测数据范围。

示例:5

Excel 中的命名范围

'NamedRange'

在 Excel 中,您可以创建名称来标识电子表格中的范围。例如,您可以选择电子表格的一个矩形部分,并将其命名为 'myTable'。如果电子表格中存在此类命名范围,则导入函数可以使用它的名称来读取该范围。

例如:'Range','myTable'

未指定或为空

''

如果未指定,则导入函数会自动检测使用的范围。

例如:'Range',''

注意:使用范围指电子表格中实际包含数据的矩形部分。导入函数通过删减不包含数据的前导行列和尾随行列,自动检测使用范围。只包含空白的文本被视为数据,并会在使用范围内被捕获。

数据类型: char | string | double

仅限电子表格文件的参数

全部折叠

要从中读取数据的工作表,指定为空字符数组、包含工作表名称的字符向量或字符串标量,或表示工作表索引的正整数标量。根据为 Sheet 属性指定的值,导入函数的行为如下表中所述。

指定的值行为
''(默认值)从第一个工作表导入数据。
名称从具有匹配名称的工作表中导入数据,不考虑电子表格文件中工作表的顺序。
整数从由整数指定的位置的工作表导入数据,不考虑电子表格文件中的工作表名称。

数据类型: char | string | single | double

要导入的数据的位置,指定为字符向量、字符串标量、字符向量元胞数组、字符串数组、正整数标量或由正整数标量组成的 N×2 数组。使用以下形式之一指定 DataRange

行为

'Cell'n

起始单元格或起始行

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

根据起始单元格,导入函数通过从起始单元格开始导入,并在到达最后一个空行或页脚范围时结束,从而自动检测数据范围。

也可以使用正标量行索引指定包含数据的第一行。

根据指定的行索引,导入函数通过从指定的第一行开始读取,一直到数据的最后或页脚范围,从而自动检测数据范围。

例如:'A5'5

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

导入函数只读取指定范围内包含的数据。指定范围内的任何空字段都作为缺失单元导入。

列数必须与 NumVariables 属性中的指定的数字匹配。

例如:'A5:K50'

'Row1:Row2''Column1:Column2'

行范围或列范围

通过使用 Excel 行号标识起始行和结束行来指定范围。

根据指定的行范围,导入函数通过从第一个非空列开始读取,一直到数据的最后,从而自动检测列范围,并为每一列创建一个变量。

例如:'5:500'

也可以通过使用 Excel 列字母或列号标识起始列和结束列来指定范围。

根据指定的列范围,导入函数通过从第一个非空行开始读取,一直到数据的最后或页脚范围,从而自动检测行范围。

指定范围内的列数必须与 NumVariables 属性中指定的数字匹配。

例如:'A:K'

[n1 n2; n3 n4;...]

多个行范围

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

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

  • 以递增顺序指定行范围,也就是说,数组中指定的第一个行范围出现在文件中的其他行范围之前。

  • 仅包含不重叠的行范围。

Inf 只能用来指示指定了多个行范围的数组中的最后一个范围。例如,[1 3; 5 6; 8 Inf]

例如:[1 3; 5 6; 8 Inf]

''

未指定或为空

不获取任何数据。

例如:''

数据类型: char | string | cell | single | double

行名称的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 RowNamesRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量标识一个名称。

例如:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

RowNamesRange 中包含的行数必须与数据行的数量匹配,而且 RowNamesRange 指示的范围只能跨一列。

例如:'A5:A50'

'Row1:Row2'

行范围

通过使用 Excel 行号标识起始行和结束行来指定范围。

行名称必须在单独一列中。

例如:'5:50'

n

数字索引

使用正标量列索引指定包含行名称的列。

例如:5

''

未指定或为空

指示没有行名称。

例如:''

数据类型: char | single | double

变量名称的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 VariableNamesRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量读取一个名称。

例如:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

列数必须与 NumVariables 属性中指定的数字匹配,而且范围只能跨一行。

例如:'A5:K5'

'Row1:Row2'

行范围

通过使用 Excel 行号标识起始行和结束行来指定范围。

必须为一行。

例如:'5:5'

n

数字索引

使用正标量行索引指定包含变量名称的行。

例如:5

''

未指定或为空

指示没有变量名称。

例如:''

数据类型: char | single | double

变量单位的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 VariableUnitsRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量读取一个单位。

例如:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

列数必须与 NumVariables 属性中指定的数字匹配,而且范围只能跨一行。

例如:'A5:K5'

'Row1:Row2'

行范围

通过使用 Excel 行号标识起始行和结束行来指定范围。

必须为一行。

例如:'5:5'

n

数字索引

使用正标量行索引指定包含数据单位的行。

例如:5

''

未指定或为空

指示没有变量单位。

例如:''

数据类型: char | string | single | double

变量描述的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 VariableDescriptionRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量读取一个描述。

例如:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

列数必须与 NumVariables 属性中指定的数字匹配,而且范围只能跨一行。

例如:'A5:K5'

'Row1:Row2'

行范围

通过使用 Excel 行号标识起始行和结束行来指定范围。

必须为一行。

例如:'5:5'

n

数字索引

使用正标量行索引指定包含描述的行。

例如:5

''

未指定或为空

指示没有变量描述。

例如:''

数据类型: char | string | single | double

仅限文本文件的参数

全部折叠

带分隔符的文本文件中的字段分隔符,指定为字符串数组、字符向量或字符向量元胞数组。

示例: "Delimiter","|"

示例: "Delimiter",[";","*"]

管理带分隔符的文本文件中的前导分隔符的过程,指定为下表中的值之一。

行为
"keep"保留分隔符。
"ignore"忽略分隔符。
"error"返回错误并取消导入操作。

管理带分隔符的文本文件中的尾部分隔符的过程,指定为下表中的值之一。

前导分隔符规则行为
'keep'保留分隔符。
'ignore'忽略分隔符。
'error'返回错误并中止导入操作。

管理带分隔符的文本文件中的连续分隔符的过程,指定为下表中的值之一。

行为
"split"将连续分隔符拆分为多个字段。
"join"将多个分隔符合并成一个分隔符。
"error"返回错误并取消导入操作。

等宽文本文件中变量的字段宽度,指定为正整数值向量。该向量中的每个正整数对应于一个字段中构成变量的字符数。对于 VariableNames 属性中指定的每个变量,VariableWidths 属性中均包含一个对应的条目。

要视为空白的字符,指定为包含一个或多个字符的字符向量或字符串标量。

示例: 'Whitespace',' _'

示例: 'Whitespace','?!.,'

行尾字符,指定为字符串数组、字符向量或字符向量元胞数组。

示例: "LineEnding","\n"

示例: "LineEnding","\r\n"

示例: "LineEnding",["\b",":"]

与文件关联的字符编码方案,指定为以逗号分隔的对组,其中包含 'Encoding''system' 或标准字符编码方案名称。

如果您没有指定任何编码,则该函数在读取文件时将使用自动字符集检测来确定编码。

示例: 'Encoding','system' 使用系统默认编码。

数据类型: char | string

注释样式,指定为字符串数组、字符向量或字符向量元胞数组。对于单行和多行注释,起始标识符必须为第一个非空白字符。对于单行注释,请指定一个标识符,以便将以该标识符开头的行视为注释。对于多行注释,从起始(第一个)标识符到结束(第二个)标识符的行被视为注释。最多只能指定两个由标识符组成的字符向量。

例如,要忽略百分号后面的行作为第一个非空白字符,请将 CommentStyle 指定为 "%"

示例: "CommentStyle",["/*"]

示例: "CommentStyle",["/*","*/"]

来自文本文件的持续时间数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'DurationType''duration''text'

导入的持续时间数据的类型
'duration'

MATLAB duration 数据类型

有关详细信息,请参阅 duration

'text'

如果将 'DurationType' 指定为 'text',则导入的持续时间数据的类型取决于 'TextType' 参数中指定的值:

  • 如果 'TextType' 设置为 'char',则导入函数会以字符向量元胞数组的形式返回持续时间数据。

  • 如果 'TextType' 设置为 'string',则导入函数会以字符串数组的形式返回持续时间数据。

数据类型: char | string

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

附加列规则行为
'addvars'

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

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

数据类型: char | string

要解释为缺失数据的文本,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

当导入函数发现缺失实例后,将根据 MissingRule 属性中的指定确定适当的操作。

示例: 'TreatAsMissing',{'NA','TBD'} 指示导入函数将 NATBD 的任何实例都视为缺失字段。

数据类型: char | string | cell

用于读取日期的区域设置,指定为逗号分隔的对组,其中包含 'DateLocale' 和一个 xx_YY 形式的字符向量或字符串标量,其中:

  • YY 是指示国家/地区的大写 ISO 3166-1 alpha-2 代码。

  • xx 是指示语言的小写 ISO 639-1 双字母代码。

下表列出了区域设置的某些常用值。

区域设置 语言国家/地区
'de_DE'德语德国
'en_GB'英语英国
'en_US'英语美国
'es_ES'西班牙语西班牙
'fr_FR'法语法国
'it_IT'意大利语意大利
'ja_JP'日语日本
'ko_KR'韩语韩国
'nl_NL'荷兰荷兰
'zh_CN'简体中文中国

使用 %D 格式设定符来将文本读取为 datetime 值时,请使用 DateLocale 指定导入函数应使用何种区域设置来解释月份和星期几的名称及缩写。

如果除 opts 导入选项外您还指定了 DateLocale 参量,则导入函数将使用为 DateLocale 参量指定的值,而覆盖导入选项中定义的区域设置。

示例: 'DateLocale','ja_JP'

表示数值变量中千分位的字符,指定为字符向量或字符串标量。千分位字符作为视觉分隔符,将数字按三位数一组进行分组。导入函数使用 ThousandsSeparator 属性中的字符来解释要导入的数字。

数据类型: char | string

表示数值变量中小数分隔符的字符,指定为字符向量或字符串标量。导入函数使用 DecimalSeparator 属性来区分数字的整数部分和小数部分。

转换为整数数据类型时,带小数部分的数字将被舍入为最接近的整数。

数据类型: char | string

从数值变量中删除非数值字符,指定为逻辑值 truefalse

数据类型: logical

十六进制数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'HexType' 和下表中列出的值之一。

输入文件以文本形式表示十六进制值,使用 0x0X 作为前缀,以字符 0-9a-fA-F 作为数字。(大写和小写字母表示相同的数字 - 例如,'0xf''0xF' 都表示 15。)

导入函数将十六进制值转换为由 'HexType' 的值指定的数据类型。

'HexType' 的值

输出表变量的数据类型

'auto'

自动检测到的数据类型

'text'

未更改的输入文本

'int8'

8 位有符号整数

'int16'

16 位有符号整数

'int32'

32 位有符号整数

'int64'

64 位有符号整数

'uint8'

8 位无符号整数

'uint16'

16 位无符号整数

'uint32'

32 位无符号整数

'uint64'

64 位无符号整数

示例: 'HexType','uint16' 将输出表中表示十六进制值的文本(如 '0xFF')转换为 16 位无符号整数(如 255)。

数据类型: char | string

二进制数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'BinaryType' 和下表中列出的值之一。

输入文件以文本形式表示二进制值,使用 0b0B 作为前缀,以字符 01 作为数字。

导入函数将二进制值转换为由 'BinaryType' 的值指定的数据类型。

'BinaryType' 的值

输出表变量的数据类型

'auto'

自动检测到的数据类型

'text'

未更改的输入文本

'int8'

8 位有符号整数

'int16'

16 位有符号整数

'int32'

32 位有符号整数

'int64'

64 位有符号整数

'uint8'

8 位无符号整数

'uint16'

16 位无符号整数

'uint32'

32 位无符号整数

'uint64'

64 位无符号整数

示例: 'BinaryType','uint16' 将输出表中表示二进制值的文本(如 '0b11111111')转换为 16 位无符号整数(如 255)。

数据类型: char | string

仅 XML 文件

全部折叠

导入属性,指定为逗号分隔的对组,包含 'ImportAttributes'1 (true) 或 0 (false)。如果指定 false,则读取函数不会将输入文件中的 XML 属性作为输出表中的变量导入。

示例: 'ImportAttributes',false

属性后缀,指定为逗号分隔的对组,包含 'AttributeSuffix' 和一个字符向量或字符串标量。此参量指定读取函数追加到与输入 XML 文件中的属性对应的所有表变量的后缀。如果未指定 'AttributeSuffix',则读取函数默认将后缀 'Attribute' 附加到与输入 XML 文件中的属性对应的所有变量名称。

示例: 'AttributeSuffix','_att'

表行 XML 节点名称,指定为逗号分隔的对组,包含 'RowNodeName' 和一个字符向量或字符串标量。此参量指定界定输出表行的 XML 节点名称。

示例: 'RowNodeName','XMLNodeName'

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

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

表变量 XML 节点名称,指定为以逗号分隔的对组,包含 'VariableNodeNames' 和一个字符向量元胞数组或字符串数组。此参量指定读取函数用于标识输出表中作为变量读取的 XML 节点的 XML 节点名称。

示例: 'VariableNodeNames',{'XMLNodeName1','XMLNodeName2'}

示例: 'VariableNodeNames',"XMLNodeName"

示例: 'VariableNodeNames',["XMLNodeName1","XMLNodeName2"]

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

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

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

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

表 XML 节点名称,指定为逗号分隔的对组,其中包含 'TableNodeName' 和一个字符向量或字符串标量。此参量指定读取函数应读取到表的输入结构体中的节点。

示例: 'TableNodeName','NodeName'

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

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

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

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

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

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

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

重复节点规则

行为

'addcol'

在表中的变量标题下为重复节点添加列。将 'RepeatedNodeRule' 的值指定为 'addcol' 不会在表中为重复节点创建单独变量。

'ignore'

跳过导入重复节点。

'error'显示错误消息并中止导入操作。

示例: 'RepeatedNodeRule','ignore'

注册的 XML 命名空间前缀集,指定为由 RegisteredNamespaces 和前缀数组组成的以逗号分隔的对组。读取函数在计算 XML 文件的 XPath 表达式时使用这些前缀。将命名空间前缀及其关联的 URL 指定为 N×2 字符串数组。RegisteredNamespaces 还可以用于计算由选择器名称-值参量(例如 readstructStructSelectorreadtablereadtimetableVariableSelectors)指定的 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"]

仅限 Microsoft Word 文档和 HTML 文件

全部折叠

要从包含多个表的 Microsoft Word 文档或 HTML 文件中读取的表的索引,指定为正整数。

当您指定 TableIndex 时,软件会自动将 TableSelector 设置为等效的 XPath 表达式。

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

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

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

包含变量名称的行,指定为非负整数。

  • 如果您没有指定 VariableNamesRow,则软件会根据 ReadVariableNames 参量读取变量名称。

  • 如果 VariableNamesRow0,则软件不会导入变量名称。

  • 否则,软件将从指定的行导入变量名称。

数据类型: 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

应用于表中空行的规则,指定为以下各项之一:

  • "skip" - 跳过空行。

  • "read" - 读取空行。

  • "error" - 在表检测期间忽略空行,在读取时报错。

应用于表中空列的规则,指定为以下各项之一:

  • "skip" - 跳过空列。

  • "read" - 读取空列。

  • "error" - 在表检测期间忽略空列,在读取时报错。

仅限 Microsoft Word 文档、HTML 和 XML 文件

全部折叠

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

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

输出参量

全部折叠

指定文件的导入选项,以 SpreadsheetImportOptionsDelimitedTextImportOptionsFixedWidthImportOptionsXMLImportOptions 对象形式返回。选项对象的类型取决于指定文件的类型。对于文本文件(.txt.dat.csv),detectImportOptions 函数返回 DelimitedTextImportOptionsFixedWidthImportOptions 对象。对于电子表格文件(.xls.xlsb.xlsm.xlsx.xltm.xltx.ods),detectImportOptions 函数返回 SpreadsheetImportOptions 对象。对于 XML 文件 (.xml),detectImportOptions 返回 XMLImportOptions 对象。

提示

  • 在创建导入选项对象后更新属性值:不推荐使用圆点表示法更新由 detectImportOptions 创建的导入选项对象的属性。当您使用圆点表示法设置属性时,MATLAB 不会重新检测文件的所有导入选项。因此,要更新和重新检测所有属性,必须使用名称-值参量指定新值。例如,按如下方式更新 ConsecutiveDelimitersRule 属性的值并重新检测导入选项。

    opts = detectImportOptions(__,'ConsecutiveDelimitersRule','join')

  • 使用 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 选择器名称-值参量(例如 VariableSelectorsTableSelector)支持的 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 

版本历史记录

在 R2016b 中推出