sftg-frond-library

创建时间：2026-01-19 10:50 操作人：肖瑶

修改时间：2026-01-19 10:50 操作人：肖瑶

基于 Vue 3 + TypeScript + Vite 构建的通用组件库。

🔍 查看所有组件与文档索引

一、组件开发规范

为了维护高质量的组件库和文档，请遵循以下开发规范。 每次修改组件，请及时更新文档。

1. 目录结构

每个组件应拥有独立的文件夹，包含源码、入口文件和文档。

packages/components/
└── [ComponentName]/            # 使用 PascalCase 命名
    ├── [ComponentName].vue     # 组件源码
    ├── index.ts                # 组件导出入口
    └── README.md               # 组件说明文档

2. 文档规范 (README.md)

每个组件必须包含 README.md，用于描述组件的功能和用法。请复制以下模板进行编写。

文档模板

# [ComponentName] 组件中文名称

创建时间：YYYY-MM-DD 操作人：xx
修改时间：YYYY-MM-DD 操作人：xx

## 1. 功能介绍

简要描述组件的功能、用途和适用场景。
可以包含效果截图或 GIF。

## 2. 使用介绍

### 基础用法

提供最简单的代码示例。

\`\`\`vue
<template>
<[ComponentName] />
</template>
\`\`\`

### API

#### Props (属性)

| 参数名称 | 说明     | 类型   | 默认值    | 必填 |
| -------- | -------- | ------ | --------- | ---- |
| example  | 示例参数 | string | 'default' | 否   |

#### Slots (插槽)

| 插槽名称 | 说明     | 作用域参数 |
| -------- | -------- | ---------- |
| default  | 默认内容 | -          |

#### Events (事件)

| 事件名称 | 说明       | 回调参数   |
| -------- | ---------- | ---------- |
| click    | 点击时触发 | (e: Event) |

#### Exposes (暴露方法)

| 方法名称 | 说明           | 参数 |
| -------- | -------------- | ---- |
| focus    | 使组件获取焦点 | -    |

3. 代码规范

1. 命名：组件文件名和文件夹名使用 PascalCase (如 MyComponent)。
2. Setup：推荐使用 <script setup lang="ts">。
3. Props/Emits：必须定义类型 (Typescript Interface 或 Object syntax)。

二、目录结构架构

本项目采用 源码与演示分离 的架构：

• packages/: 组件库的核心源码目录。
  • components/: 存放所有 UI 组件。
  • index.ts: 库的统一入口文件，负责导出组件和 install 方法。
• src/: 开发环境的演示/测试应用 (Playground)。
  • 用于在开发过程中实时预览和调试组件，模拟真实的消费端环境。
• dist/: 构建输出目录 (发布到 npm 的内容)。

root
├── packages/              # [核心] 组件库源码
│   ├── components/        # 组件目录
│   └── index.ts           # 库入口 & 导出
├── src/                   # [开发] 演示应用 (Playground)
├── dist/                  # [产物] 构建后的文件
├── vite.lib.config.ts     # 库打包专用配置
└── vite.config.ts         # 演示应用配置

三、技术栈

• Core: Vue 3 (Script Setup, Composition API)
• Language: TypeScript
• Build Tool: Vite
• Store: Pinia (如果是库依赖)
• Code Quality: ESLint, Prettier
• Type Generation: vite-plugin-dts (自动生成 .d.ts 声明文件)

四、开发指南

1. 项目初始化

npm install

2. 启动开发环境

启动本地开发服务器，可以在 src/App.vue 中直接调试 packages/ 下的组件。

npm run dev

3. 类型检查

npm run type-check

4. 代码格式化与 Lint

npm run lint
npm run format

五、构建与发布

本项目配置了专门的打包脚本，用于生成符合 npm 发包标准的产物（包含 ESM, UMD 和 TypeScript 类型声明）。

构建组件库

运行以下命令，将 packages/ 目录下的内容构建到 dist/ 目录。

npm login
npm run build-lib

产物说明 (dist/):

• sftg-frond-library.js: ESM 格式 (供 Vite/Webpack 等现代构建工具使用)
• sftg-frond-library.umd.cjs: UMD 格式 (供 CDN 或旧版环境使用)
• index.d.ts: TypeScript 类型定义文件
• sftg-frond-library.css: 组件库的样式文件

发布到 npm

构建完成后，确保 package.json 中的 version 已更新，然后运行：

npm publish

六、配置说明

构建配置 (vite.lib.config.ts)

为了区分“组件库构建”和“演示应用构建”，我们创建了独立的配置文件 vite.lib.config.ts。

• Library Mode: 使用 Vite 的库模式 (build.lib)。
• Entry: 指定入口为 packages/index.ts。
• External: 将 vue 和 pinia 排除在打包产物之外，作为外部依赖（peerDependencies）。
• DTS: 集成 vite-plugin-dts 插件，在构建时自动生成类型声明。

TypeScript 配置

• tsconfig.app.json: 用于开发环境 (src/ + packages/)。
• tsconfig.lib.json: 专用于库构建，仅包含 packages/ 目录，确保生成的类型文件干净且不包含测试/演示代码。

七、如何使用

安装

npm install sftg-frond-library

Global Registration (全局注册)

import { createApp } from 'vue'
import App from './App.vue'
import SftgFrondLibrary from 'sftg-frond-library'
import 'sftg-frond-library/dist/sftg-frond-library.css' // 引入样式

const app = createApp(App)
app.use(SftgFrondLibrary)
app.mount('#app')

On-demand Import (按需引入)

<script setup>
import { HelloWorld } from 'sftg-frond-library'
</script>