腾龙开发底座

主题

全局资源 ​

图片 ​

框架用到的图片资源都放在 /src/assets/images/ 目录下，可自行新建文件夹分类管理。

样式 ​

样式存放目录为 /src/assets/styles/ ，因为 Vue 的文件特性，页面样式建议写在 .vue 文件里，所以该目录只存放全局样式，方便统一管理。

此目录下还有一个特殊目录，即 /src/assets/styles/resources/ ，这是全局 SCSS 资源目录，首先这个目录里只支持 .scss 文件，其次在这个目录里的文件，无需在页面上引用即可生效并使用。 该能力是用 vite 插件实现的

说明

全局 SCSS 资源并不是全局样式，是变量、@mixin 、@function 这些东西

组件 ​

组件化开发是提高开发效率、保证项目质量的关键。组件按照其作用域和适用范围可细分为项目级公共组件、应用级公共组件以及局部组件，每一级别的组件都在项目的不同层次中扮演着至关重要的角色，其适用范围由广及窄，约束也随之递减。这里只展示组件的存放位置和导出方式，具体的组件描述请查看 components 介绍。

项目级公共组件 beta ​

描述

项目级公共组件是跨越整个项目，供多个应用或模块共享的通用组件。这些组件被设计为高度复用的UI构建块，旨在提供一致的用户界面元素和交互模式。具体而言：

  • 存储位置：项目级公共组件位于 packages/components/ 目录下，这一结构化的存储方案确保了组件库的清晰和可维护性。
  • 组织方式：为了优化管理和引用效率，每个组件都独立存放在对应的子文件夹中。这种组织方式不仅便于开发者快速定位和更新组件，也有利于维护组件间的依赖关系。
  • 导出机制：所有项目级公共组件统一通过根目录下的 index.ts 文件导出。这一集中导出机制简化了组件的引用路径，提高了开发效率。
  • 统一前缀：为标识清晰这是项目级公共组件，所有组件的文件名都以 Pub 开头。这一命名规范有助于开发者快速识别组件的作用域和适用范围。
  • 自动注册：为了进一步优化开发体验，项目内公共组件在项目构建过程中将被自动注册到全局。这意味着，在项目的任何地方使用这些组件时，开发者无需进行手动引入，从而实现了“零配置”使用。
ts
// 按照如下 PubTestDemo 方式导出, 组件名称必须已Pub开头
export { default as PubTestDemo } from './TestDemo/index.vue'

// 全局组件导出
export { default as PubSvgIcon } from './SvgIcon/index.vue'
export { default as PubFixedActionBar } from './FixedActionBar/index.vue'
export { default as PubListLayout } from './LayoutContainer/index.vue'
export { default as PubPageHeader } from './PageHeader/index.vue'
export { default as PubPageMain } from './PageMain/index.vue'
export { default as PubSearchBar } from './SearchBar/index.vue'
export { default as PubTrend } from './Trend/index.vue'

注意事项

此处仅用于全局组件，避免包含任何业务逻辑或全局状态。若组件涉及特定业务逻辑， 请在应用的components目录中创建。对于与业务逻辑紧密相关且复用频率极高的组件， 应当将其与应用一同导出。例如，涉及获取用户信息的弹窗组件，应从rbac（权限管理系统）中导出以便在其他应用中复用。 这种做法是因为高度耦合的业务组件往往与接口和全局状态密切相关，将其与特定应用绑定更加合理明晰

应用级公共组件 ​

描述

应用级公共组件指的是专为特定应用设计的通用组件，它们解决了该应用内部多个页面或功能模块间的共享需求。与项目级公共组件相比，应用级公共组件的范围更为局限，专注于解决特定应用的通用设计和功能实现问题

  • 存储位置：这一类组件统一存放于应用的 /src/components/ 目录下。此路径的选择反映了应用级公共组件与特定应用紧密关联的特点，同时保持了源代码的结构化和系统性。
  • 组织架构：为了保持架构的清晰性与可维护性，每个应用级公共组件都单独放置在以组件名命名的文件夹中。这种组织方式便于组件的发现、引用和管理，同时也方便了对组件相关资源（如样式、脚本、子组件等）的集中管理。
  • 组件入口：每个组件文件夹中包含一个名为 index.vue 的文件，作为组件的主入口。采用 index.vue 命名约定，简化了组件引用路径，使得组件的导入更加直观、方便。组件文件夹的命名直接决定了组件的名称，这一一致性原则有助于维持命名的规范性和可预测性。
  • 自动注册：应用级公共组件配置为自动引入。这样，开发者在使用这些组件时不再需要手动导入每个组件，从而实现“即用即得”的效果

局部组件 ​

局部组件没有提供专门的存放目录，我们建议采用就近原则，你可以在每个模块的文件夹下，建立一个 components 文件夹专门用于存放局部组件。

业务组件库 0.0.1-beta.1 ​

为了进一步提升开发效率并避免在业务开发中重复造轮子，我们计划推出一个专门针对业务常见需求设计的业务组件库。该组件库将以 npm 包的形式发布，支持通过 pnpm 进行安装和使用，从而为项目提供一套标准化、高效的业务组件解决方案。

与项目级和应用级公共组件不同，后两者主要以源码共享的形式存在，旨在为开发团队提供可自定义修改的灵活性。虽然这种方式增加了项目和应用的自适应性，但相对地，也牺牲了一定的维护性和标准化程度。相比之下，业务组件库注重提供一套经过精心封装和统一维护的组件集合。这套组件库由技术基础架构团队负责持续维护，确保其稳定性、可靠性和向后兼容性，从而让业务开发团队能够专注于业务逻辑的实现，无需担心组件的底层实现和维护问题。

通过引入这样一个业务组件库，我们旨在构建一个既能保证开发效率，又能保持代码质量和项目可维护性的开发生态。这不仅能减少开发过程中的重复劳动，也有助于提升整个项目团队的工作效率和协同能力。

composable ​

描述

在现代前端架构中，composable 是 Vue 3 Composition API的一部分，提供了一种新的组织和重用逻辑的方法，在名称上你可能会更熟悉 react hooks，其实他们就是不同的叫法而已，我们遵循 Vue 的名称统一称之为 composable。

与组件类似，composable 也可以根据其使用范围和目的被分为项目级和应用级。

这里只展示组合函数的存放位置和导出方式，具体的描述请查看 composable 介绍。

项目级 beta ​

项目级 composable 是指那些跨越整个项目、可在多个应用或功能模块中共享使用的逻辑单元。这些 composable通常封装了一些通用的逻辑，旨在提供一套通用的逻辑解决方案，以提高代码的复用率和一致性。

  • 模块化：通常以模块的形式存在于项目的公共目录下，如 packages/composables/TestDemo，便于管理和引用。
  • 统一前缀：为标识清晰这是项目级公共组件，所有组件的文件名都以 usePub 开头。这一命名规范有助于开发者快速识别组合函数的作用域和适用范围。
  • 自动注册：为了进一步优化开发体验，在项目构建过程中将被自动注册到全局。这意味着，在项目的任何地方使用这些函数时，开发者无需进行手动引入，从而实现了“零配置”使用。
  • 高复用性：它们解决的是项目范围内的通用问题，因此具有高度的复用潜力。
  • 独立性：为了确保高度的复用性，项目级 composable 应当尽量保持独立，避免依赖特定的业务逻辑或组件。
ts
// packages/composables/src/TestDemo/index.ts
// 取名需要以 usePub开头,会被vite自动抓取，导入apps/*

export function usePubTestDemo1() {
  console.log('usePubTestDemo1')
}
export function usePubTestDemo2() {
  console.log('usePubTestDemo2')
}
ts
// packages/composables/src/index.ts
export * from './TestDemo'

应用级 ​

描述

应用级 composable 则更加专注于特定应用内的逻辑需求。它们可能是对项目级 composable 的进一步封装，或者是特定于某个应用的业务逻辑实现。

应用级的规范就松散很多，只要你放置在 src/composables 目录下，都可以认为是应用级 composable，而且不要求统一的前缀。

指令 ​

描述

在 Vue 中，指令 directives 提供了一种方式来扩展HTML，允许你在DOM元素上附加特殊的行为。与 components 和 composable 类似，指令也可以根据其作用域和用途被分为项目级和应用级。

这里只展示指令的存放位置和导出方式，具体的指令描述请查看 directive 介绍。

项目级 beta ​

项目级指令是那些跨越整个项目、可被多个应用或功能模块共享的指令。这些指令通常封装了通用的DOM操作或行为逻辑，例如，自动聚焦、复制到剪贴板、懒加载图片、图片缩放等。由于它们解决的是通用问题，项目级指令具有以下特点：

  • 广泛适用性：设计用来解决项目中广泛存在的问题，使得它们在不同的应用和组件中都有潜在的使用场景。
  • 独立性：项目级指令应当尽可能地独立，不依赖于特定的业务逻辑或外部状态，以保持其高度的复用性。
  • 模块化：它们通常被组织在项目的公共目录下 packages/directives/，方便统一管理和自动注册。
  • 统一前缀：为标识清晰这是项目级 directive 和自动引入，所有的指令导出应当以 Pub 为前缀，例如 PubFocus、PubCopy、PubLazyLoad 等。

项目级指令应当尽可能编写 ObjectDirective 类型

ObjectDirective 类型是vue3的指令类型

ts
export interface ObjectDirective<T = any, V = any> {
  created?: DirectiveHook<T, null, V>
  beforeMount?: DirectiveHook<T, null, V>
  mounted?: DirectiveHook<T, null, V>
  beforeUpdate?: DirectiveHook<T, VNode<any, T>, V>
  updated?: DirectiveHook<T, VNode<any, T>, V>
  beforeUnmount?: DirectiveHook<T, null, V>
  unmounted?: DirectiveHook<T, null, V>
  getSSRProps?: SSRDirectiveHook
  deep?: boolean
}
ts
// packages/directives/src/ZoomAble/index.ts
import type { ObjectDirective } from 'vue'
import mediumZoom from 'medium-zoom'

const zoomable: ObjectDirective = {
  mounted: (el) => {
    mediumZoom(el, {
      background: 'rgba(0, 0, 0, 0.5)',
      scrollOffset: 0,
      margin: 80,
    })
  },
}

export { zoomable }
ts
// packages/directives/src/index.ts
export { zoomable as PubZoomable } from './ZoomAble'

应用级 ​

应用级指令则更加专注于特定应用的需求，解决该应用内部特有的问题。例如，应用级指令可能涉及特定表单验证逻辑、特殊的交互效果、鉴权等，它们的特征包括：

  • 特定性：这类指令通常为了特定应用的特定需求而设计，含有更多的业务逻辑和应用场景特定的行为。
  • 灵活性：考虑到紧密关联特定应用的特定需求，这些指令在设计时可以更灵活，更贴合具体的业务逻辑。
  • 定制化：应用级指令往往需要根据应用的具体需求进行定制开发和调整，以实现特定的功能或效果。

提示

应用级 directive 并没有做自动引入，因为创建频率和使用评率并不高，所以目前采用手动注册的方式

在 src/directive/index.ts 中引入并导出应用级指令, setupGlobDirectives 会在 main.ts 中全局注册

ts
import type { App } from 'vue'
import { setupPermissionDirective } from './plugins/permission'
import { setupWaves } from './plugins/waves'
import { setupTimeago } from './plugins/timeago'

export function setupGlobDirectives(app: App) {
  setupPermissionDirective(app)
  setupWaves(app)
  setupTimeago(app)
}