开发指南

本文档介绍了项目的目录结构、开发流程、新增组件的步骤以及编译与发布流程。

项目结构

项目目录大致如下所示：

saas-aimall-view-docs
├─ .husky
├─ build # 打包脚本
│ ├─ ...
├─ docs # 项目的文档
├─ examples # 示例代码
├─ packages # 工程包
│ ├─ components # 组件库
│ │ ├─ ... # 此处省略组件
│ │ ├─ gulpfile.ts # gulp 打包脚本
│ │ ├─ index.ts # 入口文件
│ │ ├─ package.json
│ │ ├─ vite.config.ts # vite 打包配置
│ │ └─ \***\*common\*\*** # 公用组件
│ ├─ plugins # 插件包
│ └─ utils # 工具包
├─ types # eslint 类型配置
│ ├─ .eslintrc-auto-import.json
│ ├─ .eslintrc-custom.json
│ └─ .eslintrc-import.json
└─ typings # 类型定义
├─ package.json
├─ ...其他工程化配置文件

开发流程

1. 安装依赖
   在项目根目录下执行：

   pnpm i

2. 初次打包
   执行：

   pnpm build

   （需要先执行一次 build）

3. 启动开发预览

   • 启动示例examples页面：

     pnpm dev

   • 启动文档预览：

     pnpm dev:docs

     examples/src/components/*中的组件示例可以相同的在docs/components/*文档中引用，详见下方文档编写

4. 新增组件
   请参考下方“新增组件”的详细步骤。

5. 编译

   • 编译代码库：

     pnpm build

   • 编译文档库：

     pnpm build:docs

6. 发布
   执行：(！需要先 commit 代码，系统会自动更新版本号)

   pnpm runPublish

7. 本地开发并预览
   有时 npm 发布有延迟，或代码合并无法及时响应，可以使用安装本地npm的方法，快速使用对应 新增/修改 的组件：

   1. 在docs组件库先编译生成dist文件夹，pnpm build

   2. 在主端需要引入的项目执行npm install file:../path/to/project

新增组件

以下步骤以创建一个 table UI 组件为例：

1. 创建组件文件夹

在 packages 下对应的目录中（例如组件放在 components 下），创建一个新文件夹 table。在该文件夹内创建 index.ts 文件，用于导出组件。示例代码如下：

import Index from './src/index.vue'
import { withInstall } from '@senhang-ui/utils'
const ShTable = withInstall(Index)
export default ShTable

2. 编写组件代码

在 table/src 文件夹中编写组件代码，通常使用 index.vue 作为入口文件。注意组件名称需采用大驼峰写法，并以 Sh 为前缀。示例代码如下：

<script setup>
defineOptions({
    name: 'ShTable',
})
</script>

！！注意！！：ts类型，需要在packages/components/types中新建同名的{name}.ts文件（无需在index.ts中注册，编译时会生成），不允许写在vue组件中，

<script setup>
// ✅ 正确写法
import { TableData } from '../../types' // 至少一次编译后自动注册

// ❌ 不允许下面这么写：
// export interface TableData{
//   ...
// }
</script>

3. 注册组件

在 packages/components/index.ts 中注册新创建的组件或公用函数。示例代码如下：

import ShTable from './table'

const components: {
    [propName: string]: Component
} = {
    ShTable,
}

export { ShTable }

文档编写

1. 配置文件

常规的 navbar，sidebar 在.vitepress/config.mts配置，详见vitepress文档；
代码预览功能使用了该 插件 ,以下配置定义了demo目录：

// .vitepress/config.mts
markdown: {
    config(md) {
        md.use(vitepressDemoPlugin, {
            demoDir: path.resolve(__dirname, '../../examplesrc/components'),
        })
    },
},

2. 新增文档

docs
├─ components # 打包脚本
│ ├─ components # 组件UI模块
│ ├─ guidebook # 指南模块
│ ├─ plugins # vite组件模块
│ ├─ utils # 公用函数模块

在 md 文件中，使用vue组件渲染

<demo vue="galleryDrawer/basic.vue"/>

常见问题

（在此部分可添加常见问题及解答）

迭代

• [ ] 修复打包后，cjs项目引入组件的ts类型支持
• [ ] 开发模式监听编译
• [ ] 优化auto-import的类型支持