sun-card-design

Sun Card Design

一个用于卡片设计预览的 Vue 3 组件库，支持 PC 与移动端渲染，提供完整样式与多种基础/表单/图表/媒体组件的预览。

低代码卡片介绍

• sun-card-designer 设计器库
• sun-card-design 预览库

特性

• 🎯 PC 与移动端双入口：按需引入 pc、mobile 渲染面板
• 🎨 自带样式：提供 sun-card-design/style.css 一次性引入
• 🧩 组件丰富：文本、图片、音视频、表单控件、网格、图表等

安装

npm install sun-card-design

必备依赖（在你的项目中安装）

# Vue 生态基础
npm i vue@^3.5.0 vue-router@^4 pinia@^3 ant-design-vue@^4

# 设计器库（若使用 sun-card-designer 整包插件）
npm i sun-card-design

快速开始

方式一：按平台引入（推荐）

// 样式（必需）
import 'sun-card-design/style.css'

// 按平台引入渲染面板
import PcPanel from 'sun-card-design/pc'
import MobilePanel from 'sun-card-design/mobile'

// Vue 组件中使用
export default {
  components: { PcPanel, MobilePanel }
}

适合在不同容器中分别渲染 PC 与移动端界面，按需加载更轻量。

方式二：从根入口具名导入（需要打包器支持 ESM Tree-Shaking）

import 'sun-card-design/style.css'
import { PcPanel, MobilePanel } from 'sun-card-design'

根入口导出多个组件，便于二次开发与按需组合；实际打包体积取决于你的打包器摇树优化效果。

组件概览（部分）

• 渲染面板：PcPanel、MobilePanel
• 基础组件：Title、Text、Button、Picture、File、Video、Audio、Rate、Tag、Divider、Panorama、GenerateImg
• 布局组件：Grid
• 表单组件：Input、Select、EnterpriseSearch、Table
• 图表组件：BarChart、BarChart3D、PieChart、PieChart3D、LineChart

具体 props/事件请参考源码组件文件，后续会补充详细文档示例。

使用示例（片段）

<template>
  <div class="container">
    <div class="pc-wrap">
      <PcPanel
        :config="toolConfig"
        :record="record"
        @clickEvent="handleClickEvent"
        @fileUpdateEvent="handleFileUpdate"
        @clickColumnsEvent="handleClickColumns"
        @clickLinkEvent="handleClickLink"
        @uploadEvent="handleUpload"
      />
    </div>
    <div class="mb-wrap">
      <MobilePanel
        :config="toolConfig"
        :record="record"
        @clickEvent="handleClickEvent"
        @fileUpdateEvent="handleFileUpdate"
        @clickColumnsEvent="handleClickColumns"
        @clickLinkEvent="handleClickLink"
        @uploadEvent="handleUpload"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import 'sun-card-design/style.css'
import PcPanel from 'sun-card-design/pc'
import MobilePanel from 'sun-card-design/mobile'

const record = ref({
  id: 'card',
  type: 'card',
  config: {
    background: '#fff',
    borderRadius: 12
  },
  lits: []
})
const toolConfig = ref({
  variableList: [
    {
      id: '1',
      name: '字符串-Test1',
      type: 'String',
      defaultValue: '测试'
    },
    {
      id: '2',
      name: '数组-Test1',
      type: 'Array',
      defaultValue: JSON.stringify([1, 2, 3])
    }
  ]
})

// 组件点击
const handleClickEvent = (record) => {
  console.log('clickEvent', record)
}

// 布局区域点击
const handleClickColumns = (record) => {
  console.log('clickColumnsEvent', record)
}

// 文件组件内容更新
const handleFileUpdate = (record) => {
  console.log('fileUpdateEvent', record)
}

// 文件链接点击
const handleClickLink = (link) => {
  console.log('clickLinkEvent', link)
}

// 文件上传点击（上传由宿主应用实现）
const handleUpload = ({ url, callBack }) => {
  console.log('uploadEvent url', url)

  // 在这里发起实际的上传请求，拿到文件列表 list[]
  // 假设上传完成后得到 filesList 数组：
  const filesList = [] // TODO: 替换为真实上传返回的 list[]

  // 上传完成后，通过 callBack 把文件列表回传给 card 预览组件
  callBack(filesList)
}
</script>

事件 API

渲染面板组件（PcPanel、MobilePanel）会向外抛出一系列交互事件，便于在宿主应用中统一处理业务逻辑：

• clickEvent：组件点击事件

  • 触发场景：卡片内可点击基础组件（如按钮、图片、文件组件等）被用户点击时触发
  • 回调签名：(record) => void
  • 参数说明：record 为当前被点击组件的配置数据

• fileUpdateEvent：文件组件内部文件列表更新事件

  • 触发场景：在文件组件中执行“更新文件”等操作时触发
  • 回调签名：(record) => void
  • 参数说明：record 为当前文件组件的配置数据

• clickColumnsEvent：布局区域（Grid 等）点击事件

  • 触发场景：开启了点击行为的布局列/区域被点击时触发
  • 回调签名：(record) => void
  • 参数说明：record 为当前被点击的布局列配置

• clickLinkEvent：文件链接点击事件

  • 触发场景：文件组件中的链接被点击时触发
  • 回调签名：(link: string) => void
  • 参数说明：link 为当前文件的链接地址

• uploadEvent：文件上传点击事件

  • 触发场景：文件组件中点击“上传”入口时触发
  • 回调签名：(payload) => void
  • 参数结构：payload 为一个对象：{ url, callBack }
    • url：上传接口地址，类型为 string
    • callBack：上传完成后的回调函数，签名为 (files: any[]) => void，其中 files 为上传返回的文件列表 list[]；宿主应用在完成上传并拿到文件列表后，需要调用该回调将数据回传给预览面板

建议在业务代码中统一封装这些事件的处理逻辑，以便在不同卡片、不同终端（PC/Mobile）之间复用。

外部依赖与对等依赖

本库将以下依赖标记为 external/peer，不会被打入产物，请在宿主项目中自行安装与提供：

• 对等依赖（必装）
  • vue ^3.5.0
  • ant-design-vue ^4.0.0

兼容性

• 运行环境：现代浏览器 / Vite、Webpack 等现代打包器
• 模块格式：ESM（推荐）、UMD（可选，默认没有，减小体积）

许可证

MIT

作者

js-feng@foxmail.com