文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载在 Astro 项目中把 Markdown 文件渲染成页面之后往往还需要在索引页拿到这批文件的清单使用Astro.glob()可以轻松做到这一点但它的返回值默认是隐式any会破坏 TypeScript 的类型安全。本文以 TIL 仓库中的 Markdown Files Are Of Type MarkdownInstance 为主线完整讲解MarkdownInstanceT泛型类型的定义方式、两种消除隐式any的写法以及它与 Content Collections 方案的取舍。读完你就能为自己的 Markdown 文章列表页写出完全类型安全的代码。场景用 Astro.glob() 批量读取 Markdown 文件Astro 最擅长的能力之一就是把 Markdown 文件作为 HTML 页面渲染进你的站点。随之而来的一个常见需求是在索引页上展示这些 Markdown 文件的清单比如把全部博客文章的标题和 slug 渲染成一个列表。为此Astro 提供了Astro.glob()这个全局方法。它接收一个相对当前文件路径的 glob 模式返回一个 Promiseresolve 后得到所有匹配文件对应的条目数组。假设文章的 Markdown 文件放在src/posts目录下而索引页位于src/pages目录中那么从索引页的角度看这些文章位于../posts/--- const allPosts await Astro.glob(../posts/*.md); --- ul {allPosts.map(post { return Post title{post.frontmatter.title} slug{post.frontmatter.slug} / })} /ul*匹配当前目录下的所有 Markdown 文件每个post都携带了该文件的 frontmatter 解析结果可以直接通过post.frontmatter.title、post.frontmatter.slug访问。这里的Post是一个接收title与slug两个 props 的展示组件。第一道坎allPosts implicitly has type any上面的代码看起来没有问题但第一行const allPosts await Astro.glob(../posts/*.md)会触发一个 TypeScript 类型错误allPosts implicitly has type any原因在于Astro.glob()的参数是一个字符串 glob 模式Astro 无法仅仅从模式字符串推断出匹配到的 Markdown 文件内部 frontmatter 的结构因此返回条目的类型退化为any进而allPosts被隐式推断为any[]。在strict模式下隐式any是不允许的。要消除这个错误就需要我们显式地声明这些由 Astro 读入的 Markdown 条目到底是什么类型。MarkdownInstance Markdown 条目的真实类型在 Astro 的 API 设计里经由Astro.glob()以及传统方式读取的 Markdown 文件其条目类型是 typeMarkdownInstance。它本身是一个泛型泛型参数T表示该 Markdown 文件 frontmatter 的形状。因此仅写MarkdownInstance是不够的我们还需要告诉它一个 post 的具体形状。这也是原文档强调thats a generic though, so we need to tell it a bit more about the shape of a post的原因。从该类型的官方定义看MarkdownInstanceT除了frontmatter: T之外还对外暴露了一批常用成员实践中值得了解成员含义frontmatter: T解析后的 frontmatter 数据形状由泛型参数T决定file: string该 Markdown 文件在项目中的路径url: string \| undefined该条目渲染后的页面 URLgetHeadings(): PromiseHeading[]读取 Markdown 中的标题层级rawContent(): Promisestring返回未经编译的原始 Markdown 内容compiledContent(): Promisestring返回编译后的 HTML 字符串Content/default可直接在模板中渲染的组件形式这些成员中日常在列表页使用频率最高的是frontmatterContent则常用于把整篇文章内联渲染到页面里。定义 frontmatter 形状组合出 Post 类型既然MarkdownInstance需要知道 frontmatter 的形状我们就在项目里先定义一个描述 frontmatter 的类型再把它作为泛型参数传给MarkdownInstanceimport type { MarkdownInstance } from astro; export type BarePost { layout: string; title: string; slug: string; tags: string[]; }; export type Post MarkdownInstanceBarePost;BarePost描述了每篇文章 frontmatter 中我们要用的字段layout渲染该文章所用的布局、title标题、slug用于生成路由的短链接以及tags标签数组。Post则是一个 Markdown 条目 已知 frontmatter 形状的完整类型它既包含MarkdownInstance提供的全部成员又把frontmatter精确约束为BarePost。注意这里的import typeMarkdownInstance只用于类型标注不产生运行时开销因此使用类型导入是正确做法。BarePost与Post都可以export方便在多个页面、组件或工具函数中复用。消除隐式 any 的两种写法拿到Post类型后就可以回头修正最开始的那行代码。第一种方式是为变量添加显式类型注解声明allPosts是一个Post[]const allPosts: Post[] await Astro.glob(../posts/*.md);这样allPosts中每一个post都被视为MarkdownInstanceBarePost模板里的post.frontmatter.title与post.frontmatter.slug都会获得完整的类型检查与编辑器补全tags也会被正确识别为string[]。第二种方式是把泛型直接写在glob上——Astro.glob()本身也接受泛型参数它同样表示匹配条目的 frontmatter 形状const allPosts await Astro.globBarePost(../posts/*.md);两种写法得到的结果在类型上是等价的区别只在于代码组织变量注解版类型与数据分离Post可以作为独立类型在多个文件间复用适合一篇文章多处使用同一形状的项目glob 泛型版类型就地声明更简洁适合只有这一处使用且不想额外导出一个类型的情况。实战提醒glob 路径与可复用性使用Astro.glob()时还有几个实践要点值得留意路径基准glob 模式是相对于当前文件的。本文示例中索引页位于src/pages下一级所以用../posts/*.md指向上级目录中的posts目录实际写法需根据目录结构调整例如首页与文章目录平级时可直接写./posts/*.md。类型即契约把BarePost定义与文章模板约定保持一致一旦 frontmatter 结构变化如新增字段编译器会立即在列表页报错起到文档化数据契约的作用。字段按需声明BarePost中只需列出实际会用到的字段无需把每篇文章的全部 frontmatter 都声明进去。与 Content Collections 方案的对照在 Generate Types For A Content Collection 一文中仓库作者记录了另一种官方推荐的博客组织方式把文章放入src/content下的 Content Collection并在 src/content/config.ts 中用 Zod schema 描述 frontmatter 校验规则。两者解决的是同一类问题Markdown 文章要有确定的类型但机制不同Astro.glob()MarkdownInstanceT类型完全由开发者手写维护适用于文件散落在任意位置、或希望轻量获取文件清单的场景类型信息在代码中显式声明。Content Collections astro sync由astro:content模块与 astro sync 命令 根据 schema 自动生成类型生成结果落在.astro目录并被env.d.ts引入getCollection(posts)返回的条目自动携带 schema 推导出的类型astro dev、astro build、astro check运行时也会自动同步这些类型。额外收益是构建时对 frontmatter 进行 Zod 校验。选择建议如果文章有严格的 frontmatter 约定并且需要构建期校验优先考虑 Content Collections配合astro sync自动生成类型如果只是简单地把一批 Markdown 文件作为静态页面渲染、并在索引页列出它们Astro.glob()配合本文的MarkdownInstanceT手写类型就足够轻量直接。小结Astro.glob()是 Astro 中读取一批 Markdown 文件的入口但它的返回条目不会自动拥有具体的 frontmatter 类型。解决路径非常清晰这些条目的真实类型是泛型MarkdownInstanceT通过自定义BarePost描述 frontmatter 形状并用MarkdownInstanceBarePost组合出Post类型再以变量注解或globBarePost泛型两种方式消除隐式any即可让列表渲染代码获得完整的类型安全保障。若项目对文章数据有更严格的校验与自动类型生成需求则可转向仓库另一篇笔记记录的 Content Collections 方案。赞分享文档教程知识库【免费下载链接】til:memo: Today I Learned项目地址https://gitcode.com/gh_mirrors/ti/til点击查看免费下载相关推荐如何快速上手pypush10分钟学会苹果私有API的入门教程如何快速上手pypush10分钟学会苹果私有API的入门教程 pypush是一款跨平台的iMessage逆向工程POC项目能够帮助开发者探索苹果私有API的后端即时通讯逆向工程多人游戏库存同步inventory-system 服务器权威设计指南多人游戏库存同步inventory system 服务器权威设计指南 inventory system 是 Godot 4 的模块化库存系统插件采用 CSlate v2 泛型类型系统重构以 Plate 为基准替代 CustomTypes 声明合并Slate v2 泛型类型系统重构以 Plate 为基准替代 CustomTypes 声明合并 本文是 plate 仓库中 Slate v2 类型系统专项计划前端富文本UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考