Main Content

readtable

基于文件创建表

说明

示例

T = readtable(filename) 通过从文本文件、电子表格(包括 Microsoft® Excel®)文件、XML 文件、HTML 文件或 Microsoft Word 文档中读取列向数据来创建表。readtable 检测数据元素,如分隔符和数据类型,以确定如何导入数据。

示例

T = readtable(filename,Name,Value) 使用一个或多个名称-值参量指定选项。例如,通过使用 ReadVariableNames 名称-值参量,可以将文件的第一行作为变量名称或数据读取。

示例

T = readtable(filename,opts) 使用导入选项对象 opts 指定的选项创建表。使用导入选项对象来配置 readtable 解读文件的方式。与名称-值参量相比,导入选项对象在文件导入配置上可以提供更多的控制、更好的性能,并可重复使用。

示例

T = readtable(filename,opts,Name,Value) 使用导入选项对象和名称-值参量创建表。如果除了导入选项对象之外还指定名称-值参量,则 readtable 对文本文件仅支持 ReadVariableNamesReadRowNamesDateLocaleEncoding 名称-值参量,对电子表格文件仅支持 ReadVariableNamesReadRowNamesSheetUseExcel 名称-值参量。

示例

全部折叠

将文本文件的内容导入表中。生成的表为文件中的每一列包含一个变量,并使用文件第一行中的条目作为变量名。

File contents of myCsvTable.dat

T = readtable("myCsvTable.dat")
T=5×6 table
      LastName      Gender    Age    Height    Weight    Smoker
    ____________    ______    ___    ______    ______    ______

    {'Smith'   }    {'M'}     38       71       176        1   
    {'Johnson' }    {'M'}     43       69       163        0   
    {'Williams'}    {'F'}     38       64       131        0   
    {'Jones'   }    {'F'}     40       67       133        0   
    {'Brown'   }    {'F'}     49       64       119        0   

从包含数据间隙的文本文件创建表。默认情况下,readtable 会用适当的缺失值来填充间隙。

T = readtable("headersAndMissing.txt")
T=5×6 table
     LastName        Gender      Age    Height    Weight    Smoker
    ___________    __________    ___    ______    ______    ______

    {'Wu'     }    {'M'     }     38      71       176        1   
    {'Johnson'}    {'M'     }     43      69       163        0   
    {'Sanchez'}    {'F'     }     38      64       131        0   
    {'Brown'  }    {'F'     }    NaN      67       133        0   
    {'Picard' }    {0x0 char}    NaN      64       119        0   

要忽略有数据间隙的行,请指定 MissingRule 名称-值参量。

T = readtable("headersAndMissing.txt",MissingRule="omitrow")
T=3×6 table
     LastName      Gender    Age    Height    Weight    Smoker
    ___________    ______    ___    ______    ______    ______

    {'Wu'     }    {'M'}     38       71       176        1   
    {'Johnson'}    {'M'}     43       69       163        0   
    {'Sanchez'}    {'F'}     38       64       131        0   

使用导入选项对象配置 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);

基于包含第一行的变量名称和第一列的行名称的电子表格创建表。显示表的前五行和前四个变量。

T = readtable("patients.xls",ReadRowNames=true);
T(1:5,1:4)
ans=5×4 table
                  Gender      Age              Location               Height
                __________    ___    _____________________________    ______

    Smith       {'Male'  }    38     {'County General Hospital'  }      71  
    Johnson     {'Male'  }    43     {'VA Hospital'              }      69  
    Williams    {'Female'}    38     {'St. Mary's Medical Center'}      64  
    Jones       {'Female'}    40     {'VA Hospital'              }      67  
    Brown       {'Female'}    49     {'County General Hospital'  }      64  

使用电子表格的指定区域中的数据创建表。使用 C2E6 两个对角之间的 5×3 矩形区域内的数据。不要将该区域的第一行用作变量名称。结果表改用默认变量名称。

T = readtable("patients.xls",Range="C2:E6",ReadVariableNames=false)
T=5×3 table
    Var1                Var2                 Var3
    ____    _____________________________    ____

     38     {'County General Hospital'  }     71 
     43     {'VA Hospital'              }     69 
     38     {'St. Mary's Medical Center'}     64 
     40     {'VA Hospital'              }     67 
     49     {'County General Hospital'  }     64 

使用导入选项对象配置 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    

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

将 Microsoft Word 文档中的表导入 MATLAB 中的表。在本例中,文档包含两个表,第二个表包含合并的单元格。通过设置 TableIndex 名称-值参量读取第二个表。通过设置 MergedCellColumnRule 名称-值参量,跳过包含合并列的单元格的行。

filename = "MaintenanceReport.docx";
T = readtable(filename,TableIndex=2,MergedCellColumnRule="omitrow")
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"

您也可以使用 TableSelector 名称-值参量选择具有 XPath 选择器的表。要选择 Microsoft Word 文档中包含文本“Descriptio”的表,请使用 XPath 选择器 "//w:tbl[contains(.,'Description')]"

T = readtable(filename, ...
    TableSelector="//w:tbl[contains(.,'Description')]", ...
    MergedCellColumnRule="omitrow")
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"

使用 XPath 选择器 "//TABLE[contains(.,'readtable')]" 从 URL https://www.mathworks.com/help/matlab/text-files.html 中导入第一个包含文本 "readtable" 的表。该表没有标题行,因此将 ReadVariableNames 名称-值参量设置为 false

url = "https://www.mathworks.com/help/matlab/text-files.html";
T = readtable(url,TableSelector="//TABLE[contains(.,'readtable')]", ...
    ReadVariableNames=false)
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"   

输入参数

全部折叠

要读取的文件的名称,指定为字符串标量或字符向量。readtable 支持从文本、电子表格、XML 和 HTML 文件以及 Microsoft Word 文档中读取数据。

如果 filename 不包含扩展名,请使用 FileType 名称-值参量来指示文件格式。默认情况下,readtable 会根据在输入文件的每列中检测到的数据值来创建具有适当数据类型的变量。

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

位置

形式

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

指定 filename 中文件的名称。

例如:"myFile.txt"

文件夹中的文件

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

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

例如:"dataDir\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"

示例: "wasbs://path_to_file/my_file.csv"

示例: "hdfs:///path_to_file/my_file.csv"

文本文件

  • 扩展名为 .txt.dat.csv 的文件读取为带分隔符的文本文件。

  • 默认情况下,readtable 为文件中的每列创建一个表变量,并从文件的第一行读取变量名称。对于数值变量,空字段转换为 NaN,对于文本变量,则转换为空字符向量。读取文件时会忽略空白。

  • 文本文件中的所有行必须有相同数量的分隔符。

有关更多选项,请参阅文本文件的名称-值参量。

有关常用的文本文件工作流,请参阅将数据从文本文件导入表

电子表格文件

  • 扩展名为 .xls.xlsb.xlsm.xlsx.xltm.xltx.ods 的文件读取为电子表格文件。

  • 默认情况下,readtable 为文件中的每列创建一个表变量,并从文件的第一行读取变量名称。

  • 在安装了 Microsoft Excel 软件的 Windows® 系统上,readtable 能够读取您的 Excel 版本可识别的任何 Excel 电子表格文件格式。如果您的系统没有 Windows 版 Microsoft Excel 或者您正在使用 MATLAB Online™,则 readtableUseExcel 属性设置为 false 的情况下运行,并且只读取 .xls, .xlsm, .xlsx, .xltm, and .xltx 文件。

有关更多选项,请参阅电子表格文件的名称-值参量。

有关常用的电子表格文件工作流,请参阅将电子表格数据读入到表中

XML 文件

  • 扩展名为 .xml 的文件读取为可扩展标记语言 (XML) 文件。

  • 默认情况下,readtable 为每个检测为表变量的元素或属性节点创建一个表变量。变量名称对应于元素和属性名称。

  • XLSX 格式的大文件有时会加载缓慢。为了获得更好的导入和导出性能,Microsoft 推荐您使用 XLSB 格式。

有关更多选项,请参阅 XML 文件的名称-值参量。

Microsoft Word 文档文件

  • 扩展名为 .docx 的文件读取为 Microsoft Word 文档文件。

  • 默认情况下,readtable 从文档中的第一个表导入数据,为该文件中的每列创建一个表变量并从该表的第一行中读取变量名称。

有关更多选项,请参阅Microsoft Word 文档文件的名称-值参量。

HTML 文件

  • 扩展名为 .html.xhtml.htm 的文件读取为超文本标记语言 (HTML) 文件。

  • 默认情况下,readtable 从第一个 <TABLE> 元素导入数据,为该文件中的每列创建一个表变量并从该表的第一行中读取变量名称。

有关更多选项,请参阅 HTML 文件的名称-值参量。

文件导入选项,指定为表中的导入选项对象之一,由 detectImportOptions 函数或关联的导入选项函数创建。导入选项对象包含配置数据导入过程的属性。readtable 仅使用每个导入选项对象的相关属性。

文件类型导入选项对象
文本文件DelimitedTextImportOptions 对象
等宽文本文件FixedWidthImportOptions 对象
电子表格文件SpreadsheetImportOptions 对象
XML 文件XMLImportOptions 对象
Microsoft Word 文档WordDocumentImportOptions 对象
HTML 文件HTMLImportOptions 对象

有关如何控制导入的详细信息,请参阅Control How MATLAB Imports Your Data

名称-值参数

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

示例: readtable(filename,ReadVariableNames=false) 指示文件的第一行与变量名称不对应。

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

示例: readtable(filename,"ReadVariableNames",false) 指示文件的第一行与变量名称不对应。

文本文件

全部折叠

文件的类型,指定为以下值之一。

文件类型
"spreadsheet"电子表格文件
"text"文本文件
"delimitedtext"带分隔符的文本文件
"fixedwidth"等宽文本文件
"xml"XML 文件
"worddocument"Microsoft Word 文档
"html"HTML 文件

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

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

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

  • .xml(XML 文件)

  • .docxMicrosoft Word 文档文件)

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

示例: "FileType","text"

选项将第一列作为行名称读取,指定为数值或逻辑值 1 (true) 或 0 (false)。

  • 当要读取的区域第一列包含表的行名称时将 ReadRowNames 设置为 true

  • 当要读取的区域第一列包含的是数据而不是表的行名称时将 ReadRowNames 设置为 false

如果 ReadVariableNamesReadRowNames 名称-值参量都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除导入选项对象外您还指定了 ReadRowNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadRowNamestrue,则通过使用各自导入选项对象的 RowNamesColumnDelimitedTextImportOptionsFixedWidthImportOptions)、RowNamesRange (SpreadsheetImportOptions) 或 RowNamesSelector (XMLImportOptions) 属性从指定的文件中读取行名称。

  • 如果 ReadRowNamesfalse,则不导入行名称。

如果在不指定 ReadRowNames 的情况下使用导入选项语法,则 readtable 将使用与导入选项对象及其 ReadRowNames 名称-值参量相关联的值。

示例: "ReadRowNames",true

字段分隔符,指定为 Delimiter 和一个字符向量、字符向量元胞数组或字符串。使用任何有效字符(如逗号 "," 或句点 ".")指定 Delimiter

下表列出了一些常用的字段分隔符。

设定符

字段分隔符

","

"comma"

逗号

" "

"space"

空格

"\t"

"tab"

制表符

";"

"semi"

分号

"|"

"bar"

垂直条

未指定

如果未指定,readtable 将自动检测分隔符。

要将连续分隔符视为单个分隔符,请将 Delimiter 指定为字符向量元胞数组。您还必须指定 MultipleDelimsAsOne 选项。

示例: "Delimiter",",""Delimiter","comma"

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

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

示例: "LeadingDelimitersRule","keep"

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

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

示例: "TrailingDelimitersRule","keep"

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

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

示例: "ConsecutiveDelimitersRule","split"

多分隔符处理,指定为 MultipleDelimsAsOnetruefalse。如果是 true,则 readtable 将连续分隔符当作一个分隔符处理。由空白分隔的重复分隔符也被当作一个分隔符处理。您还必须指定 Delimiter 选项。

示例: "MultipleDelimsAsOne",1

文件开头要跳过的标题行数,指定为 NumHeaderLines0 或一个正整数。如果未指定,readtable 将自动检测要跳过的行数。

示例: "NumHeaderLines",2

数据类型: single | double

要作为空值处理的占位符文本,指定为 "TreatAsMissing" 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。与这些字符对应的表元素设置为 NaN

"TreatAsMissing" 仅应用于表中的数值列,而 readtable 不接受数值文字,例如 "-99"

示例: "TreatAsMissing","N/A""TreatAsMissing","N/A" 将数值列内的 N/A 设置为 NaN

示例: "TreatAsMissing",{'.','NA','N/A'}"TreatAsMissing",[".","NA","N/A"] 将数值列内的 .NAN/A 设置为 NaN

管理缺失数据的过程,指定为下表中的值之一。如果行中不存在预期字段,则认为数据缺失。由于缺失字段会导致行的后续元素移动字段,因此缺失的字段在行的末尾解释。

缺失规则行为
"fill"

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

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

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

示例: "MissingRule","omitrow"

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

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

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

示例: "TextType","char"

导入的日期和时间数据的类型,指定为 DatetimeType 和以下值之一:"datetime""text""exceldatenum"。值 "exceldatenum" 仅适用于电子表格文件,对文本文件无效。

导入日期时间数据的类型
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

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

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

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

"exceldatenum"

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

示例: "DatetimeType","datetime"

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

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

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

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

示例: "VariableNamingRule","preserve"

处理导入错误的过程,指定为下表中的值之一。当 readtable 无法将文本元素转换为预期的数据类型时,会发生导入错误。

导入错误规则行为
"fill"

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

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

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

示例: "ImportErrorRule","omitvar"

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

读取第一行以作为变量名称的指示符,指定为 ReadVariableNamestruefalse10。如果未指定,readtable 将自动检测是否存在变量名称。

指示符

描述

true

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

false

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

未指定 如果未指定,readtable 将自动检测 truefalse,并进行相应的处理。

注意:如果 "ReadVariableNames""ReadRowNames" 逻辑指示符都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除 opts 导入选项外您还指定了 ReadVariableNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadVariableNamestrue,则通过使用导入选项对象的 VariableNamesRangeVariableNamesLine 属性从指定的文件中读取变量名称。

  • 如果 ReadVariableNamesfalse,则从导入选项对象的 VariableNames 属性中读取变量名称。

示例: "ReadVariableNames",true

预期的变量数,指定为 ExpectedNumVariables 和正整数。如果未指定,readtable 会自动检测变量的数目。

示例: "ExpectedNumVariables",5

数据类型: single | double

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

示例: "VariableWidths",[10,7,4,26,7]

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

下表显示如何表示无法使用普通文本输入的特殊字符。

特殊字符

表示形式

百分比字符

%%

反斜杠

\\

警报

\a

退格符

\b

换页符

\f

换行符

\n

回车符

\r

水平制表符

\t

垂直制表符

\v

其 Unicode® 数值可以通过十六进制数 N 表示的字符

\xN

其 Unicode 数值可以通过八进制数 N 表示的字符

\N

示例: "Whitespace"," _"

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

处理数据中的空行的过程,指定为下表中的值之一。readtable 将空白解释为空。如果一行不包含字段,则认为该行为空。一行由两个行尾字符定义。

空行规则行为
"skip"跳过空行。
"read"导入空行。readtable 使用 VariableWidthsVariableOptionsMissingRule 中指定的值及其他相关属性(如 Whitespace)来解析空行。
"error"显示错误消息并取消导入操作。

示例: "EmptyLineRule","skip"

变量名称的位置,指定为正整数标量。VariableNamesLine 属性指定变量名称所在的行号。

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

示例: "VariableNamesLine",6

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

处理数据中不完整字段的过程,指定为下表中的值之一。如果某个字段在预期宽度结束之前终止,则该字段被视为部分填充。这只适用于具有固定宽度的字段。

不完整字段规则行为
"keep"

保留不完整字段数据并将文本转换为正确的数据类型。

在某些情况下,当 readtable 无法解释部分数据时,可能会发生转换错误。

"fill"

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

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

"omitrow"忽略包含不完整数据的行。
"omitvar"忽略包含不完整数据的变量。
"wrap"开始读取下一行字符。
"error"显示错误消息并取消导入操作。

示例: "PartialFieldRule","keep"

变量单位的位置,指定为正整数标量。VariableUnitsLine 属性指定变量单位所在的行号。

如果 VariableUnitsLine 指定为 0,则不导入变量单位。否则,将从指定的行中导入变量单位。

示例: "VariableUnitsLine",8

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

变量描述的位置,指定为正整数标量。VariableDescriptionsLine 属性指定变量描述所在的行号。

如果 VariableDescriptionsLine 指定为 0,则不导入变量描述。否则,将从指定的行中导入变量描述。

示例: "VariableDescriptionsLine",7

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

处理数据中的附加列的过程,指定为下表中的值之一。如果一行中的列比预期列多,则列认为是多余的。

附加列规则行为
"addvars"

要导入附加列,需要创建新变量。如果有 N 个附加列,将以 "ExtraVar1","ExtraVar2",...,"ExtraVarN" 的形式导入新变量。

附加列作为 char 数据类型的文本导入。

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

示例: "ExtraColumnsRule","addvars"

文件的列格式,指定为 Format 和一个字符向量或字符串标量(由一个或多个转换设定符组成)或 "auto"。转换设定符与 textscan 函数接受的设定符相同。

指定该格式可以显著加快一些大文件的处理速度。如果不为 Format 指定一个值,则 readtable 将使用 %q 解释非数值列。%q 设定符会读取文本并在适当情况下忽略双引号 (")。

  • 如果您没有指定 "Format" 名称-值对组,则 readtable 函数的行为就像您使用了 detectImportOptions 函数的结果来导入数据一样。有关此行为导致的结果的详细信息,请参阅兼容性注意事项

  • 如果您指定 "Format","auto",则创建的变量是 double 数组、字符向量元胞数组或 datetime 数组,具体取决于数据。如果整列都是数值,则将变量作为 double 数组导入。如果一列中有任一元素不是数值,则将这些变量作为字符向量元胞数组导入,或作为 datetime 数组导入(如果值表示日期时间)。

示例: "Format","auto"

被分隔的文本文件中空数值字段的返回值,指定为 EmptyValue 和一个数值标量。

示例: "EmptyValue",0

确定数据串联的逻辑指示符,指定为 CollectOutputtruefalse。如果为 true,则 readtable 会将同一 MATLAB 基础类的连续输出元胞串联为单个数组。

示例: "CollectOutput",true

用于指定要忽略的文本的符号,指定为 CommentStyle 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。

例如,指定一个字符(如 "%")以忽略同一行上此符号后面的文本。指定一个包含两个字符向量的元胞数组(如 {'/*','*/'}),以忽略这些序列之间的任何文本。

MATLAB 仅检查位于每个字段开头而不是字段中的注释。

示例: "CommentStyle",{'/*','*/'}

指数字符,指定为 ExponentCharacter 和字符向量或字符串标量。默认的指数字符为 eEdD

示例: "ExponentCharacter","eE"

行尾字符,指定为 LineEnding 和字符向量或字符串标量。该字符向量必须为 "\r\n",或须指定单个字符。常用的行尾字符是换行符 ("\n") 或回车符 ("\r")。如果您指定 "\r\n",则 readtable 会将 \r\n 以及两者的组合 (\r\n) 视为行尾字符。

默认的行尾序列是 \n\r\r\n,具体取决于您的文件的内容。

如果文件最后一行的结尾有缺失值和行尾序列,则 readtable 会对这些字段返回空值。这样可确保输出元胞数组 C 中的各个元胞的大小相同。

示例: "LineEnding",":"

用于读取日期的区域设置,指定为 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 指定 readtable 应使用何种区域设置来解释月份和星期几的名称及缩写。

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

示例: "DateLocale","ja_JP"

表示数值变量中小数分隔符的字符,指定为字符向量或字符串标量。readtable 使用 DecimalSeparator 名称-值参量中指定的字符来区分数字的整数部分和小数部分。

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

示例: 如果名称-值对组指定为 "DecimalSeparator",",",则 readtable 将文本 "3,14159" 导入为数字 3.14159

表示数值变量中千分位的字符,指定为字符向量或字符串标量。千分位字符作为视觉分隔符,将数字按三位数一组进行分组。readtable 使用 ThousandsSeparator 名称-值参量中指定的字符来解释正在导入的数字。

示例: 如果名称-值对组指定为 "ThousandsSeparator",",",则 readtable 将文本 "1,234,000" 导入为 1234000

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

示例: 如果名称-值对组指定为 "TrimNonNumeric",true,则 readtable"$500/-" 读作 500

数据类型: logical

与文件关联的字符编码方案,指定为 Encoding"system" 或标准字符编码方案名称。如果您没有指定任何编码,则 readtable 函数在读取文件时将使用自动字符集检测来确定编码。

如果除导入选项外您还指定了 "Encoding" 参量,readtable 函数将使用为 "Encoding" 指定的值,而覆盖导入选项中定义的编码方案。

示例: "Encoding","UTF-8" 使用 UTF-8 作为编码。

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

来自文本文件的持续时间数据的输出数据类型,DurationType"duration""text"

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

MATLAB duration 数据类型

有关详细信息,请参阅 duration

"text"

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

  • 如果 "TextType""char",则 readtable 会以字符向量元胞数组的形式返回持续时间数据。

  • 如果 "TextType""string",则 readtable 会以字符串数组的形式返回持续时间数据。

示例: "DurationType","text"

十六进制数据的输出数据类型,指定为 HexType 和下表中列出的值之一。

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

readtable 将十六进制值转换为由 "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)。

二类数据的输出数据类型,指定 BinaryType 和下表中列出的值之一。

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

readtable 将二进制值转换为由 "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)。

电子表格文件

全部折叠

文件的类型,指定为以下值之一。

文件类型
"spreadsheet"电子表格文件
"text"文本文件
"delimitedtext"带分隔符的文本文件
"fixedwidth"等宽文本文件
"xml"XML 文件
"worddocument"Microsoft Word 文档
"html"HTML 文件

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

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

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

  • .xml(XML 文件)

  • .docxMicrosoft Word 文档文件)

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

示例: "FileType","text"

读取第一列作为行名称的选项,指定为数值或逻辑值 1 (true) 或 0 (false)。

  • 当要读取的区域第一列包含表的行名称时将 ReadRowNames 设置为 true

  • 当要读取的区域第一列包含的是数据而不是表的行名称时将 ReadRowNames 设置为 false

如果 ReadVariableNamesReadRowNames 名称-值参量都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除导入选项对象外您还指定了 ReadRowNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadRowNamestrue,则通过使用各自导入选项对象的 RowNamesColumnDelimitedTextImportOptionsFixedWidthImportOptions)、RowNamesRange (SpreadsheetImportOptions) 或 RowNamesSelector (XMLImportOptions) 属性从指定的文件中读取行名称。

  • 如果 ReadRowNamesfalse,则不导入行名称。

如果在不指定 ReadRowNames 的情况下使用导入选项语法,则 readtable 将使用与导入选项对象及其 ReadRowNames 名称-值参量相关联的值。

示例: "ReadRowNames",true

要作为空值处理的占位符文本,指定为 TreatAsMissing 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。与这些字符对应的表元素设置为 NaN

TreatAsMissing 仅应用于表中的数值列,而 readtable 不接受数值文字,例如 "-99"

示例: "TreatAsMissing","N/A""TreatAsMissing","N/A" 将数值列内的 N/A 设置为 NaN

示例: "TreatAsMissing",{'.','NA','N/A'}"TreatAsMissing",[".","NA","N/A"] 将数值列内的 .NAN/A 设置为 NaN

管理缺失数据的过程,指定为下表中的值之一。如果行中的预期字段没有数据,并且字段类型为空白或空,则认为数据缺失。

缺失规则行为
"fill"

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

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

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

示例: "MissingRule","omitrow"

要读取的工作表部分,指示为一个矩形区域,以下列形式之一指定为字符向量或字符串标量。

指定 Range 的方式 描述

"Cell"[row col]

起始单元格

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

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

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

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

例如:"A5"[5 1]

"Corner1:Corner2"

矩形范围

使用语法 "Corner1:Corner2" 指定该范围,其中 Corner1Corner2 是定义区域的两个对角。例如,"D2:H4" 表示工作表上两个角落 D2H4 之间的 3×5 矩形区域。"Range" 名称-值对组参量不区分大小写,并使用 Excel A1 引用样式(请参阅 Excel 帮助)。

例如:"Range","D2:H4"

""

未指定或为空

如果未指定,readtable 将自动检测使用范围。

例如:"Range",""

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

"Row1:Row2"

行范围

您可以通过使用 Excel 行标志符指定开始行和结束行来标识范围。然后,readtable 自动在指定的行中检测使用的列范围。例如,readtable 将范围设定 "1:7" 解释为一个指令,用于读取第 1 行到第 7 行(包括这两行)使用范围内的所有列。

例如:"Range","1:7"

"Column1:Column2"

列范围

您可以通过使用 Excel 列标志符指定开始列和结束列来标识范围。然后,readtable 自动在指定的列中检测使用的行范围。例如,readtable 将范围设定 "A:F" 解释为一个指令,用于读取 A 到 F 列(包括这两列)使用范围内的所有行。

例如:"Range","A:F"

"NamedRange"

Excel 中的命名范围

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

例如:"Range","myTable"

示例: "Range", "A1:F10"

示例: "Range", "A1:F10"

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

行为

"Cell"n

起始单元格或起始行

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

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

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

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

例如:"A5"5

"Corner1:Corner2"

矩形范围

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

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

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

例如:"A5:K50"

"Row1:Row2""Column1:Column2"

行范围或列范围

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

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

例如:"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]

""

未指定或为空

不获取任何数据。

例如:""

示例: "DataRange", "B2:H15"

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

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

行为

"Cell"

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

readtable 为数据中的每个变量标识一个名称。

例如:"A5"

"Corner1:Corner2"

矩形范围

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

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

例如:"A5:A50"

"Row1:Row2"

行范围

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

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

例如:"5:50"

n

数字索引

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

例如:5

""

未指定或为空

指示没有行名称。

例如:""

示例: "RowNamesRange", "A1:H1"

数据类型: char | single | double

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

行为

"Cell"

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

readtable 为数据中的每个变量读取一个名称。

例如:"A5"

"Corner1:Corner2"

矩形范围

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

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

例如:"A5:K5"

"Row1:Row2"

行范围

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

必须为一行。

例如:"5:5"

n

数字索引

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

例如:5

""

未指定或为空

指示没有变量名称。

例如:""

示例: "VariableNamesRange", "A1:A15"

数据类型: char | single | double

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

行为

"Cell"

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

readtable 为数据中的每个变量读取一个单位。

例如:"A5"

"Corner1:Corner2"

矩形范围

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

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

例如:"A5:K5"

"Row1:Row2"

行范围

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

必须为一行。

例如:"5:5"

n

数字索引

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

例如:5

""

未指定或为空

指示没有变量单位。

例如:""

示例: "VariableUnitsRange", "A1:A5"

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

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

行为

"Cell"

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

readtable 为数据中的每个变量读取一个描述。

例如:"A5"

"Corner1:Corner2"

矩形范围

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

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

例如:"A5:K5"

"Row1:Row2"

行范围

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

必须为一行。

例如:"5:5"

n

数字索引

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

例如:5

""

未指定或为空

指示没有变量描述。

例如:""

示例: "VariableDescriptionsRange", "B1:B15"

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

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

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

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

示例: "TextType","char"

导入的日期和时间数据的类型,指定为 DatetimeType 和以下值之一:"datetime""text""exceldatenum"。值 "exceldatenum" 仅适用于电子表格文件,对文本文件无效。

导入日期时间数据的类型
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

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

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

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

"exceldatenum"

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

示例: "DatetimeType","datetime"

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

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

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

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

示例: "VariableNamingRule","preserve"

处理导入错误的过程,指定为下表中的值之一。当 readtable 无法将数据转换为预期的数据类型或单元格具有 Microsoft 错误数据类型时,会发生导入错误。

导入错误规则行为
"fill"

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

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

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

示例: "ImportErrorRule","omitvar"

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

读取第一行以作为变量名称的指示符,指定为 ReadVariableNamestruefalse10。如果未指定,readtable 将自动检测是否存在变量名称。

指示符

描述

true

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

false

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

未指定 如果未指定,readtable 将自动检测 truefalse,并进行相应的处理。

注意:如果 "ReadVariableNames""ReadRowNames" 逻辑指示符都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除 opts 导入选项外您还指定了 ReadVariableNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadVariableNamestrue,则通过使用导入选项对象的 VariableNamesRangeVariableNamesLine 属性从指定的文件中读取变量名称。

  • 如果 ReadVariableNamesfalse,则从导入选项对象的 VariableNames 属性中读取变量名称。

示例: "ReadVariableNames",true

预期的变量数,指定为 ExpectedNumVariables 和正整数。如果未指定,readtable 会自动检测变量的数目。

示例: "ExpectedNumVariables",5

数据类型: single | double

要读取的工作表,指定为 Sheet 和一个正整数(指示工作表索引)或字符向量或字符串标量(包含工作表名称)。工作表名称不能包含冒号 (:)。要确定电子表格文件中工作表的名称,请使用 sheets = sheetnames(filename)。有关详细信息,请参阅 sheetnames

如果除 opts 导入选项外您还指定了 Sheet 参量,readtable 函数将使用为 Sheet 参量指定的值,而覆盖导入选项中定义的工作表名称。

示例: "Sheet", 2

示例: 'Sheet', 'MySheetName'

示例: "Sheet", "MySheetName"

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

用于在读取电子表格数据时启动 Windows 版 Microsoft Excel 实例的标志,指定 UseExceltruefalse

您可以将 "UseExcel" 参数设置为下列值之一:

  • true - readtable 读取文件时启动 Microsoft Excel 的实例。

  • false - readtable 读取文件时不启动 Microsoft Excel 的实例。在此模式下操作时,readtable 功能支持的文件格式和交互式功能(例如公式和宏)有所不同。

UseExcel

true

false

支持的文件格式

.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods

.xls, .xlsx, .xlsm, .xltx, .xltm

支持交互功能,例如公式和宏

从 Windows 平台上的电子表格文件中读取时,如果您想启动 Microsoft Excel 实例,则将 "UseExcel" 参数设置为 true

示例: "UseExcel",true

XML 文件

全部折叠

文件的类型,指定为以下值之一。

文件类型
"spreadsheet"电子表格文件
"text"文本文件
"delimitedtext"带分隔符的文本文件
"fixedwidth"等宽文本文件
"xml"XML 文件
"worddocument"Microsoft Word 文档
"html"HTML 文件

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

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

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

  • .xml(XML 文件)

  • .docxMicrosoft Word 文档文件)

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

示例: "FileType","text"

读取第一列作为行名称的选项,指定为数值或逻辑值 1 (true) 或 0 (false)。

  • 当要读取的区域第一列包含表的行名称时将 ReadRowNames 设置为 true

  • 当要读取的区域第一列包含的是数据而不是表的行名称时将 ReadRowNames 设置为 false

如果 ReadVariableNamesReadRowNames 名称-值参量都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除导入选项对象外您还指定了 ReadRowNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadRowNamestrue,则通过使用各自导入选项对象的 RowNamesColumnDelimitedTextImportOptionsFixedWidthImportOptions)、RowNamesRange (SpreadsheetImportOptions) 或 RowNamesSelector (XMLImportOptions) 属性从指定的文件中读取行名称。

  • 如果 ReadRowNamesfalse,则不导入行名称。

如果在不指定 ReadRowNames 的情况下使用导入选项语法,则 readtable 将使用与导入选项对象及其 ReadRowNames 名称-值参量相关联的值。

示例: "ReadRowNames",true

要作为空值处理的占位符文本,指定为 TreatAsMissing 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。与这些字符对应的表元素设置为 NaN

"TreatAsMissing" 仅应用于表中的数值列,而 readtable 不接受数值文字,例如 "-99"

示例: 'TreatAsMissing','N/A'"TreatAsMissing","N/A" 将数值列内的 N/A 设置为 NaN

示例: 'TreatAsMissing',{'.','NA','N/A'}"TreatAsMissing",[".","NA","N/A"] 将数值列内的 .NAN/A 设置为 NaN

管理缺失数据的过程,指定为下表中的值之一。如果预期的节点不存在,则认为数据缺失。

缺失规则行为
"fill"

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

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

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

示例: "MissingRule","omitrow"

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

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

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

示例: "TextType","char"

导入的日期和时间数据的类型,指定为 DatetimeType 和以下值之一:"datetime""text""exceldatenum"。值 "exceldatenum" 仅适用于电子表格文件,对文本文件无效。

导入日期时间数据的类型
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

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

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

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

"exceldatenum"

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

示例: "DatetimeType","datetime"

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

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

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

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

示例: "VariableNamingRule","preserve"

处理导入错误的过程,指定为下表中的值之一。当 readtable 无法将文本转换为预期的数据类型时,会发生导入错误。

导入错误规则行为
"fill"

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

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

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

示例: "ImportErrorRule","omitvar"

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

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

示例: "AttributeSuffix","_att"

导入属性,指定为 ImportAttributes1 (true) 或 0 (false)。如果指定 false,则读取函数不会将输入文件中的 XML 属性作为输出表中的变量导入。

示例: "ImportAttributes",false

表行 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 表达式。

使用 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>

选取操作语法示例
选择其名称与您要选择的节点匹配的每个节点,而无论它在文档中的位置如何。在名称前加两个正斜杠 (//) 前缀。

要选择每个名为“var”的节点,请使用:

data = readtable("myFile.xml", "VariableSelectors", "//var")
读取属于元素节点的属性的值。在属性前加 at 符号 (@) 前缀。

要选择表节点的类别属性值,请使用:

data = readtable("myFile.xml", "VariableSelectors", "//table/@category")
在一组节点中选择一个特定节点。在方括号 ([]) 中提供要选择的节点的索引。

要选择每个表节点的第一个 var 节点,请使用:

data = readtable("myFile.xml", "VariableSelectors", "//var[1]")
指定运算的优先级。在要首先计算的表达式前后添加圆括号。

要选择每个 var 节点的第一个值,请使用:

data = readtable("myFile.xml", "VariableSelectors", "//table/var[1]")

要选择第一个 var 节点的第一个值,请使用:

data = readtable("myFile.xml", "VariableSelectors", "(//table/var)[1]")

表 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"]

表数据 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择输出表数据。您必须将 TableSelector 指定为有效的 XPath 版本 1.0 表达式。使用 XPath 选择器指定要导入 XML 输入文档的哪些元素。

选取操作语法
选择其名称与您要选择的节点匹配的每个节点,而无论它在文档中的位置如何。在名称前加两个正斜杠 (//) 前缀。
选择属于元素节点的属性的值。在属性前加 at 符号 (@) 前缀。
在一组节点中选择一个特定节点。在方括号 ([]) 中提供要选择的节点的索引。
指定运算的优先级。在要首先计算的表达式前后添加圆括号。

示例: "myFile.xml", "TableSelector", "//table[1]"

Microsoft Word 文档文件

全部折叠

文件的类型,指定为以下值之一。

文件类型
"spreadsheet"电子表格文件
"text"文本文件
"delimitedtext"带分隔符的文本文件
"fixedwidth"等宽文本文件
"xml"XML 文件
"worddocument"Microsoft Word 文档
"html"HTML 文件

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

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

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

  • .xml(XML 文件)

  • .docxMicrosoft Word 文档文件)

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

示例: "FileType","text"

将第一列作为行名称读取的选项,指定为数值或逻辑值 1 (true) 或 0 (false)。

  • 当要读取的区域第一列包含表的行名称时将 ReadRowNames 设置为 true

  • 当要读取的区域第一列包含的是数据而不是表的行名称时将 ReadRowNames 设置为 false

如果 ReadVariableNamesReadRowNames 名称-值参量都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除导入选项对象外您还指定了 ReadRowNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadRowNamestrue,则通过使用各自导入选项对象的 RowNamesColumnDelimitedTextImportOptionsFixedWidthImportOptions)、RowNamesRange (SpreadsheetImportOptions) 或 RowNamesSelector (XMLImportOptions) 属性从指定的文件中读取行名称。

  • 如果 ReadRowNamesfalse,则不导入行名称。

如果在不指定 ReadRowNames 的情况下使用导入选项语法,则 readtable 将使用与导入选项对象及其 ReadRowNames 名称-值参量相关联的值。

示例: "ReadRowNames",true

要作为空值处理的占位符文本,指定为 TreatAsMissing 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。与这些字符对应的表元素设置为 NaN

"TreatAsMissing" 仅应用于表中的数值列,而 readtable 不接受数值文字,例如 "-99"

示例: 'TreatAsMissing','N/A'"TreatAsMissing","N/A" 将数值列内的 N/A 设置为 NaN

示例: 'TreatAsMissing',{'.','NA','N/A'}"TreatAsMissing",[".","NA","N/A"] 将数值列内的 .NAN/A 设置为 NaN

管理缺失数据的过程,指定为下表中的值之一。如果行中不存在预期字段,则认为数据缺失。

缺失规则行为
"fill"

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

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

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

示例: "MissingRule","omitrow"

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

  • "skip" - 跳过空行。

  • "read" - 读取空行。

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

示例: "EmptyRowRule","read"

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

  • "skip" - 跳过空列。

  • "read" - 读取空列。

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

示例: "EmptyColumnRule","error"

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

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

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

示例: "TextType","char"

导入的日期和时间数据的类型,指定为 DatetimeType 和以下值之一:"datetime""text""exceldatenum"。值 "exceldatenum" 仅适用于电子表格文件,对文本文件无效。

导入日期时间数据的类型
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

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

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

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

"exceldatenum"

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

示例: "DatetimeType","datetime"

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

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

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

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

示例: "VariableNamingRule","preserve"

处理导入错误的过程,指定为下表中的值之一。当 readtable 无法将文本转换为预期的数据类型时,会发生导入错误。

导入错误规则行为
"fill"

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

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

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

示例: "ImportErrorRule","omitvar"

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

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

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

示例: "TableIndex",2

数据类型: 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"显示错误消息并中止导入操作。

示例: "MergedCellColumnRule","placeright"

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

导入错误规则行为
"placetop"

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

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

"placebottom"

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

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

"duplicate"

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

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

示例: "MergedCellRowRule","duplicate"

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

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

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

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

示例: "VariableNamesRow",2

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

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

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

示例: "VariableUnitsRow",3

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

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

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

示例: "VariableDescriptionsRow",4

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

表数据 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择输出表数据。您必须将 TableSelector 指定为有效的 XPath 版本 1.0 表达式。使用 XPath 选择器指定要导入 XML 输入文档的哪些元素。

选取操作语法
选择其名称与您要选择的节点匹配的每个节点,而无论它在文档中的位置如何。在名称前加两个正斜杠 (//) 前缀。
选择属于元素节点的属性的值。在属性前加 at 符号 (@) 前缀。
在一组节点中选择一个特定节点。在方括号 ([]) 中提供要选择的节点的索引。
指定运算的优先级。在要首先计算的表达式前后添加圆括号。

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

示例: "myFile.xml", "TableSelector", "//table[1]"

HTML 文件

全部折叠

文件的类型,指定为以下值之一。

文件类型
"spreadsheet"电子表格文件
"text"文本文件
"delimitedtext"带分隔符的文本文件
"fixedwidth"等宽文本文件
"xml"XML 文件
"worddocument"Microsoft Word 文档
"html"HTML 文件

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

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

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

  • .xml(XML 文件)

  • .docxMicrosoft Word 文档文件)

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

示例: "FileType","text"

读取第一列作为行名称的选项,指定为数值或逻辑值 1 (true) 或 0 (false)。

  • 当要读取的区域第一列包含表的行名称时将 ReadRowNames 设置为 true

  • 当要读取的区域第一列包含的是数据而不是表的行名称时将 ReadRowNames 设置为 false

如果 ReadVariableNamesReadRowNames 名称-值参量都为 true,则 readtable 将读取的区域第一行第一列中的名称保存为属性 T.Properties.DimensionNames 中的第一个维度名称。

如果除导入选项对象外您还指定了 ReadRowNames 参量,readtable 的行为将因您的指定而异:

  • 如果 ReadRowNamestrue,则通过使用各自导入选项对象的 RowNamesColumnDelimitedTextImportOptionsFixedWidthImportOptions)、RowNamesRange (SpreadsheetImportOptions) 或 RowNamesSelector (XMLImportOptions) 属性从指定的文件中读取行名称。

  • 如果 ReadRowNamesfalse,则不导入行名称。

如果在不指定 ReadRowNames 的情况下使用导入选项语法,则 readtable 将使用与导入选项对象及其 ReadRowNames 名称-值参量相关联的值。

示例: "ReadRowNames",true

要作为空值处理的占位符文本,指定为 TreatAsMissing 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。与这些字符对应的表元素设置为 NaN

"TreatAsMissing" 仅应用于表中的数值列,而 readtable 不接受数值文字,例如 "-99"

示例: "TreatAsMissing","N/A""TreatAsMissing","N/A" 将数值列内的 N/A 设置为 NaN

示例: 'TreatAsMissing',{'.','NA','N/A'}"TreatAsMissing",[".","NA","N/A"] 将数值列内的 .NAN/A 设置为 NaN

管理缺失数据的过程,指定为下表中的值之一。如果行中不存在预期字段,则认为数据缺失。

缺失规则行为
"fill"

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

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

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

示例: "MissingRule","omitrow"

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

  • "skip" - 跳过空行。

  • "read" - 读取空行。

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

示例: "EmptyRowRule","read"

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

  • "skip" - 跳过空列。

  • "read" - 读取空列。

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

示例: "EmptyColumnRule","error"

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

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

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

示例: "TextType","char"

导入的日期和时间数据的类型,指定为 DatetimeType 和以下值之一:"datetime""text""exceldatenum"。值 "exceldatenum" 仅适用于电子表格文件,对文本文件无效。

导入日期时间数据的类型
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

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

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

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

"exceldatenum"

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

示例: "DatetimeType","datetime"

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

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

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

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

示例: "VariableNamingRule","preserve"

处理导入错误的过程,指定为下表中的值之一。当 readtable 无法将文本转换为预期的数据类型时,会发生导入错误。

导入错误规则行为
"fill"

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

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

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

示例: "ImportErrorRule","omitvar"

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

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

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

示例: "TableIndex",2

数据类型: 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"显示错误消息并中止导入操作。

示例: "MergedCellColumnRule","placeright"

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

导入错误规则行为
"placetop"

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

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

"placebottom"

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

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

"duplicate"

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

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

示例: "MergedCellRowRule","duplicate"

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

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

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

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

示例: "VariableNamesRow",2

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

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

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

示例: "VariableUnitsRow",3

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

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

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

示例: "VariableDescriptionsRow",4

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

表数据 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择输出表数据。您必须将 TableSelector 指定为有效的 XPath 版本 1.0 表达式。使用 XPath 选择器指定要导入 XML 输入文档的哪些元素。

选取操作语法
选择其名称与您要选择的节点匹配的每个节点,而无论它在文档中的位置如何。在名称前加两个正斜杠 (//) 前缀。
选择属于元素节点的属性的值。在属性前加 at 符号 (@) 前缀。
在一组节点中选择一个特定节点。在方括号 ([]) 中提供要选择的节点的索引。
指定运算的优先级。在要首先计算的表达式前后添加圆括号。

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

示例: "myFile.xml", "TableSelector", "//table[1]"

输出参量

全部折叠

输出表,以表形式返回。该表可以存储元数据,例如描述、变量单位、变量名称和行名称。有关详细信息,请参阅 table 的“属性”部分。

扩展功能

版本历史记录

在 R2013b 中推出

全部展开