Vue Academy · 课时

组件库的 TypeScript 声明

Q: 「组件库的 TypeScript 声明」这节课中我会学到什么？

vite-plugin-dts、生成 .d.ts 文件，以及为库使用者标注组件 props 的类型 你通过在浏览器中直接运行的动手代码来练习 Vue Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

vite-plugin-dts、生成 .d.ts 文件，以及为库使用者标注组件 props 的类型

组件库的 TypeScript 声明 是 CoddyKit 上的免费 Vue Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Vue Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Vue Academy 课程共包含 4 节课。

为什么需要类型声明

TypeScript 使用者需要 .d.ts 文件，才能获得组件和属性的自动补全与类型检查。发布的库应当将生成的声明文件与 JS 一同提供。

vite-plugin-dts 插件

vite-plugin-dts 会在 Vite 构建期间从源代码生成 .d.ts 文件，其中包括 .vue 单文件组件的类型。

npm install -D vite-plugin-dts

添加插件

将 dts() 添加到插件数组中。它会在编译后运行，将声明文件输出到 dist。

import dts from "vite-plugin-dts";

export default defineConfig({
  plugins: [vue(), dts()]
});

insertTypesEntry

insertTypesEntry 选项会生成一个统一的 index.d.ts 入口文件，重新导出您的所有类型，与 JS 入口点保持一致。

dts({
  insertTypesEntry: true
})

生成的 d.ts 文件

构建后，dist 中会包含与源代码对应的 .d.ts 文件，以及聚合后的入口声明。这些文件描述组件属性、触发事件和导出内容。

// dist/index.d.ts
export { MyButton } from "./MyButton.vue";
// dist/MyButton.vue.d.ts describes its props

package.json 的 types 字段

通过 types（或 typings）字段将使用者指向入口声明，以便 TypeScript 解析您库的类型。

{
  "types": "./dist/index.d.ts"
}

导出映射中的类型

现代软件包还会在 exports 映射中为每个入口公开类型，从而正确解析子路径导入。

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/my-ui-lib.es.js"
    }
  }
}

全局组件自动补全

当使用者全局注册您的组件时，TypeScript 需要在 GlobalComponents 接口中声明这些组件，才能提供模板自动补全和属性检查。

扩展 GlobalComponents

提供一个模块扩展，将您的组件添加到 vue 的 GlobalComponents 中。引用您类型的使用者就能在模板中获得 IntelliSense。

// global.d.ts
import MyButton from "./MyButton.vue";

declare module "vue" {
  export interface GlobalComponents {
    MyButton: typeof MyButton;
  }
}
export {};

为组件属性添加类型

将 defineProps 与 TypeScript 类型结合使用，使生成的声明能够向使用者传递准确的属性类型。

// MyButton.vue <script setup lang="ts">
defineProps<{
  label: string;
  disabled?: boolean;
}>();

验证类型

发布前，请在示例使用者项目中运行 tsc --noEmit（或使用 attw/are-the-types-wrong 之类的工具），确认声明能够正确解析并且属性得到检查。

npx tsc --noEmit

快速检查

GlobalComponents 扩展能为库的使用者提供什么？

回顾

使用 vite-plugin-dts 和 insertTypesEntry 生成 .d.ts 文件，将 package.json 的 types 字段（以及 exports 映射）指向入口声明，并提供 GlobalComponents 扩展，让使用者获得模板自动补全。使用 defineProps 为属性添加类型，并通过 tsc --noEmit 进行验证。

常见问题解答

「组件库的 TypeScript 声明」课时是免费的吗？

是的 — 「组件库的 TypeScript 声明」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Vue Academy 课程的其余内容，请升级到 CoddyKit PRO。 Vue Academy 课程共包含 4 节课。

「组件库的 TypeScript 声明」这节课中我会学到什么？

vite-plugin-dts、生成 .d.ts 文件，以及为库使用者标注组件 props 的类型你通过在浏览器中直接运行的动手代码来练习 Vue Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Vue Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Vue Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「组件库的 TypeScript 声明」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Vue Academy 课中编写并运行代码吗？

能。每节 Vue Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Vue Academy