dj 组件库

ui_dj 是一个基于 Vue 3 + Vite 8 + UnoCSS + sass-embedded 构建的业务组件库。当前仓库主要包含基础 UI 组件和 PDF 编辑/生成能力。

当前包名：ui_dj
当前版本：6.0.3
Vue 版本要求：vue >= 3.5.30

特性

• 支持 Vue 3 组件库全局安装和按需引入。
• 内置 UnoCSS 样式，构建产物提供样式文件。
• 提供 SVG 图标组件 DjSvg。
• 提供 PDF 编辑器组件 DjDoPdf，可编辑工程 Schema、预览、下载、打开和打印 PDF。
• 提供 PDF 工具函数，可直接通过 Schema 和模板数据生成 PDF Blob 或预览地址。
• 支持字体 URL 或完整 pdfmake 字体映射配置。
• 提供 TypeScript 类型声明。

安装

pnpm add ui_dj

说明：早期历史版本曾包含独立打印功能；当前新版本已经移除旧打印功能，组件库主要保留 PDF 编辑和生成能力。如果项目仍依赖早期打印功能，请安装对应的历史旧版本。

Peer Dependencies

项目依赖以下 peer dependencies，宿主项目需要保证已安装或可解析：

pnpm add vue tools_dj pdfmake

版本要求参考：

| 依赖 | 要求 | | --- | --- | | vue | >=3.5.30 | | tools_dj | >=1.0.94 | | pdfmake | >=0.3.0 |

样式引入

组件库导出了样式文件，宿主项目建议优先使用当前可确认的兼容路径：

import 'ui_dj/lib/index.css'

package.json 也声明了 style.css 导出，但它依赖发布产物中存在 lib/style.css。如果你安装的版本确认包含该文件，也可以使用：

import 'ui_dj/style.css'

快速开始

全局注册

import { createApp } from 'vue'
import App from './App.vue'
import MukUI from 'ui_dj'
import 'ui_dj/lib/index.css'

const app = createApp(App)

app.use(MukUI)
app.mount('#app')

全局注册后，组件名称由 Dj 前缀和组件内部名称组成，当前可用组件包括：

<template>
  <DjSvg name="home" class="text-xl" color="#1677ff" />
  <DjButton type="primary" />
</template>

按需引入

<script setup lang="ts">
import { DjSvg, DjButton } from 'ui_dj'
import 'ui_dj/lib/index.css'
</script>

<template>
  <DjSvg name="search" class="text-base" color="currentColor" />
  <DjButton type="primary" />
</template>

组件清单

| 组件 | 引入方式 | 说明 | | --- | --- | --- | | DjSvg | import { DjSvg } from 'ui_dj' | SVG 图标组件，通过 <use> 引用 symbol。 | | DjButton | import { DjButton } from 'ui_dj' | 基础按钮/测试组件，当前仍偏示例性质。 | | DjDoPdf | import { DjDoPdf } from 'ui_dj/doPdf' | PDF 编辑器组件，提供 Schema 编辑、预览、导出、PDF 生成后打印能力。 |

DjDoPdf 使用独立入口 ui_dj/doPdf 导出，不随默认 MukUI install 全局注册。

DjSvg

DjSvg 用于渲染 SVG symbol 图标。

Props

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | name | string | '' | 图标名称，最终会拼接为 #icon-${name}。 | | color | string | currentColor | 图标颜色，会传给 <use> 的 fill。 | | size | number \| string | 继承字号 | 图标宽高。不传时为 1em，继承主项目或父级字号；传入后会生成运行时内联样式，不经过 postcss-pxtorem。 |

DjSvg 不读取全局 rootValue。移动端项目需要单位转换时不要使用 size，推荐不传 size，通过主项目 UnoCSS/CSS 字号控制；只有已经明确传入 rem、em 等最终单位时才使用 size。

示例

<script setup lang="ts">
import { DjSvg } from 'ui_dj'
</script>

<template>
  <DjSvg name="user" class="text-xl" color="#333" />
</template>

渲染后的引用地址为：

<use xlink:href="#icon-user" />

因此宿主项目需要提前注入或加载对应的 SVG symbol。

强制设置颜色

如果需要通过父组件样式强制覆盖图标颜色，可以使用 :deep：

:deep(.c-icon use) {
  fill: $themeBgColor;
}

DjButton

DjButton 当前是一个基础示例组件，支持传入 type 并在组件内部展示。

<script setup lang="ts">
import { DjButton } from 'ui_dj'
</script>

<template>
  <DjButton type="primary" />
</template>

注意：该组件当前代码中仍包含调试展示和 console 输出，更适合作为组件库基础示例或后续扩展入口。

DjDoPdf

DjDoPdf 是基于 pdfmake 的 PDF 编辑器组件。它支持在页面中编辑文档结构、查看编译后的 docDefinition 和 runtimeConfig，并对外暴露导出、导入、预览、下载、打开和打印等方法。

这里的“打印”指 PDF 生成后的浏览器打印能力，即 printPdf / print()；不是早期历史版本中的独立打印模块。当前新版本已经移除旧打印功能，主要保留 PDF 编辑和生成能力。

为什么 DjDoPdf 强大

DjDoPdf 不只是一个“点击下载 PDF”的封装，而是一套可以嵌入业务系统的 PDF 可视化编辑和生成方案。它把 pdfmake 的复杂配置抽象成可编辑的工程 Schema，同时保留底层 docDefinition 和运行时配置的导出能力，既适合页面端低代码编辑，也适合业务系统保存模板后按数据生成 PDF。

核心优势包括：

• 可视化编辑：内置画布区、文档设置区、节点检查器和预览区，用户可以直接编辑文本、列表、表格、图片、SVG、二维码、分栏、堆叠、目录等 PDF 内容节点。
• Schema 驱动：所有编辑结果都可以导出为当前版本的 EditorSchema，便于保存到数据库、接口下发、宿主侧版本管理和再次导入编辑。
• 运行时编译：可随时把工程 Schema 编译成 pdfmake 可识别的 docDefinition 与 runtimeConfig，方便接入现有 PDF 生成链路。
• 模板数据填充：支持 {{user.name}} 这类路径变量，也支持列表和表格等数组数据解析，适合合同、报价单、出库单、报表、证书等动态文档。
• 完整输出链路：同一份工程既可以生成预览 URL，也可以生成 Blob，还可以直接下载、打开新标签页或打印。
• 中文字体友好：支持 fontUrl + fontFileName 快速配置字体，也支持传入完整 fontConfig，解决中文 PDF 常见的乱码、缺字问题。
• 组件和工具函数两种用法：需要可视化编辑时使用 DjDoPdf 组件；只需要根据模板和数据生成 PDF 时，直接使用 createPreviewUrlFromSchemaAndData、createPdfBlobFromSchemaAndData 等工具函数。
• 适合业务系统集成：外层系统可以通过 ref 获取 Schema、导入 Schema、监听 change、接管预览地址、上传 Blob 或把编译产物交给服务端处理。

典型使用场景：

| 场景 | 能力 | | --- | --- | | 合同/协议模板 | 可视化维护固定版式，通过模板变量填充客户、金额、日期等数据。 | | 报价单/订单/出库单 | 表格数据可由业务数组动态生成，适合多行明细。 | | 报表导出 | 支持标题、段落、表格、图片、页眉页脚等组合内容。 | | 证书/凭证 | 可配置字体、字号、颜色、图片和 SVG 内容。 | | 低代码平台 | Schema 可保存、导入、复制、回滚，适合作为模板设计器嵌入。 |

一句话概括：DjDoPdf 负责把“复杂的 PDF 代码配置”变成“可编辑、可保存、可复用、可动态填充数据的 PDF 模板工程”。

安装依赖

使用 PDF 能力时，请确保安装了 pdfmake：

pnpm add pdfmake

引入方式

DjDoPdf 使用独立入口导出：

<script setup lang="ts">
import { ref } from 'vue'
import { DjDoPdf } from 'ui_dj/doPdf'
import type { PdfmakeEditorExposed } from 'ui_dj/doPdf'
import 'ui_dj/lib/index.css'

const editorRef = ref<PdfmakeEditorExposed | null>(null)
</script>

<template>
  <DjDoPdf ref="editorRef" />
</template>

Props

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | insertFeatures | string[] | [] | 可插入节点能力配置，传给顶部工具栏。 | | showToolbar | boolean | true | 是否显示顶部工具栏。 | | fontUrl | string | '' | 字体 URL 前缀，例如 https://cdn.example.com/fonts/。 | | fontFileName | string | '' | 字体文件名，例如 KaiTI_GB2312.ttf。 | | fontFamily | string | 'Roboto' | 注册到 pdfmake 的字体名称。 | | fontConfig | PdfFontMap | {} | 完整字体映射，优先级高于 fontUrl + fontFileName。 |

字体配置示例

使用字体 URL

<template>
  <DjDoPdf
    ref="editorRef"
    font-url="https://cdn.example.com/fonts/"
    font-file-name="KaiTI_GB2312.ttf"
    font-family="KaiTi"
  />
</template>

组件会自动生成 pdfmake 字体映射，并把默认字体设置为 fontFamily。

使用完整字体映射

const fontConfig = {
  KaiTi: {
    normal: 'https://cdn.example.com/fonts/KaiTI_GB2312.ttf',
    bold: 'https://cdn.example.com/fonts/KaiTI_GB2312.ttf',
    italics: 'https://cdn.example.com/fonts/KaiTI_GB2312.ttf',
    bolditalics: 'https://cdn.example.com/fonts/KaiTI_GB2312.ttf',
  },
}

<template>
  <DjDoPdf :font-config="fontConfig" font-family="KaiTi" />
</template>

Events

| 事件 | 参数 | 说明 | | --- | --- | --- | | change | EditorSchema | 工程 Schema 变化时触发。 |

<template>
  <DjDoPdf @change="handleSchemaChange" />
</template>

import type { EditorSchema } from 'ui_dj/doPdf'

function handleSchemaChange(schema: EditorSchema) {
  console.log(schema)
}

Expose 方法

通过 ref 可以调用以下方法：

| 方法 | 返回值 | 说明 | | --- | --- | --- | | addBlock(type) | void | 添加指定类型节点。 | | selectBlock(id) | void | 选中节点。 | | removeBlock(id) | void | 删除节点。 | | moveBlock(id, offset) | void | 移动节点。 | | duplicateBlock(id) | void | 复制节点。 | | reset() | void | 重置为初始工程。 | | download(filename?) | void | 下载当前 PDF。 | | open() | void | 新标签打开当前 PDF。 | | print() | void | 打印当前 PDF。 | | getSchema() | EditorSchema | 获取当前工程 Schema。 | | getSchemaJson(space?) | string | 获取格式化后的工程 Schema JSON。 | | setSchema(schemaOrJsonText) | void | 导入工程 Schema，支持对象或 JSON 字符串。 | | getDocDefinition() | Record<string, any> | 获取当前 pdfmake docDefinition。 | | getDocDefinitionJson(space?) | string | 获取格式化后的 docDefinition JSON。 | | getRuntimeConfig() | PdfRuntimeConfig | 获取当前运行时配置。 | | getRuntimeConfigJson(space?) | string | 获取格式化后的运行时配置 JSON。 | | getCompiled() | CompiledResult | 一次性获取 docDefinition 和 runtimeConfig。 | | getPreviewUrl() | Promise<string> | 生成当前工程的 PDF 预览地址。 | | getPdfBlob() | Promise<Blob> | 生成当前工程的 PDF Blob。 |

外层页面调用示例

<script setup lang="ts">
import { ref } from 'vue'
import { DjDoPdf } from 'ui_dj/doPdf'
import type { PdfmakeEditorExposed } from 'ui_dj/doPdf'

const editorRef = ref<PdfmakeEditorExposed | null>(null)

function downloadPdf() {
  editorRef.value?.download('demo.pdf')
}

function exportSchema() {
  const schema = editorRef.value?.getSchemaJson()
  console.log(schema)
}
</script>

<template>
  <DjDoPdf ref="editorRef" />
  <button @click="downloadPdf">下载 PDF</button>
  <button @click="exportSchema">导出工程 JSON</button>
</template>

PDF 工具函数

ui_dj/doPdf 同时导出了一组工具函数，适合不渲染编辑器组件、只基于 Schema 生成 PDF 的场景。

常用导出

import {
  createPdfBlob,
  createPdfBlobUrl,
  createUrlFontMap,
  downloadPdf,
  openPdf,
  printPdf,
  compileSchemaToPdf,
  createPdfBlobFromSchema,
  createPreviewUrlFromSchema,
  createPdfBlobFromSchemaAndData,
  createPreviewUrlFromSchemaAndData,
} from 'ui_dj/doPdf'

使用 Schema 和模板数据生成预览

import { createPreviewUrlFromSchemaAndData } from 'ui_dj/doPdf'

const schema = editorRef.value?.getSchema()
const runtimeConfig = editorRef.value?.getRuntimeConfig()

if (!schema) return

const templateData = {
  user: {
    name: '张三',
    phone: '13800000000',
  },
  table: [
    { name: '苹果', count: '2箱' },
    { name: '香蕉', count: '3箱' },
  ],
}

const previewUrl = await createPreviewUrlFromSchemaAndData(schema, templateData, {
  fontConfig: runtimeConfig?.fonts,
})

然后可以把 previewUrl 挂载到 iframe：

<template>
  <iframe :src="previewUrl" class="h-full w-full border-0"></iframe>
</template>

使用 URL.createObjectURL 生成的地址，在不再使用时建议调用 URL.revokeObjectURL(previewUrl) 释放资源。

模板语法

PDF 编辑器支持在文本、列表、表格等内容中使用模板变量。变量会根据传入的模板数据进行解析。

基础字段

{{user.name}}
{{user.phone}}

对应数据：

const templateData = {
  user: {
    name: '张三',
    phone: '13800000000',
  },
}

数组数据

表格或列表中可以使用数组数据，例如：

const templateData = {
  table: [
    { name: '苹果', count: '2箱' },
    { name: '香蕉', count: '3箱' },
    { name: '橙子', count: '1箱' },
  ],
}

在表格节点中可通过对应字段映射生成多行内容。

数组模板建议保持单一数据源：列表项和表格模板行更适合绑定一个数组数据源，复杂嵌套数组建议在业务侧先整理成适合渲染的数据结构。

类型导出

ui_dj/doPdf 导出以下常用类型：

import type {
  EditorSchema,
  EditorBlock,
  PdfFontMap,
  PdfRuntimeConfig,
  PdfmakeEditorProps,
  PdfmakeEditorExposed,
  CompiledResult,
  SchemaPdfBuildOptions,
  SchemaTemplateBuildOptions,
  HeaderFooterVisualConfig,
  HeaderFooterPosition,
  TemplateToken,
  TemplateArrayContext,
  TemplateScanResult,
} from 'ui_dj/doPdf'

本地开发

安装依赖

pnpm install

启动开发服务

pnpm dev

开发服务默认端口为 5133。

构建

pnpm build

构建产物输出到 lib 目录，入口包括：

| 入口 | 说明 | | --- | --- | | lib/index.mjs | 主组件库入口。 | | lib/doPdf.mjs | PDF 编辑器和 PDF 工具函数入口。 | | lib/ui_dj.css | 当前构建样式文件。 | | lib/index.d.ts | 主入口类型声明。 | | lib/doPdf.d.ts | package.json 声明的 PDF 入口类型文件；如果当前构建产物未生成该文件，请以实际 lib/doPdf/** 类型产物为准。 |

本地发布调试

pnpm lcalPub

该命令会执行构建并通过 yalc push 推送到本地 yalc 仓库。

正式发布

pnpm proPub

该命令会构建、更新 patch 版本号并执行 npm publish。

常见问题

为什么 SVG 图标不显示？

DjSvg 只负责渲染：

<use xlink:href="#icon-xxx" />

宿主项目需要自行加载 SVG symbol，例如通过 iconfont、svg-sprite 或其他构建插件注入。

为什么图标颜色没有生效？

默认颜色来自 color 属性，并传给 <use> 的 fill。如果外层样式优先级更高，可能需要使用：

:deep(.c-icon use) {
  fill: #1677ff;
}

为什么 PDF 中文显示异常？

pdfmake 默认字体可能不包含中文字符。请通过 fontUrl + fontFileName + fontFamily 或 fontConfig 配置支持中文的字体。

当前版本还有旧打印功能吗？

当前新版本已经移除早期独立打印功能，主要保留 PDF 编辑和生成能力。如果项目仍需要早期打印功能，请安装对应的历史旧版本。

兼容说明

• 当前库面向 Vue 3 项目。
• PDF 能力依赖 pdfmake。
• 部分工具能力依赖 tools_dj。
• 样式优先使用 UnoCSS，宿主项目一般只需要引入构建后的样式文件。