readmatrix

从文件中读取矩阵

全页折叠

语法

A = readmatrix(filename)

A = readmatrix(filename,opts)

A = readmatrix(___,Name,Value)

说明

A = readmatrix(filename) 通过从文件中读取列向数据来创建数组。readmatrix 函数可自动检测文件的导入参数。

readmatrix 基于文件的扩展名确定文件格式：

.txt、.dat 或 .csv（带分隔符的文本文件）
.xls、.xlsb、.xlsm、.xlsx、.xltm、.xltx 或 .ods（电子表格文件）
.zip、.gz 或 .tar（压缩和存档文件）。

对于包含数值和文本混合数据的文件，默认情况下，readmatrix 将数据作为数值数组导入。

示例

A = readmatrix(filename,opts) 还使用导入选项 opts。

示例

A = readmatrix(___,Name,Value) 创建基于文件的数组，且可使用一个或多个名称-值对组参量指定其他选项。您需要在上述语法的输入参量之后指定名称-值对组。

要为数据设置特定的导入选项，您可以使用 opts 对象，也可以指定名称-值对组。当您指定除 opts 之外的名称-值对组时，readmatrix 仅支持下列名称-值对组：

文本文件 - DateLocale、Encoding
电子表格文件 - Sheet、UseExcel

示例

全部折叠

从文本文件中读取矩阵

打开实时脚本

显示 basic_matrix.txt 的内容，然后将数据导入矩阵。

type basic_matrix.txt

6,8,3,1
5,4,7,3
1,6,7,10
4,2,8,2
2,7,5,9

M = readmatrix('basic_matrix.txt')

M = 5×4

     6     8     3     1
     5     4     7     3
     1     6     7    10
     4     2     8     2
     2     7     5     9

从电子表格文件中读取矩阵

打开实时脚本

将数值数据从 basic_matrix.xls 导入矩阵。

M = readmatrix('basic_matrix.xls')

M = 5×4

     6     8     3     1
     5     4     7     3
     1     6     7    10
     4     2     8     2
     2     7     5     9

使用导入选项从指定的工作表和范围中读取矩阵

打开实时脚本

预览电子表格文件中的数据，并以矩阵形式从指定的工作表和范围中导入数值数据。

电子表格文件 airlinesmall_subset.xlsx 包含 1996 年至 2008 年间多个工作表中的数据。每个工作表都包含给定年份的数据。预览文件 airlinesmall_subset.xlsx 中的数据。默认情况下，preview 函数显示第一个工作表中的数据。文件中的前八个变量包含数值数据。

opts = detectImportOptions('airlinesmall_subset.xlsx');
preview('airlinesmall_subset.xlsx',opts)

ans=8×29 table
    Year    Month    DayofMonth    DayOfWeek    DepTime    CRSDepTime    ArrTime    CRSArrTime    UniqueCarrier    FlightNum     TailNum      ActualElapsedTime    CRSElapsedTime    AirTime    ArrDelay    DepDelay    Origin      Dest      Distance    TaxiIn    TaxiOut    Cancelled    CancellationCode    Diverted    CarrierDelay    WeatherDelay      SDelay      SecurityDelay    LateAircraftDelay
    ____    _____    __________    _________    _______    __________    _______    __________    _____________    _________    __________    _________________    ______________    _______    ________    ________    _______    _______    ________    ______    _______    _________    ________________    ________    ____________    ____________    __________    _____________    _________________

    1996      1          18            4         2117         2120        2305         2259          {'HP'}           415       {'N637AW'}           108                 99            85           6          -3       {'COS'}    {'PHX'}      551         5         18           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          12            5         1252         1245        1511         1500          {'HP'}           610       {'N905AW'}            79                 75            58          11           7       {'LAX'}    {'PHX'}      370         3         18           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          16            2         1441         1445        1708         1721          {'HP'}           211       {'N165AW'}            87                 96            74         -13          -4       {'RNO'}    {'PHX'}      601         4          9           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1           1            1         2258         2300        2336         2335          {'HP'}          1245       {'N183AW'}            38                 35            20           1          -2       {'TUS'}    {'PHX'}      110         6         12           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1           4            4         1814         1814        1901         1910          {'US'}           683       {'N963VJ'}            47                 56            34          -9           0       {'DTW'}    {'PIT'}      201         6          7           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          31            3         1822         1820        1934         1925          {'US'}           757       {'N912VJ'}            72                 65            52           9           2       {'PHL'}    {'PIT'}      267         6         14           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          18            4          729          730         841          843          {'US'}          1564       {'N941VJ'}            72                 73            58          -2          -1       {'DCA'}    {'PVD'}      357         3         11           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          26            5         1704         1705        1829         1839          {'NW'}          1538       {'N960N' }            85                 94            69         -10          -1       {'DTW'}    {'RIC'}      456         3         13           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}

配置 opts 对象中的值，以便从名为 '2007' 的工作表中导入前五个变量的 10 行。

opts.Sheet = '2007';
opts.SelectedVariableNames = [1:5]; 
opts.DataRange = '2:11';
M = readmatrix('airlinesmall_subset.xlsx',opts)

M = 10×5

        2007           1           2           2         711
        2007           1           3           3         652
        2007           1           4           4        1116
        2007           1           5           5         825
        2007           1           7           7        1411
        2007           1           8           1        1935
        2007           1           9           2        2005
        2007           1          11           4        1525
        2007           1          12           5        1133
        2007           1          13           6         922

从指定的工作表和范围中读取矩阵

打开实时脚本

预览电子表格文件中的数据，并以矩阵形式从指定的工作表和范围中导入数值数据。

opts = detectImportOptions('airlinesmall_subset.xlsx');
preview('airlinesmall_subset.xlsx',opts)

ans=8×29 table
    Year    Month    DayofMonth    DayOfWeek    DepTime    CRSDepTime    ArrTime    CRSArrTime    UniqueCarrier    FlightNum     TailNum      ActualElapsedTime    CRSElapsedTime    AirTime    ArrDelay    DepDelay    Origin      Dest      Distance    TaxiIn    TaxiOut    Cancelled    CancellationCode    Diverted    CarrierDelay    WeatherDelay      SDelay      SecurityDelay    LateAircraftDelay
    ____    _____    __________    _________    _______    __________    _______    __________    _____________    _________    __________    _________________    ______________    _______    ________    ________    _______    _______    ________    ______    _______    _________    ________________    ________    ____________    ____________    __________    _____________    _________________

    1996      1          18            4         2117         2120        2305         2259          {'HP'}           415       {'N637AW'}           108                 99            85           6          -3       {'COS'}    {'PHX'}      551         5         18           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          12            5         1252         1245        1511         1500          {'HP'}           610       {'N905AW'}            79                 75            58          11           7       {'LAX'}    {'PHX'}      370         3         18           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          16            2         1441         1445        1708         1721          {'HP'}           211       {'N165AW'}            87                 96            74         -13          -4       {'RNO'}    {'PHX'}      601         4          9           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1           1            1         2258         2300        2336         2335          {'HP'}          1245       {'N183AW'}            38                 35            20           1          -2       {'TUS'}    {'PHX'}      110         6         12           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1           4            4         1814         1814        1901         1910          {'US'}           683       {'N963VJ'}            47                 56            34          -9           0       {'DTW'}    {'PIT'}      201         6          7           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          31            3         1822         1820        1934         1925          {'US'}           757       {'N912VJ'}            72                 65            52           9           2       {'PHL'}    {'PIT'}      267         6         14           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          18            4          729          730         841          843          {'US'}          1564       {'N941VJ'}            72                 73            58          -2          -1       {'DCA'}    {'PVD'}      357         3         11           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}    
    1996      1          26            5         1704         1705        1829         1839          {'NW'}          1538       {'N960N' }            85                 94            69         -10          -1       {'DTW'}    {'RIC'}      456         3         13           0           {0×0 char}          0         {0×0 char}      {0×0 char}     {0×0 char}     {0×0 char}         {0×0 char}

从名为 '2007' 的工作表中导入前 5 个变量的 10 行。

M = readmatrix('airlinesmall_subset.xlsx','Sheet','2007','Range','A2:E11')

M = 10×5

        2007           1           2           2         711
        2007           1           3           3         652
        2007           1           4           4        1116
        2007           1           5           5         825
        2007           1           7           7        1411
        2007           1           8           1        1935
        2007           1           9           2        2005
        2007           1          11           4        1525
        2007           1          12           5        1133
        2007           1          13           6         922

输入参数

全部折叠

`filename` — 要读取的文件的名称
字符向量 | 字符串标量

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

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

如果 filename 包含文件扩展名，则导入函数基于扩展名确定文件格式。否则，您必须指定 'FileType' 名称-值对组参量以指示文件类型。
在安装了 Microsoft^® Excel^® 软件的 Windows^® 系统上，导入函数读取您的 Excel 版本可识别的任何 Excel 电子表格文件格式。
如果您的系统没有 Windows 版 Excel 或者您正在使用 MATLAB Online™，则导入函数在 UseExcel 属性设置为 false 的情况下运行，并且只读取 .xls, .xlsx, .xlsm, .xltx, and .xltm 文件。
对于带分隔符的文本文件，导入函数将文件中的空字段转换为 NaN（对于数值变量）或空字符向量（对于文本变量）。文本文件中的所有行必须有相同数量的分隔符。导入函数会忽略文件中的无用空白。
压缩文件格式作为文件读取。存档文件格式被视为文件夹。例如，函数将 mydatafiles.zip 解释为文件夹，因此必须在其中指定一个文件，如 mydatafiles.zip/file1.xlsx。对于以 .gz 扩展名结尾的文件，函数通过使用 .gz 之前的扩展名来确定文件格式。例如，mydata.csv.gz 作为 CSV 文件读取。 (自 R2025a 起)

数据类型: char | string

`opts` — 文件导入选项
`SpreadsheetImportOptions` | `DelimitedtextImportOptions` | `FixedWidthImportOptions` | `XMLImportOptions`

文件导入选项，指定为 detectImportOptions 函数创建的 SpreadsheetImportOptions、DelimitedTextImportOptions、FixedWidthImportOptions 或 XMLImportOptions 对象。opts 对象包含控制数据导入过程的属性。有关每个对象的属性的详细信息，请参阅相应的对象页。

文件类型	输出
电子表格文件	`SpreadsheetImportOptions` 对象（仅对 `Sheet`、`DataRange` 和 `VariableNames` 属性可用）
文本文件	`DelimitedTextImportOptions` 对象
等宽文本文件	`FixedWidthImportOptions` 对象
XML 文件	`XMLImportOptions` 对象

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

名称-值参数

全部展开

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

如果使用的是 R2021a 之前的版本，请使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: 'NumHeaderLines',5 表示表格数据前面的前五行是标题行。

所有支持的文件类型

全部展开

`WebOptions` — `HTTP` 或 `HTTPS` 请求选项
`weboptions` 对象

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

文本和电子表格文件

全部展开

`FileType` — 文件类型
`'text'` | `'spreadsheet'`

文件类型，以逗号分隔的对组形式指定，其中包含 'FileType' 以及 'text' 或 'spreadsheet'。

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

.txt、.dat 或 .csv（带分隔符的文本文件）
.xls、.xlsb、.xlsm、.xlsx、.xltm、.xltx 或 .ods（电子表格文件）

示例: 'FileType','text'

数据类型: char | string

`NumHeaderLines` — 标题行数
正整数

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

示例: 'NumHeaderLines',7

数据类型: single | double

`ExpectedNumVariables` — 需要的变量数目
正整数

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

数据类型: single | double

`Range` — 要读取的数据部分
字符向量 | 字符串标量 | 数值向量

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

指定 Range 的方式描述

指定 `Range` 的方式	描述
起始单元格 `'Cell'` 或 `[row col]`	将数据的起始单元格指定为字符向量、字符串标量或二元素数值向量。字符向量或字符串标量，其中包含使用 Excel `A1` 表示法的列字母和行号。例如，`A5` 是第 `A` 列与第 `5` 行相交处的单元格的标识符。二元素数值向量，形式为 `[row col]`，表示起始行和列。根据起始单元格，导入函数通过从起始单元格开始导入，并在到达最后一个空行或页脚范围时结束，从而自动检测数据范围。示例：`'A5'` 或 `[5 1]`
矩形范围 `'Corner1:Corner2'` 或 `[r1 c1 r2 c2]`	使用以下形式之一的矩形范围指定要读取的精确范围。 `'Corner1:Corner2'` - 使用 `Corner1` 和 `Corner2` 指定范围，这两个对角以 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',''` 注意：使用范围指电子表格中实际包含数据的矩形部分。导入函数通过删减不包含数据的前导行列和尾随行列，自动检测使用范围。只包含空白的文本被视为数据，并会在使用范围内被捕获。

起始单元格

'Cell' 或 [row col]

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

字符向量或字符串标量，其中包含使用 Excel A1 表示法的列字母和行号。例如，A5 是第 A 列与第 5 行相交处的单元格的标识符。
二元素数值向量，形式为 [row col]，表示起始行和列。

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

示例：'A5' 或 [5 1]

矩形范围

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

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

'Corner1:Corner2' - 使用 Corner1 和 Corner2 指定范围，这两个对角以 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

`TreatAsMissing` — 要解释为缺失数据的文本
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

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

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

数据类型: char | string | cell

`OutputType` — 输出数据类型
字符向量 | 字符串标量

输出数据类型，指定为以逗号分隔的对组，由 'OutputType' 和包含下表中任何数据类型名称的字符向量或字符串标量组成。

数据类型	输出数据类型
数值	`'uint8'`、`'int8'`、`'int16'`、`'int32'`、`'int64'`、`'uint16'`、`'uint32'`、`'uint64'`、`'single'` 或 `'double'`
文本	`'char'` 或 `'string'`
其他类型	`'datetime'`、`'duration'` 或 `'categorical'`

示例: 'OutputType','uint8'

数据类型: char | string

仅限文本文件

全部展开

`Delimiter` — 字段分隔符
字符串数组 | 字符向量 | 字符向量元胞数组

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

示例: "Delimiter","|"

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

`Whitespace` — 要视为空白的字符
字符向量 | 字符串标量

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

示例: 'Whitespace',' _'

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

`LineEnding` — 行尾字符
`["\n","\r","\r\n"]` (默认) | 字符串数组 | 字符向量 | 字符向量元胞数组

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

示例: "LineEnding","\n"

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

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

`CommentStyle` — 注释样式
字符串数组 | 字符向量 | 字符向量元胞数组

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

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

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

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

`Encoding` — 字符编码方案
`'UTF-8'` | `'ISO-8859-1'` | `'windows-1251'` | `'windows-1252'` | ...

与文件关联的字符编码方案，指定为以逗号分隔的对组，其中包含 'Encoding' 和 'system' 或标准字符编码方案名称。如果您没有指定任何编码，则 readmatrix 函数在读取文件时将使用自动字符集检测来确定编码。

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

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

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

数据类型: char | string

`DateLocale` — 用于读取日期的区域设置
字符向量 | 字符串标量

用于读取日期的区域设置，指定为逗号分隔的对组，其中包含 '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'

`DecimalSeparator` — 表示小数分隔符的字符
字符向量 | 字符串标量

表示数值变量中小数分隔符的字符，指定为字符向量或字符串标量。导入函数使用 DecimalSeparator 名称-值对组中指定的字符来区分数字的整数部分和小数部分。

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

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

数据类型: char | string

`ThousandsSeparator` — 表示千分位的字符
字符向量 | 字符串标量

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

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

数据类型: char | string

`TrimNonNumeric` — 删除非数值字符
`false` (默认) | `true`

从数值变量中删除非数值字符，指定为逻辑值 true 或 false。

示例: 如果名称-值对组指定为 'TrimNonNumeric',true，则导入函数将 '$500/-' 读取为 500。

数据类型: logical

`ConsecutiveDelimitersRule` — 管理连续分隔符的过程
`"split"` | `"join"` | `"error"`

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

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

`LeadingDelimitersRule` — 管理前导分隔符的过程
`"keep"` | `"ignore"` | `"error"`

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

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

`TrailingDelimitersRule` — 管理尾部分隔符的过程
`'keep'` | `'ignore'` | `'error'`

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

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

仅限电子表格文件

全部展开

`Sheet` — 要从中读取数据的工作表
`''` 空字符数组 (默认) | 字符向量 | 字符串标量 | 正整数标量

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

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

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

`UseExcel` — 用于启动 Windows 版 Microsoft Excel 实例的标志
`false` (默认) | `true`

用于在读取电子表格数据时启动 Windows 版 Microsoft Excel 实例的标志，指定为逗号分隔的对组，包含 'UseExcel' 和 true 或 false。

您可以将 'UseExcel' 参数设置为下列值之一：

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

UseExcel	`true`	`false`
支持的文件格式	`.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods`	`.xls, .xlsx, .xlsm, .xltx, .xltm`
支持交互功能，例如公式和宏	是	否

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

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

`MergedCellColumnRule` — 跨列合并单元格的规则
`"placeleft"` (默认) | `"placeright"` | `"duplicate"` | `"omitrow"` | `"error"`

自 R2024b 起

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

导入规则	行为
`"placeleft"`	将数据放在最左侧单元格中，并用 `FillValue` 属性的内容填充其余单元格。您可以在要导入的变量的 `VariableImportOptions` 对象中指定 `FillValue` 属性。有关设置 `FillValue` 属性的详细信息，请参阅 `setvaropts`。
`"placeright"`	将数据放在最右侧单元格中，并用 `FillValue` 属性的内容填充其余单元格。您可以在要导入的变量的 `VariableImportOptions` 对象中指定 `FillValue` 属性。有关设置 `FillValue` 属性的详细信息，请参阅 `setvaropts`。
`"duplicate"`	在所有单元格中复制数据。
`"omitrow"`	忽略出现合并单元格的行。
`"error"`	显示错误消息并取消导入操作。

`MergedCellRowRule` — 跨行合并单元格的规则
`"placetop"` (默认) | `"placebottom"` | `"duplicate"` | `"omitvar"` | `"error"`

自 R2024b 起

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

导入规则	行为
`"placetop"`	将数据放在顶部单元格中，并用 `FillValue` 属性的内容填充其余单元格。您可以在要导入的变量的 `VariableImportOptions` 对象中指定 `FillValue` 属性。有关设置 `FillValue` 属性的详细信息，请参阅 `setvaropts`。
`"placebottom"`	将数据放在底部单元格中，并用 `FillValue` 属性的内容填充其余单元格。您可以在要导入的变量的 `VariableImportOptions` 对象中指定 `FillValue` 属性。有关设置 `FillValue` 属性的详细信息，请参阅 `setvaropts`。
`"duplicate"`	在所有单元格中复制数据。
`"omitvar"`	省略出现合并单元格的变量。
`"error"`	显示错误消息并取消导入操作。

扩展功能

全部展开

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

对于代码生成，readmatrix 支持 Delimiter、NumHeaderLines 和 ExpectedNumVariables 作为名称-值参量。
您必须同时指定 Delimiter 和 NumHeaderLines 名称-值参量才能生成代码。
readmatrix 仅支持数值数据类型。
代码生成不支持文件导入选项。
此函数仅支持从本地文件系统上存储的文本文件中读取数值矩阵。不支持从 Excel 文件读取。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

请参阅“C/C++ 代码生成”部分中的用法说明和限制。同样的用法说明和限制也适用于 GPU 代码生成。

版本历史记录

在 R2019a 中推出

全部展开

R2026a: 代码生成支持

为 readmatrix 函数生成 C/C++ 代码。

R2025a: 从压缩和存档文件中读取数据

您可以将压缩和存档文件中的数据作为矩阵读取。

R2024b: 指定如何导入电子表格中的合并单元格

从电子表格导入数据时，您可以使用 MergedCellRowRule 和 MergedCellColumnRule 名称-值参量来指定 readmatrix 如何导入跨行和列合并的单元格。

另请参阅

readtable | readtimetable | readvars | readcell | writematrix

主题

Control How MATLAB Imports Your Data

readmatrix

语法

说明

示例

从文本文件中读取矩阵

从电子表格文件中读取矩阵

使用导入选项从指定的工作表和范围中读取矩阵

从指定的工作表和范围中读取矩阵

输入参数

filename — 要读取的文件的名称 字符向量 | 字符串标量

opts — 文件导入选项 SpreadsheetImportOptions | DelimitedtextImportOptions | FixedWidthImportOptions | XMLImportOptions

名称-值参数

所有支持的文件类型

WebOptions — HTTP 或 HTTPS 请求选项 weboptions 对象

文本和电子表格文件

FileType — 文件类型 'text' | 'spreadsheet'

NumHeaderLines — 标题行数 正整数

ExpectedNumVariables — 需要的变量数目 正整数

Range — 要读取的数据部分 字符向量 | 字符串标量 | 数值向量

TreatAsMissing — 要解释为缺失数据的文本 字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

OutputType — 输出数据类型 字符向量 | 字符串标量

仅限文本文件

Delimiter — 字段分隔符 字符串数组 | 字符向量 | 字符向量元胞数组

Whitespace — 要视为空白的字符 字符向量 | 字符串标量

LineEnding — 行尾字符 ["\n","\r","\r\n"] (默认) | 字符串数组 | 字符向量 | 字符向量元胞数组

CommentStyle — 注释样式 字符串数组 | 字符向量 | 字符向量元胞数组

Encoding — 字符编码方案 'UTF-8' | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

DateLocale — 用于读取日期的区域设置 字符向量 | 字符串标量

DecimalSeparator — 表示小数分隔符的字符 字符向量 | 字符串标量

ThousandsSeparator — 表示千分位的字符 字符向量 | 字符串标量

TrimNonNumeric — 删除非数值字符 false (默认) | true

ConsecutiveDelimitersRule — 管理连续分隔符的过程 "split" | "join" | "error"

LeadingDelimitersRule — 管理前导分隔符的过程 "keep" | "ignore" | "error"

TrailingDelimitersRule — 管理尾部分隔符的过程 'keep' | 'ignore' | 'error'

仅限电子表格文件

Sheet — 要从中读取数据的工作表 '' 空字符数组 (默认) | 字符向量 | 字符串标量 | 正整数标量

UseExcel — 用于启动 Windows 版 Microsoft Excel 实例的标志 false (默认) | true

MergedCellColumnRule — 跨列合并单元格的规则 "placeleft" (默认) | "placeright" | "duplicate" | "omitrow" | "error"

MergedCellRowRule — 跨行合并单元格的规则 "placetop" (默认) | "placebottom" | "duplicate" | "omitvar" | "error"

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

版本历史记录

R2026a: 代码生成支持

R2025a: 从压缩和存档文件中读取数据

R2024b: 指定如何导入电子表格中的合并单元格

另请参阅

主题

`filename` — 要读取的文件的名称
字符向量 | 字符串标量

`opts` — 文件导入选项
`SpreadsheetImportOptions` | `DelimitedtextImportOptions` | `FixedWidthImportOptions` | `XMLImportOptions`

`WebOptions` — `HTTP` 或 `HTTPS` 请求选项
`weboptions` 对象

`FileType` — 文件类型
`'text'` | `'spreadsheet'`

`NumHeaderLines` — 标题行数
正整数

`ExpectedNumVariables` — 需要的变量数目
正整数

`Range` — 要读取的数据部分
字符向量 | 字符串标量 | 数值向量

`TreatAsMissing` — 要解释为缺失数据的文本
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

`OutputType` — 输出数据类型
字符向量 | 字符串标量

`Delimiter` — 字段分隔符
字符串数组 | 字符向量 | 字符向量元胞数组

`Whitespace` — 要视为空白的字符
字符向量 | 字符串标量

`LineEnding` — 行尾字符
`["\n","\r","\r\n"]` (默认) | 字符串数组 | 字符向量 | 字符向量元胞数组

`CommentStyle` — 注释样式
字符串数组 | 字符向量 | 字符向量元胞数组

`Encoding` — 字符编码方案
`'UTF-8'` | `'ISO-8859-1'` | `'windows-1251'` | `'windows-1252'` | ...

`DateLocale` — 用于读取日期的区域设置
字符向量 | 字符串标量

`DecimalSeparator` — 表示小数分隔符的字符
字符向量 | 字符串标量

`ThousandsSeparator` — 表示千分位的字符
字符向量 | 字符串标量

`TrimNonNumeric` — 删除非数值字符
`false` (默认) | `true`

`ConsecutiveDelimitersRule` — 管理连续分隔符的过程
`"split"` | `"join"` | `"error"`

`LeadingDelimitersRule` — 管理前导分隔符的过程
`"keep"` | `"ignore"` | `"error"`

`TrailingDelimitersRule` — 管理尾部分隔符的过程
`'keep'` | `'ignore'` | `'error'`

`Sheet` — 要从中读取数据的工作表
`''` 空字符数组 (默认) | 字符向量 | 字符串标量 | 正整数标量

`UseExcel` — 用于启动 Windows 版 Microsoft Excel 实例的标志
`false` (默认) | `true`

`MergedCellColumnRule` — 跨列合并单元格的规则
`"placeleft"` (默认) | `"placeright"` | `"duplicate"` | `"omitrow"` | `"error"`

`MergedCellRowRule` — 跨行合并单元格的规则
`"placetop"` (默认) | `"placebottom"` | `"duplicate"` | `"omitvar"` | `"error"`

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。