@qynpm/product-preview

起印商品结构编辑和展示组件包。

当前提供：

• QyProductPreview：商品结构编辑组件。
• QyProductPreviewTable：商品结构表格展示组件，承接旧 ERP prodPreview 展示壳。
• configureProductPreview：宿主运行时能力注入。

安装

pnpm add @qynpm/product-preview

Peer Dependencies：

• vue >= 3.4
• element-plus >= 2.0
• @element-plus/icons-vue >= 2.0
• @vueuse/core >= 10.0
• @qynpm/ui
• @qynpm/hooks

宿主项目仍需要引入 Element Plus 样式：

import 'element-plus/dist/index.css'

引入

import ProductPreview, {
  QyProductPreview,
  QyProductPreviewTable,
  configureProductPreview
} from '@qynpm/product-preview'

也可以使用兼容入口：

import { formatParams } from '@qynpm/product-preview/utils'
import { PARAMS_LABEL } from '@qynpm/product-preview/constants'
import { TRIGGER_SYMBOL } from '@qynpm/product-preview/useTrigger'

宿主接入

@qynpm/product-preview 不直接绑定 ERP 的 request、上传和消息反馈。宿主需要在启动阶段注册运行时能力：

import { configureProductPreview } from '@qynpm/product-preview'

configureProductPreview({
  request(config) {
    return request(config)
  },
  getConfig({ num }) {
    return request({
      url: `/global/getConfig?num=${num}`,
      method: 'get'
    })
  },
  getMarketConfig(num) {
    return request({
      url: `/admin/global/getConfig?num=${num}`,
      method: 'get'
    })
  },
  craftDetails(code) {
    return request({
      url: '/craft/craftDetails',
      method: 'post',
      data: { code }
    })
  },
  getProductDetails(code) {
    return request({
      url: '/product/getProductDetails',
      method: 'post',
      data: { code }
    })
  },
  uploadRequest(formData) {
    return request({
      url: '/permission-api/common/uploads',
      method: 'post',
      data: formData
    })
  },
  feedback(target, message, options) {
    ElMessage[options?.type || 'success'](message)
  }
})

也可以在全局注册组件时传入同一组运行时配置：

import QyProductPreview from '@qynpm/product-preview'

app.use(QyProductPreview, {
  request,
  uploadRequest,
  feedback
})

如果未注入 request，组件在调用接口或上传时会抛出明确错误；独立宿主至少需要注入 request，涉及备注图片上传时建议同时注入 uploadRequest。

建议接入位置：

• main.ts
• main.js
• 项目公共初始化文件，例如 setupProductPreview.ts

组件说明

QyProductPreview

商品结构编辑组件，负责：

• 商品模型初始化
• 商品属性编辑
• 材料属性编辑
• 工艺属性编辑
• 子件 / 组合结构编辑
• 备注图上传
• 商品结构序列化和回显

不负责：

• 商品选择弹窗
• 录单页面字段回填副作用
• 订单确认页业务编排
• ERP request 实例和接口绑定

基础用法：

<template>
  <QyProductPreview
    ref="previewRef"
    :product-detail="productDetail"
    :unit-map="unitMap"
    resetabled
    @ready="handleReady"
  />

  <el-button type="primary" @click="handleGetForm">获取结构数据</el-button>
</template>

<script setup>
import { ref } from 'vue'
import { QyProductPreview } from '@qynpm/product-preview'
import type { ProductPreviewInstance } from '@qynpm/product-preview'

const previewRef = ref<ProductPreviewInstance>()
const unitMap = []
const productDetail = []

function handleReady() {
  console.log('商品结构组件就绪')
}

function handleGetForm() {
  console.log(previewRef.value?.getForm())
}
</script>

固定最小布局用法：

<template>
  <QyProductPreview
    :product-detail="productDetail"
    responsive-mode="minimum"
    size="small"
  />
</template>

• responsive-mode 默认为 viewport，保持旧行为：内部布局继续按浏览器视口断点切换。
• responsive-mode="minimum" 是宿主明确指定的无条件最小布局，会固定启用紧凑和 mobile 状态，适合产品区固定在较窄容器中的场景；材质组占满内容宽度，组内紧凑选项横向排列并按可用空间自动换行。
• minimum 模式不读取浏览器或容器尺寸，不创建容器尺寸观察器；根节点提供 product-preview--minimum class 便于定位和测试。
• size="small" 只控制字体、输入控件高度等密度；是否使用最小布局由 responsive-mode 控制。
• material-craft-readonly 默认为 false。设为 true 时只锁定根级材质与工艺选择；材质/工艺备注及图片、已选工艺详情属性仍可编辑，已选工艺详情保持可打开查看。全局 readonly 仍会锁定全部编辑能力。
• regular-attr 在运行时变更时只更新属性锁定规则，不会重建当前产品树，也不会再次触发 ready。产品模型或 default-data 变更仍按既有行为重新初始化。

实例在 ready 后可作为产品树的稳定读写入口：

previewRef.value?.setValue('FP-TDGLH.BA-SL', '2500')
const latestProductTree = previewRef.value?.getForm()

setValue(attrPath, value) 只会更新存在的属性路径；无效路径保持无操作。路径使用实际根产品编码和属性编码，不能假定所有货品都使用同一个数量属性编码。

属性输入兼容方法也可通过实例调用：

const propertyText = previewRef.value?.getPropertyAttrInputValue()
previewRef.value?.setPropertyAttrInputValue('第一行\n第二行')
previewRef.value?.clearPropertyAttrInputValue()
previewRef.value?.propertyAttrInputFocus()

getPropertyAttrInputValue() 返回当前缓存文本，尚未收到输入变化时可能为 undefined。setPropertyAttrInputValue() 支持换行，clearPropertyAttrInputValue() 请求清空文本；二者都不承诺同步更新 getter。propertyAttrInputFocus() 保留旧录单联动的聚焦能力。

QyProductPreviewTable

商品结构展示组件，当前用于兼容旧 ERP prodPreview 的表格展示形态。

基础用法：

<template>
  <QyProductPreviewTable
    :tree-prod="treeProd"
    name="抽拉礼盒"
    preset-product-name="抽拉礼盒-500x500x50"
    flow-product-remark="测试备注"
    show-button
    @changeName="handleChangeName"
  />
</template>

<script setup>
import { QyProductPreviewTable } from '@qynpm/product-preview'

const treeProd = []

function handleChangeName(name) {
  console.log(name)
}
</script>

稳定导出

| 导出项 | 类型 | 说明 | | --- | --- | --- | | QyProductPreview | component | 商品结构编辑组件 | | QyProductPreviewTable | component | 商品结构展示组件 | | configureProductPreview | function | 注册宿主运行时能力 | | formatParams | helper | 商品模型转商品结构参数 | | getAttrValue | helper | 读取属性值 | | formatAttrValueToString | helper | 属性值文本化 | | PARAMS_LABEL | constant | 商品结构内部字段标识 | | KEY_TYPE_ENUM | constant | 商品属性类型枚举 | | TRIGGER_SYMBOL | symbol | 录单触发器兼容标识 |

当前兼容保留的深层入口：

import FromAttrItem from '@qynpm/product-preview/components/from/craft-from/from-attr-item'
import inputWrapper from '@qynpm/product-preview/components/controls/input-wrapper.vue'

这些入口是为了兼容 foundation、备注图等历史深引用，不建议新业务继续扩散使用。

分层边界

@qynpm/product-preview 负责商品结构编辑和展示。

@qynpm/pickers 后续负责商品选择，例如 ProductPicker。

宿主项目负责：

• API adapter
• 上传 adapter
• 消息反馈 adapter
• 录单页面字段回填
• 保存、确认、提交等业务编排

本地演示

pnpm --dir .\@qiyin\product-preview run dev

演示入口位于：

@qiyin/product-preview/playground

当前 demo 只用于基础组件包测试，不代表 ERP 页面替换已经完成。

playground 和 playground/data/product.json 只作为仓库内调试资产保留，不进入 npm 发布包。

迁移注意事项

迁移页面前，先阅读：

• 迁移注意事项