快速开始 ​

本节介绍如何在项目中引入并使用 DHdesign 组件库。

移动端（dh-design-mobile） ​

组件级引入 ​

推荐按组件引入，在入口文件里显式注册需要的组件：

ts
import { createApp } from 'vue'
import App from './App.vue'
import { Button } from '@szhn/dh-design-mobile'
import '@szhn/dh-design-mobile/styles/button.css'

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

注册后，在模板中通过 van- 前缀标签使用（与 Vant 一致）：

vue
<template>
  <van-button type="primary">主要按钮</van-button>
</template>

PC 端（dh-design-pc） ​

组件级引入 ​

ts
import { createApp } from 'vue'
import App from './App.vue'
import { ElButton } from '@szhn/dh-design-pc'
import '@szhn/dh-design-pc/styles/button.css'

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

注册后，在模板中通过 el- 前缀标签使用（与 Element Plus 一致）：

vue
<template>
  <el-button type="primary">主要按钮</el-button>
</template>

只使用少量组件时，推荐引入对应的 styles/组件名.css。如果项目全量注册组件，可以继续引入 style.css。

自动按需引入（推荐） ​

配合 unplugin-vue-components，模板里直接写 <el-button>、<dh-pro-table>，组件和对应样式会在构建时自动按需引入，不需要手动 app.use 和 import CSS：

ts
// vite.config.ts
import Components from 'unplugin-vue-components/vite'
import { DhDesignPcResolver } from '@szhn/dh-design-pc/resolver'

export default defineConfig({
  plugins: [
    vue(),
    Components({ resolvers: [DhDesignPcResolver()] }),
  ],
})

自动引入只处理模板中的组件。ElMessage、ElMessageBox 等函数式调用仍需从 @szhn/dh-design-pc 显式引入，并引入对应的 styles/message.css。

提示

不要同时使用 Element Plus 官方的 ElementPlusResolver，否则会绕过 DHdesign 的样式覆盖。

PC 和移动端同时全量注册时，页面布局组件分别使用 dh-pc-page-grid、dh-pc-page-layout 和 dh-mobile-page-grid，避免同名标签互相覆盖。旧的 dh-page-grid 标签仍可用，但只会由先注册的组件库接管。

图标按需引入 ​

推荐：具名引入。 图标是固定的时（绝大多数场景），直接引入图标组件，最终产物只包含用到的图标：

vue
<script setup lang="ts">
import { Delete, EditPen } from '@szhn/dh-design-icons'
</script>

<template>
  <Delete />
  <EditPen :size="16" color="var(--dh-color-primary)" />
</template>

具名图标也可以直接传给 Element Plus 的 icon 属性，例如 <el-button :icon="Delete" />。

按名称动态加载。 只有图标名称来自接口、配置等、运行时才能确定时，才使用 name 属性：

vue
<script setup lang="ts">
import { DhIcon } from '@szhn/dh-design-icons/component'
</script>

<template>
  <DhIcon :name="menu.icon" />
</template>

注意

动态加载只在用到时下载图标内容，但打包工具无法预知会用到哪些名称，会为全部约 1700 个图标各生成一个 chunk，构建产物文件数和构建时间都会明显增加。固定图标请始终使用具名引入。

只有图标选择器和文档页可以引入 @szhn/dh-design-icons/catalog，业务页不要引入完整图标目录。

TypeScript 支持 ​

两个包均内置 .d.ts 类型声明文件，开箱即用，无需额外配置。

PC 端通过 app.use(DhDesignPc) 全量注册组件时，在 tsconfig.json 中加入全局组件类型，模板里的 <el-button>、<dh-pro-table> 等标签即可获得属性提示和类型检查：

json
{
  "compilerOptions": {
    "types": ["@szhn/dh-design-pc/global"]
  }
}

使用上面的自动按需引入时，unplugin-vue-components 会自动生成 components.d.ts，无需再配置该项。移动端的全局类型入口尚未提供，推荐在页面中显式导入使用到的组件。

主题色 ​

业务系统只需要在入口处设置一次主题色：

ts
import { applyDhDesignTheme } from '@szhn/dh-design-mobile'

applyDhDesignTheme({ colorPrimary: '#075AED' })
ts
import { applyDhDesignPcTheme } from '@szhn/dh-design-pc'

applyDhDesignPcTheme({ colorPrimary: '#075AED' })

移动端会自动转换成 Vant 需要的变量，PC 端会自动转换成 Element Plus 需要的变量。更多说明见 主题管理。

Vue2 老项目 ​

Vue2 项目使用独立兼容包：

  • 移动端：@szhn/dh-design-mobile-vue2
  • PC 端：@szhn/dh-design-pc-vue2

组件标签仍沿用 van- / el- 前缀。更多说明见 Vue2 老项目接入。