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

readcell

基于文件创建元胞数组

全页折叠

语法

C = readcell(filename)
C = readcell(filename,Name,Value)
C = readcell(filename,opts)
C = readcell(filename,opts,Name,Value)

说明

C = readcell(filename) 通过从文本文件或电子表格文件中读取列向数据来创建元胞数组。

示例

C = readcell(filename,Name,Value) 使用一个或多个名称-值参量指定选项。例如，您可以指定文件中标题行的行数、预期的变量数或列数，或要读取的数据范围。

示例

C = readcell(filename,opts) 使用导入选项对象 opts 指定的选项创建元胞数组。使用导入选项对象来配置 readcell 解读文件的方式。与前两种语法相比，导入选项对象在文件导入配置上可以提供更多的控制、更好的性能，并可重复使用

示例

C = readcell(filename,opts,Name,Value) 使用导入选项对象和名称-值参量创建元胞数组。如果除了导入选项对象之外还指定名称-值参量，则 readcell 对文本文件仅支持 DateLocale 和 Encoding 名称-值参量，对电子表格文件仅支持 Sheet 和 UseExcel 名称-值参量。

示例

全部折叠

打开实时脚本

将文本文件的内容导入元胞数组。readcell 将文本文件的每个元素以元胞形式导入输出元胞数组。

C = readcell("basic_cell.txt")
C=3×3 cell array
    {[                   1]}    {[    2]}    {[        3]}
    {'hello'               }    {'world'}    {[      NaN]}
    {[10-Oct-2018 10:27:56]}    {[    1]}    {[<missing>]}
打开实时脚本

将表格数据从电子表格文件导入元胞数组。

C = readcell("basic_cell.xls")
C=3×3 cell array
    {[                   1]}    {[    2]}    {[        3]}
    {'hello'               }    {'world'}    {[<missing>]}
    {[10-Oct-2018 10:27:56]}    {[    1]}    {[<missing>]}
打开实时脚本

将指定的工作表和范围中的数据导入元胞数组。

电子表格文件 airlinesmall_subset.xlsx 包含 1996 年至 2008 年间多个工作表中的数据。电子表格文件中的每个工作表都包含一个给定年份的数据。

从名为 "2007" 的工作表的 G、H 和 I 列导入 10 行数据。Excel® 范围 "G2:I11" 表示由 G 列到 I 列以及第 2 行到第 11 行（标题行后的前 10 行）所定义的数据区域。 

C = readcell("airlinesmall_subset.xlsx","Sheet","2007","Range","G2:I11")
C=10×3 cell array
    {[ 935]}    {[ 935]}    {'WN'}
    {[1041]}    {[1040]}    {'WN'}
    {[1430]}    {[1500]}    {'WN'}
    {[ 940]}    {[ 950]}    {'WN'}
    {[1515]}    {[1515]}    {'WN'}
    {[2042]}    {[2035]}    {'WN'}
    {[2116]}    {[2130]}    {'WN'}
    {[1604]}    {[1605]}    {'WN'}
    {[1258]}    {[1230]}    {'WN'}
    {[1134]}    {[1145]}    {'WN'}
打开实时脚本

使用导入选项对象从文本文件导入变量的子集。

使用 detectImportOptions 函数检测文本文件的各个方面，包括变量名称和类型、分隔符以及空白字符。导入选项对象 opts 将检测到的文件各方面的数据存储为属性。

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: Show all 29 VariableOptions 
	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

通过修改导入选项对象，指定要导入的变量子集和行尾字符。

opts.SelectedVariableNames = ["Year","Month","DayofMonth"];
opts.LineEnding = "\n";

通过将 readcell 与导入选项对象配合使用，导入数据子集。

C = readcell("airlinesmall.csv",opts);

输入参数

全部折叠

要读取的文件的名称，指定为字符串标量或字符向量。您可以指定以下文件格式之一：

  • 扩展名为 .txt、.dat 或 .csv 的带分隔符的文本文件或等宽文本文件。

    • 对于带分隔符的文本文件和等宽文本文件，readcell 将空字段转换为 missing 值。

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

    • readcell 会忽略文件中的无用空白。

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

    • 在安装了 Microsoft® Excel® 的 Windows® 系统上，readcell 能够读取您的 Excel 版本可识别的任何 Excel 电子表格文件格式。

    • 如果您的系统没有 Windows 版的 Excel，或您正在使用 MATLAB® Online™，则 readcell 只能读取 .xls、.xlsm、.xlsx、.xltm 和 .xltx 文件。

  • 扩展名为 .zip、.gz 或 .tar 的压缩和存档文件和文件夹。 (自 R2025a 起)

    • 压缩文件格式作为文件读取。

    • 存档文件格式被视为文件夹。例如，函数将 mydatafiles.zip 解释为文件夹，因此必须在其中指定一个文件，如 mydatafiles.zip/file1.xlsx。

    • 对于以 .gz 扩展名结尾的文件，函数通过使用 .gz 之前的扩展名来确定文件格式。例如，mydata.csv.gz 作为 CSV 文件读取。

如果 filename 不包含扩展名，请使用 FileType 名称-值参量来指示文件格式。

根据文件的位置，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"

文件导入选项，指定为表中的导入选项对象之一，由 detectImportOptions 函数或关联的导入选项函数创建。导入选项对象包含用于配置数据导入过程的属性。下表显示 readcell 在导入数据时应用的每个导入选项对象的属性。

文件类型导入选项对象应用的属性
带分隔符的文本文件DelimitedTextImportOptions 对象

  • SelectedVariableNames

  • DataLines

  • Delimiter

  • Whitespace

  • LineEnding

  • CommentStyle

  • ConsecutiveDelimitersRule

  • LeadingDelimitersRule

  • TrailingDelimitersRule

  • Encoding

  • MissingRule

  • EmptyLineRule

  • ExtraColumnsRule

等宽文本文件FixedWidthImportOptions 对象

  • SelectedVariableNames

  • DataLines

  • VariableWidths

  • Whitespace

  • LineEnding

  • CommentStyle

  • Encoding

  • PartialFieldRule

  • EmptyLineRule

  • MissingRule

  • ExtraColumnsRule

电子表格文件

SpreadsheetImportOptions 对象

  • SelectedVariableNames

  • Sheet

  • DataRange

  • MissingRule

  • ImportErrorRule

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

名称-值参数

全部展开

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

示例: readcell(filename,NumHeaderLines=5) 指示指定文件的前五行是标题行。

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

示例: readcell(filename,"NumHeaderLines",5) 指示指定文件的前五行是标题行。

文本文件

全部展开

文件的类型，指定为 "text" 或 "spreadsheet"。

当 filename 不包括文件扩展名或者扩展名不是以下任一扩展名时，请指定 FileType 名称-值参量：

  • .txt、.dat 或 .csv（用于带分隔符的或等宽文本文件）

  • .xls、.xlsb、.xlsm、.xlsx、.xltm、.xltx 或 .ods（电子表格文件）

示例: "FileType","text"

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

示例: "Delimiter","|"

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

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

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

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

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

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

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

文件中的标题行数，指定为正整数。如果未指定，则 readcell 会自动检测文件中标题行的数目。

示例: "NumHeaderLines",7

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

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

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

示例: "TextType","char"

导入的日期时间数据的类型，指定为下表中的值之一。

值描述
"datetime"

MATLAB datetime 数据类型

有关详细信息，请参阅 datetime。

"text"

导入的日期时间数据的类型取决于 TextType 参量中指定的值：

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

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

预期的变量或列的数目，指定为正整数。如果未指定，readcell 会自动检测变量或列的数目。

要从文本文件中读取的数据部分，指定为以下形式之一的字符串标量、字符向量或数值向量。

指定 Range 的方式描述

起始单元格

"Cell" 或 [row col]

指定数据的起始单元格：

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

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

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

例如："A5" 或 [5 1]

矩形范围

"Corner1:Corner2" 或 [r1 c1 r2 c2]

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

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

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

readcell 只读取包含在指定范围内的数据。readcell 将指定范围内的任何空字段作为空元胞导入。

行范围或列范围

"Row1:Row2" 或 "Column1:Column2"

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

readcell 根据指定的行范围自动检测列范围，从第一个非空列开始读取，一直到数据的最后。readcell 为文件中的每列数据创建一个元胞数组列。

例如："5:500"

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

readcell 根据指定的列范围自动检测行范围，从第一个非空行开始读取，一直到数据的最后或页脚范围。

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

例如："A:K"

起始行号

n

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

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

例如：5

Excel 中的命名范围

"NamedRange"

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

例如："Range","myTable"

未指定或为空

""

如果未指定或为空，readcell 会自动检测使用的范围。

例如："Range",""

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

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

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

示例: 'Whitespace',' _'

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

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

示例: "LineEnding","\n"

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

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

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

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

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

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

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

如果除了导入选项对象外还指定了 Encoding 参量，则 readcell 将使用 Encoding 指定的值，从而覆盖在导入选项中定义的编码。

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

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

文本文件中持续时间数据的输出数据类型，指定为下表中的值之一。

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

MATLAB duration 数据类型。

有关详细信息，请参阅 duration。

"text"

导入的持续时间数据的类型取决于在 TextType 参量中指定的值：

  • 如果 TextType 设置为 "string"，则 readcell 会以字符串数组的形式返回持续时间数据。

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

用于读取日期的区域设置，指定为字符串标量或 xx_YY 形式的字符向量，其中：

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

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

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

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

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

如果除导入选项对象外您还指定了 DateLocale 参量，则 readcell 将使用为 DateLocale 参量指定的值，从而覆盖在导入选项中定义的区域设置。

示例: "DateLocale","ja_JP"

电子表格文件

全部展开

文件的类型，指定为 "text" 或 "spreadsheet"。

当 filename 不包含文件扩展名或扩展名不是以下任一项时，请指定 FileType 名称-值对组参量：

  • .txt、.dat 或 .csv（用于带分隔符的或等宽文本文件）

  • .xls、.xlsb、.xlsm、.xlsx、.xltm、.xltx 或 .ods（电子表格文件）

示例: "FileType","text"

文件中的标题行数，指定为正整数。如果未指定，则 readcell 会自动检测文件中标题行的数目。

示例: "NumHeaderLines",7

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

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

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

示例: "TextType","char"

导入的日期时间数据的类型，指定为下表中的值之一。

值描述
"datetime"

MATLAB datetime 数据类型

有关详细信息，请参阅 datetime。

"text"

导入的日期时间数据的类型取决于 TextType 参量中指定的值：

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

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

"exceldatenum"

Excel 日期序列值

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

预期的变量或列的数目，指定为正整数。如果未指定，readcell 会自动检测变量或列的数目。

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

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

从电子表格文件中读取的数据部分，指定为以下形式之一的字符串标量、字符向量或数值向量。

指定 Range 的方式描述

起始单元格

"Cell" 或 [row col]

将数据的起始单元格指定为：

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

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

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

例如："A5" 或 [5 1]

矩形范围

"Corner1:Corner2" 或 [r1 c1 r2 c2]

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

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

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

readcell 只读取包含在指定范围内的数据。readcell 将指定范围内的任何空字段作为空元胞导入。

行范围或列范围

"Row1:Row2" 或 "Column1:Column2"

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

readcell 根据指定的行范围自动检测列范围，从第一个非空列开始读取，一直到数据的最后。readcell 为文件中的每列数据创建一个元胞数组列。

例如："5:500"

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

readcell 根据指定的列范围自动检测行范围，从第一个非空行开始读取，一直到数据的最后或页脚范围。

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

例如："A:K"

起始行号

n

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

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

例如：5

Excel 中的命名范围

"NamedRange"

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

例如："Range","myTable"

未指定或为空

""

如果未指定或为空，readcell 会自动检测使用的范围。

例如："Range",""

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

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

读取电子表格数据时启动 Windows 版 Microsoft Excel 实例的标志，指定为以下值之一：

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

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

UseExcel

true

false

支持的文件格式

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

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

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

是

否

UseExcel 在非交互式自动化环境中不受支持。

自 R2024b 起

跨列合并单元格的规则，指定为下表中的值之一。

导入规则行为
"placeleft"

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

您可以在要导入的变量的 VariableImportOptions 对象中指定 FillValue 属性。有关设置 FillValue 属性的详细信息，请参阅 setvaropts。

"placeright"

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

您可以在要导入的变量的 VariableImportOptions 对象中指定 FillValue 属性。有关设置 FillValue 属性的详细信息，请参阅 setvaropts。

"duplicate"

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

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

自 R2024b 起

跨行合并单元格的规则，指定为下表中的值之一。

导入规则行为
"placetop"

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

您可以在要导入的变量的 VariableImportOptions 对象中指定 FillValue 属性。有关设置 FillValue 属性的详细信息，请参阅 setvaropts。

"placebottom"

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

您可以在要导入的变量的 VariableImportOptions 对象中指定 FillValue 属性。有关设置 FillValue 属性的详细信息，请参阅 setvaropts。

"duplicate"

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

"omitvar"省略出现合并单元格的变量。
"error"显示错误消息并取消导入操作。

版本历史记录

在 R2019a 中推出

全部展开

另请参阅

| | | |

主题