@me-framework/me-sku-editor 1.0.1

package/document//345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -0,0 +1,292 @@
+# 快速开始指南
+
+本指南将帮助你在 5 分钟内快速上手 SkuEditor 组件。
+
+## 目录
+
+- [环境准备](#环境准备)
+- [运行项目](#运行项目)
+- [最小化示例](#最小化示例)
+- [核心概念](#核心概念)
+- [下一步](#下一步)
+
+---
+
+## 环境准备
+
+### 必需条件
+
+- Node.js 16+
+- npm 或 pnpm
+
+### 安装依赖
+
+```bash
+# 使用 npm
+npm install
+
+# 或使用 pnpm（推荐）
+pnpm install
+```
+
+---
+
+## 运行项目
+
+### 启动开发服务器
+
+```bash
+npm run dev
+```
+
+项目将在 `http://localhost:5173` 启动。
+
+### 构建生产版本
+
+```bash
+npm run build
+```
+
+构建产物将输出到 `dist` 目录。
+
+---
+
+## 最小化示例
+
+### 示例 1：最简单的用法
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import SkuEditor from './components/sku/SkuEditor.vue'
+</script>
+
+<template>
+  <div class="app-container" style="padding: 20px;">
+    <h1>商品规格编辑器</h1>
+    <SkuEditor />
+  </div>
+</template>
+```
+
+这个示例使用组件的内部数据管理模式，无需任何配置即可使用。
+
+### 示例 2：带初始数据的用法
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+import { generateSkuData } from './composables/sku/useSkuGenerator'
+
+// 准备初始规格数据
+const specs = ref<Spec[]>([
+  {
+    id: 'spec-1',
+    name: '颜色',
+    type: 'color',
+    sort: 0,
+    attributes: [
+      { id: 'attr-1-1', name: '红色', color: '#ff0000', image: '', sort: 0, content: '' },
+      { id: 'attr-1-2', name: '蓝色', color: '#0000ff', image: '', sort: 1, content: '' },
+      { id: 'attr-1-3', name: '绿色', color: '#00ff00', image: '', sort: 2, content: '' }
+    ]
+  },
+  {
+    id: 'spec-2',
+    name: '尺码',
+    type: 'text',
+    sort: 1,
+    attributes: [
+      { id: 'attr-2-1', name: 'S', color: '', image: '', sort: 0, content: '' },
+      { id: 'attr-2-2', name: 'M', color: '', image: '', sort: 1, content: '' },
+      { id: 'attr-2-3', name: 'L', color: '', image: '', sort: 2, content: '' },
+      { id: 'attr-2-4', name: 'XL', color: '', image: '', sort: 3, content: '' }
+    ]
+  }
+])
+
+// 生成 SKU 数据
+const skuData = ref<SkuRow[]>(generateSkuData(specs.value))
+</script>
+
+<template>
+  <div class="app-container" style="padding: 20px;">
+    <h1>商品规格编辑器</h1>
+    <div style="margin-bottom: 16px;">
+      <span style="margin-right: 24px;">规格数：{{ specs.length }}</span>
+      <span>SKU数：{{ skuData.length }}</span>
+    </div>
+    <SkuEditor
+      v-model:specs="specs"
+      v-model:sku-data="skuData"
+    />
+  </div>
+</template>
+```
+
+### 示例 3：使用外部格式数据（推荐）
+
+使用 `spec_json` 格式的数据，这是推荐的存储和交互格式：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import SkuEditor from './components/sku/SkuEditor.vue'
+import type { Spec, SkuRow } from './types/sku'
+import { generateSkuData, toInternalFormat } from './composables/sku/useSkuGenerator'
+
+// 规格数据
+const specs = ref<Spec[]>([
+  {
+    id: 'spec-1',
+    name: '颜色',
+    type: 'color',
+    sort: 0,
+    attributes: [
+      { id: 'attr-1-1', name: '白色', color: '#ffffff', image: '', sort: 0, content: '' },
+      { id: 'attr-1-2', name: '黑色', color: '#000000', image: '', sort: 1, content: '' }
+    ]
+  },
+  {
+    id: 'spec-2',
+    name: '尺寸',
+    type: 'text',
+    sort: 1,
+    attributes: [
+      { id: 'attr-2-1', name: '小', color: '', image: '', sort: 0, content: '' },
+      { id: 'attr-2-2', name: '中', color: '', image: '', sort: 1, content: '' },
+      { id: 'attr-2-3', name: '大', color: '', image: '', sort: 2, content: '' }
+    ]
+  }
+])
+
+// 你的业务数据（使用规格名称和属性名称）
+const myData: SkuRow[] = [
+  {
+    spec_json: { '颜色': '白色', '尺寸': '小' },
+    skuNo: 'PROD-WHITE-S',
+    skuName: '产品-白色-小',
+    salePrice: 99,
+    marketPrice: 199,
+    status: 1
+  },
+  {
+    spec_json: { '颜色': '白色', '尺寸': '中' },
+    skuNo: 'PROD-WHITE-M',
+    skuName: '产品-白色-中',
+    salePrice: 109,
+    marketPrice: 199,
+    status: 1
+  }
+]
+
+// 转换并生成完整数据
+const existingData = toInternalFormat(myData, specs.value)
+const skuData = ref<SkuRow[]>(generateSkuData(specs.value, existingData))
+</script>
+
+<template>
+  <SkuEditor
+    v-model:specs="specs"
+    v-model:sku-data="skuData"
+  />
+</template>
+```
+
+---
+
+## 核心概念
+
+### 两种使用模式
+
+#### 1. 内部管理模式
+
+组件内部管理数据，适合简单场景：
+
+```vue
+<SkuEditor />
+```
+
+#### 2. 外部控制模式
+
+父组件控制数据，适合需要自定义处理的场景：
+
+```vue
+<SkuEditor
+  v-model:specs="specs"
+  v-model:sku-data="skuData"
+/>
+```
+
+### 数据结构关系
+
+```
+Spec（规格）
+  ├── id
+  ├── name（如"颜色"）
+  ├── type（'text' | 'color' | 'image'）
+  └── attributes[]
+        ├── SpecAttribute（属性）
+        │     ├── id
+        │     ├── name（如"红色"）
+        │     ├── color
+        │     ├── image
+        │     └── ...
+        └── ...
+
+SkuRow（SKU）
+  ├── id
+  ├── specs: { specId: attrId }（内部格式）
+  ├── spec_json: { specName: attrName }（外部格式，推荐）
+  ├── skuNo
+  ├── skuName
+  ├── salePrice
+  └── ...
+```
+
+### 规格类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `text` | 文字规格 | 尺码：S、M、L |
+| `color` | 颜色规格 | 颜色：红、蓝、绿 |
+| `image` | 图片规格 | 款式：图片1、图片2 |
+
+### 两种数据格式
+
+| 格式 | 字段名 | 说明 | 使用场景 |
+|------|--------|------|----------|
+| 外部格式 | `spec_json` | `{ '颜色': '红色', '尺码': 'S' }` | 存储、后端交互、用户界面 |
+| 内部格式 | `specs` | `{ 'spec-1': 'attr-1-1', 'spec-2': 'attr-2-1' }` | 组件内部计算、快速查找 |
+
+**推荐做法**：始终使用 `spec_json` 格式与组件交互，组件会自动处理转换。
+
+---
+
+## 下一步
+
+现在你已经了解了基本用法，可以：
+
+1. 查看完整的 [使用文档](./使用文档.md) 了解所有功能
+2. 了解 [开发指南](./开发指南.md) 进行二次开发
+3. 运行项目中的示例 `src/App.vue` 进行实践
+4. 尝试导出导入 Excel 文件体验数据交换功能
+5. 体验新增的数据校验功能
+
+---
+
+## 获取帮助
+
+如果在使用过程中遇到问题：
+
+1. 查看 [常见问题](./使用文档.md#常见问题) 章节
+2. 检查项目的 `README.md`
+3. 查看组件源码中的注释和类型定义
+4. 查看 `src/types/sku/` 目录下的类型定义
+
+---
+
+祝你使用愉快！

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@me-framework/me-sku-editor",
+  "version": "1.0.1",
+  "description": "A powerful Vue 3 SKU editor component",
+  "type": "module",
+  "main": "./dist/lib/me-sku-editor.umd.js",
+  "module": "./dist/lib/me-sku-editor.mjs",
+  "types": "./dist/lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/lib/me-sku-editor.mjs",
+      "require": "./dist/lib/me-sku-editor.umd.js",
+      "types": "./dist/lib/types/index.d.ts"
+    },
+    "./style.css": "./dist/lib/me-sku-editor.css"
+  },
+  "files": [
+    "dist/lib",
+    "dist/demo",
+    "document",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "keywords": [
+    "vue",
+    "vue3",
+    "sku",
+    "editor",
+    "component",
+    "商品规格",
+    "sku-editor"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/me-sku-editor.git"
+  },
+  "homepage": "https://github.com/your-username/me-sku-editor",
+  "bugs": {
+    "url": "https://github.com/your-username/me-sku-editor/issues"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run build:lib && npm run build:demo",
+    "build:lib": "vue-tsc -b && vite build --config vite.config.lib.ts",
+    "build:demo": "vite build",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build",
+    "pub": "npx auto-version && npm publish --access public"
+  },
+  "peerDependencies": {
+    "@element-plus/icons-vue": "^2.3.0",
+    "element-plus": "^2.14.0",
+    "vue": "^3.4.0",
+    "vxe-pc-ui": "^4.15.0",
+    "vxe-table": "^4.19.0"
+  },
+  "dependencies": {
+    "sortablejs": "^1.15.7",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "@types/sortablejs": "^1.15.9",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vue/tsconfig": "^0.9.1",
+    "auto-version-js": "^1.0.0",
+    "page-agent": "^1.11.0",
+    "typescript": "~6.0.2",
+    "vite": "^8.1.0",
+    "vite-plugin-dts": "^5.0.3",
+    "vue-tsc": "^3.3.5"
+  }
+}