@xmdrizzol/drizzol-ui

Drizzol UI

Vue 3 组件库 —— 组件、工具函数、样式体系的统一基准。基于 @xmdrizzol/drizzol-ui，可作为个人/小型项目前端基建直接使用。

📦 npm · 🐙 GitHub · 🖥 在线演示 · 📖 贡献指南

• 组件全部 D 前缀（DButton → 模板 <d-button>）
• 样式全部走 --dz-* CSS 变量（深浅双主题 :root.dark）
• 工具函数（request 拦截器、theme、cookie、pxToRem 等）随包导出
• 提示/通知/确认/抽屉均为库内自研，不依赖任何第三方 UI 库

安装

npm i @xmdrizzol/drizzol-ui vue

vue 为 peerDependency（宿主自行安装；vue-router 可选）。

快速开始

// main.ts
import { createApp } from 'vue'
import DrizzolUi from '@xmdrizzol/drizzol-ui'
import '@xmdrizzol/drizzol-ui/style.css'

const app = createApp(App)
app.use(DrizzolUi) // 全量注册 d-* 组件
app.mount('#app')

<!-- App.vue：根节点渲染一次雪碧图即可 -->
<template>
  <d-icon-sprite />
  <d-card is-hover>
    <d-button type="primary" icon="add">新增</d-button>
  </d-card>
</template>

也可以按需具名导入（配合 tree-shaking）：

import { DCard, DButton, message, applyTheme } from '@xmdrizzol/drizzol-ui'

组件清单

工具函数（import { ... } from '@xmdrizzol/drizzol-ui'）

请求配置示例

import { configureRequest } from '@xmdrizzol/drizzol-ui'

configureRequest({
  baseURL: '/api',
  onUnauthorized: () => userStore.clear(), // 401 时清理宿主登录态
})

后端契约约定：响应 { code, msg, data } 包一层，code === 200 为成功；文件上传 POST /api/general/file/upload[/image]（字段 File + CustomCategory），访问 GET /api/general/file/access/{type}/{fileRef}。

库源码不内置任何后端地址——上传路径与访问前缀默认为空，文件地址完全由宿主声明。按上述契约使用时，在应用入口配置一次：

import { configureFileApi, configureFileAccessPrefix } from '@xmdrizzol/drizzol-ui'

// 上传接口路径（DUpload / DCropper 组件也可传 action，uploadFile / uploadImage 可传 url 覆盖）
configureFileApi({ uploadUrl: '/general/file/upload', uploadImageUrl: '/general/file/upload/image' })

// 文件访问前缀：fileRef（如 image/xxx.png 或裸存储文件名）按 `前缀 + type/fileRef` 拼接
configureFileAccessPrefix('/api/general/file/access/')

图片类组件（DImage / DAvatar / DUpload 预览）的 src 语义：http(s) / blob: / data: 开头的完整地址与 / 开头的同源相对路径（如 /uploads/xxx.png）原样使用；其余视为 fileRef——已配置前缀时按 前缀 + type/fileRef 拼接，未配置时原样返回。拼接规则不满足后端约定时，configureFileAccessResolver(src => ...) 可完全接管 src → URL 的解析（优先于前缀配置，传 undefined 恢复内置规则）。

样式与主题

• 组件 CSS 随包导出于 dist/style.css（已含 --dz-* 变量定义与基础排版：h1~h6/p/code/pre/kbd 字号阶梯与边距），保持 px 单位——pxtorem 等转换属宿主项目决策
• 主题切换：<html> 挂 dark class（applyTheme 三态：auto/light/dark，localStorage 持久化）
• 自定义品牌色：改 _variables.scss 的 $light-primary-* / $dark-primary-* 两套 10 级色板重新编译（语义浅底三元组同源派生，自动同步），或直接在宿主覆盖 --dz-primary 等 CSS 变量（运行时覆盖需成对覆盖对应 -rgb 三元组，见「浏览器兼容性」）
• SCSS 源文件随包输出（@xmdrizzol/drizzol-ui/styles），@mixin prose 正文排版、mobile/flex 等 mixin 可被宿主 @use

@use '@xmdrizzol/drizzol-ui/styles/_mixin.scss' as *;
// vite 可选：与库一致的 additionalData 全局注入

浏览器兼容性（最低 Chrome 86）

产物基线为最低支持 Chrome 86：源码不使用高于该基线的 CSS 语法，构建声明 build.cssTarget: 'chrome86'（否则 Vite 8 默认目标会让压缩器产出旧内核无法解析的 inset、range 媒体查询等），并以 npm test 扫源码 + npm run build 末尾扫产物的双护栏防回归。

宿主自建构建同样要声明，否则打包时会把库产物重新压缩回现代语法、静默抵消兼容性：

// 宿主 vite.config.ts
export default defineConfig({
  build: { cssTarget: 'chrome86' }, // 与库保持一致
})

写法规范（四个模板 + 禁写清单 + 语义色成对维护）、修复记录与宿主侧清单详见 docs/browser-support.md。

贡献

欢迎 Issue 与 PR！提交前请阅读 CONTRIBUTING.md：

• Bug 报告请附版本、复现步骤与期望/实际行为（Issue 模板）
• PR 走 fork + 分支，不要直接 push main；提交遵循 Conventional Commits
• npm test / npm run typecheck 必须通过；发布物改动需附 changeset

许可与致谢

本库源码基于 MIT 许可开源。

• 内置图标来自 Lucide（ISC 许可），经 Iconify 拉取后内联
• 运行时依赖 axios / js-cookie / cropperjs / artplayer 均为 MIT
• 各依赖与图标的详细许可说明见在线文档「介绍」页