列出文件

.listfiles {path} {directories?} {recursive?} {pattern?} {fullpath?} {sortby?} {order?} ^{文档 ↗} 函数返回某个目录下的条目组成的可迭代对象 。

默认情况下，结果是 path 所指目录的直接子项的绝对路径组成的无序集合。路径相对于主源文件的位置进行解析，也可以是一个绝对路径。无论使用何种操作系统，都使用正斜杠（/）作为路径分隔符。

对于以下示例，假设存在如下目录结构：

• assets
  • folder
    • file1.txt
    • file2.txt
    • file3.md
    • subfolder
      • nested-file1.txt
      • nested-file2.txt
      • nested-file3.md

.listfiles {assets/folder} fullpath:{no}

结果是一个可迭代值，可以传递给 .foreach 。

.foreach {.listfiles {assets/folder} fullpath:{no}}
    name:
    **File:** .name

完整路径

默认情况下，每个条目以其绝对路径的形式返回：

.listfiles {assets/folder}

这可以与文件数据 函数结合使用，以读取文件内容：

.foreach {.listfiles {assets/folder} directories:{no}}
    path:
    Content of .path::filename::codespan is .path::read::codespan

递归遍历

将 recursive:{yes} 设置为会遍历每一个嵌套子目录，并返回所有后代，而不仅仅是直接子项。

.listfiles {assets/folder} recursive:{yes} fullpath:{no}

结果中绝不会包含根目录自身。

按名称过滤

传入 pattern 只会保留纯文件名匹配给定正则表达式的条目。无论 fullpath 或 recursive 如何设置，该模式始终只应用于文件名本身（绝不会应用于目录路径）。

.listfiles {assets/folder} pattern:{.*\.txt} recursive:{yes} fullpath:{no}

排除目录

将 directories:{no} 设置为结果中只保留文件，从而在输出中省略子目录：

.listfiles {assets/folder} directories:{no}

排序

默认情况下，结果的顺序是未指定的，返回的可迭代对象是无序的。通过 sortby 选择排序标准会将结果切换为一个有序的可迭代对象：

order 参数随后选择排序方向：

• ascending（默认）：最小者在前（A-Z，最旧在前）。
• descending：最大者在前（Z-A，最新在前）。

.listfiles {assets/folder} sortby:{name} order:{descending} fullpath:{no}

批量引入源文件

由于结果是可迭代的，它可以与 .includeall 自然地组合：

.listfiles {chapters} sortby:{name}::includeall

权限

.listfiles 遵循与其他文件读取函数相同的权限模型：

• 在项目目录下列举文件需要 project-read 权限（默认授予）。
• 在项目目录外列举文件需要 global-read（需显式开启）。