@qynpm/qy-address-dialog

@qynpm/qy-address-dialog

面向 ERP 录单、详情回填场景的地址编辑弹窗能力包。

当前提供：

• QyAddressDialog
• QyAddressDialogConfirmPayload
• AddressDialogRow
• AddressDialogExtraField
• AddressDialogRequiredField

安装

pnpm add @qynpm/qy-address-dialog

Peer Dependencies：

• vue ^3.4.21
• element-plus ^2.8.7，宿主同时引入其样式

引入

import QyAddressDialog from '@qynpm/qy-address-dialog'
import type {
  AddressDialogExtraField,
  AddressDialogParseResultMode,
  AddressDialogRequiredField,
  AddressDialogRow,
  QyAddressDialogConfirmPayload
} from '@qynpm/qy-address-dialog'

设计说明

这个包不是纯基础 UI 组件，而是表单能力层的业务组件，主要解决：

• 原始地址文本输入
• 默认地址解析
• 结构化地址字段编辑
• flowRecv* 兼容字段回填
• 配置化扩展字段
• 可配置必填字段
• 确认时统一输出标准结果

与 QyDialog 的关系

组件源码通过 @qynpm/ui/qy-dialog 公共子入口复用 QyDialog，构建时将该入口及其内部工具、样式打入地址包。UI 仅是开发/构建依赖；宿主只提供 Vue、Element Plus 和 Element Plus 样式，无需安装或注册 UI 包。这不代表整个 UI 包支持 Element Plus 2.8.7。

外部地址协议仍是 open、update:open、confirm(payload) 和 cancel，地址组件自己持有校验、保存 loading 与最终关闭时机。地址保存成功后才关闭，失败会保持打开；业务侧不需要接触 Dialog 的 renderer 类型或旧 modelValue/layout/confirmProps 协议。

QyDialog 的实现仍由 UI 维护；更新内部弹窗需要重新构建、验收并发布地址包。构建前先构建 UI，发布验收必须使用真实 tarball，覆盖 Element Plus 2.8.7 与 2.14.5、独立消费与宿主浮层共存，不能用源码 alias 或 mock 测试代替。

补充说明：

• 组件内部同时维护 receiver* 与 flowRecv* 两套字段，便于兼容历史页面。
• 默认内置 ERP 地址解析能力，可通过 parseMethod 覆盖。
• saveOnConfirm / saveMethod 只提供扩展点，不在包内直接写死业务保存逻辑。
• 默认不会执行线上地址同步保存，只回传当前弹窗表单值给接入页面。
• requiredFields 用来控制当前页面实际启用哪些必填校验，红色星号也会与之保持一致。
• syncRawTextOnOpen 用来控制上方“智能识别地址”文本框是否根据传入 row 自动回显。
• parseResultMode 用来控制地址解析后只回填省市区，还是回填完整地址、姓名、电话。
• autoParseOnOpen 适合历史页面只有 flowRecvAddress/flowRecvArea 的场景，打开后会按 parseResultMode 自动尝试回填字段。
• saveMethod 抛错时，组件只会阻止弹窗关闭；错误提示建议交给业务请求层或全局响应拦截器统一处理，避免组件层重复提示。
• 组件内部自带确认态提交锁；即使通过动态实例挂载，也会在保存期间禁用确认，避免重复提交。

快速上手

<template>
  <el-button type="primary" @click="open = true">修改地址</el-button>

  <QyAddressDialog
    :open="open"
  :row="row"
  :extra-fields="extraFields"
  :required-fields="requiredFields"
  :online-sync-enabled="false"
  @update:open="open = $event"
  @confirm="handleConfirm"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import QyAddressDialog from '@qynpm/qy-address-dialog'
import type {
  AddressDialogExtraField,
  AddressDialogRequiredField,
  QyAddressDialogConfirmPayload
} from '@qynpm/qy-address-dialog'

const open = ref(false)
const row = ref({
  posCode: 'POS-001',
  refOid: 'S3-20260415',
  receiverState: '浙江省',
  receiverCity: '杭州市',
  receiverDistrict: '余杭区',
  receiverTown: '仓前街道',
  receiverAddress: '梦想小镇互联网村 1 号楼 101 室',
  receiverName: '张三',
  receiverMobile: '13800138000'
})

const extraFields: AddressDialogExtraField[] = [
  {
    key: 'posCode',
    label: '店铺编码',
    placeholder: '请输入店铺编码',
    disabled: true,
    visible: true
  },
  {
    key: 'refOid',
    label: 'S3单号',
    placeholder: '请输入S3单号',
    disabled: true,
    visible: true
  }
]

const requiredFields: AddressDialogRequiredField[] = [
  'receiverName',
  'receiverState',
  'receiverCity',
  'receiverAddress'
]

function handleConfirm(payload: QyAddressDialogConfirmPayload) {
  console.log(payload)
}
</script>

原始地址文本框回显策略

QyAddressDialog 上方的原始地址文本框，默认不根据 row 自动回显。

原因：

• 要兼容历史页面旧逻辑
• 某些页面原来就是“上方文本框默认空，只作为手动智能识别输入区”

默认行为：

<QyAddressDialog :open="open" :row="row" />

此时：

• 上方 rawText 默认空
• 下方结构化字段正常按 row 回填

如果某个页面需要打开弹窗时就回显原始地址文本，可以显式开启：

<QyAddressDialog
  :open="open"
  :row="row"
  :sync-raw-text-on-open="true"
/>

地址解析范围开关

QyAddressDialog 支持通过 parseResultMode 控制解析结果的回填范围。

可选值：

• 'region'：只回填 receiverState/city/district/town，适合历史页面“省市区是一个字段、详细地址单独维护”的场景
• 'full'：回填省市区、详细地址、姓名、电话，适合完整地址录入页

示例：

<QyAddressDialog
  :open="open"
  :row="row"
  parse-result-mode="region"
/>

<QyAddressDialog
  :open="open"
  :row="row"
  parse-result-mode="full"
/>

补充说明：

• 顶部“智能识别”按钮会按 parseResultMode 回填
• autoParseOnOpen 也会按 parseResultMode 生效
• 默认值为 'full'

历史页面自动拆分

有些老页面本身只有：

• flowRecvAddress
• flowRecvArea
• flowRecvName
• flowRecvPhone

但保存接口又要求：

• receiverState
• receiverCity
• receiverDistrict
• receiverTown
• receiverAddress

这种场景建议开启，并按页面字段结构显式指定解析范围：

<QyAddressDialog
  :open="open"
  :row="row"
  :auto-parse-on-open="true"
  parse-result-mode="region"
/>

行为说明：

• 打开弹窗时，先按 row 回填结构化字段
• 如果当前是 split 模式，且拆分字段都为空，但 rawText 有值
• 组件会自动调用解析能力，并按 parseResultMode 回填字段
• 默认不会把上方原始文本框自动回显；只有显式开启 syncRawTextOnOpen 才会显示
• 用户可以在保存前继续人工修正解析结果

推荐搭配方式：

<QyAddressDialog
  :open="open"
  :row="{
    ...row,
    rawText: [row.flowRecvAddress, row.flowRecvArea, row.flowRecvName, row.flowRecvPhone]
      .filter(Boolean)
      .join(' ')
  }"
  :auto-parse-on-open="true"
  parse-result-mode="region"
  :required-fields="[
    'receiverName',
    'receiverState',
    'receiverCity',
    'receiverAddress',
    'receiverMobile'
  ]"
/>

必填字段策略

QyAddressDialog 支持通过 requiredFields 显式声明当前页面的必填字段，不同接入页可以保留各自原有规则。

默认行为：

• regionMode="split"：默认必填 receiverName、receiverState、receiverCity、receiverAddress
• regionMode="merged"：默认必填 receiverName、receiverRegionText、receiverAddress

如果某个页面历史规则更严格，可以自行覆盖：

<QyAddressDialog
  :open="open"
  :row="row"
  :required-fields="[
    'receiverName',
    'receiverState',
    'receiverCity',
    'receiverDistrict',
    'receiverTown',
    'receiverAddress',
    'receiverMobile'
  ]"
/>

如果页面不希望地址弹窗额外增加必填限制，也可以显式传空数组：

<QyAddressDialog
  :open="open"
  :row="row"
  :required-fields="[]"
/>

组件上的红色星号会与 requiredFields 保持一致。

保存行为

组件默认关闭线上地址同步：

• 弹窗内会展示“当前修改仅更新本系统数据，不会同步到线上地址信息。”
• 即使接入页面传了 saveOnConfirm 和 saveMethod，默认也不会执行 saveMethod
• 点击确认后仍会触发 confirm 并关闭弹窗，接入页面可以继续按原逻辑回填当前页面表单

如果某个场景后续确实需要恢复线上同步，可以在应用入口统一开启：

import { configureQyAddressDialog } from '@qynpm/qy-address-dialog'

configureQyAddressDialog({
  onlineSyncEnabled: true
})

也可以在单个弹窗调用点显式配置：

<QyAddressDialog
  :open="open"
  :row="row"
  :online-sync-enabled="false"
/>

当 saveOnConfirm 为 true 且提供了 saveMethod 时：

• 组件内部会自动维护确认按钮 loading，并阻止重复点击
• saveMethod 成功：组件继续触发 confirm 并关闭弹窗
• saveMethod 抛错：组件只会阻止关闭，不会再额外弹一次错误提示

推荐做法是让业务请求层统一负责错误提示，saveMethod 里只需要在失败时抛错即可。

如果接入页面已经复用了 ERP 请求封装或全局响应拦截器，那么这里不建议再由 QyAddressDialog 额外弹一次错误提示，否则容易出现重复提示。

API

Props

Emits

Expose

AddressDialogExtraField

interface AddressDialogExtraField {
  key: string
  label: string
  placeholder?: string
  disabled?: boolean
  visible?: boolean
  span?: 1 | 2
  type?: 'input' | 'textarea'
  rows?: number
}

AddressDialogRequiredField

type AddressDialogRequiredField =
  | 'receiverName'
  | 'receiverRegionText'
  | 'receiverState'
  | 'receiverCity'
  | 'receiverDistrict'
  | 'receiverTown'
  | 'receiverAddress'
  | 'receiverMobile'

QyAddressDialogConfirmPayload

组件确认后统一输出核心地址字段、flowRecv* 字段，以及所有扩展字段。

核心字段包括：

• receiverName
• receiverMobile
• receiverPhone
• receiverState
• receiverCity
• receiverDistrict
• receiverTown
• receiverAddress
• receiverZip
• rawText
• flowRecvName
• flowRecvPhone
• flowRecvAddress
• flowRecvArea

本地开发

pnpm dev
pnpm build

• pnpm dev：启动 playground
• pnpm build：构建产物并生成类型声明

本地 Demo

当前包内提供的调试入口：

• index.html
• playground/main.ts
• playground/App.vue

playground 重点验证：

• 弹窗打开与关闭
• 原始文本默认不回显
• 显式开启 syncRawTextOnOpen 后的回显效果
• requiredFields 对星号和校验的影响
• 地址识别结果回填
• 标准结果输出

Workspace 联调

{
  "dependencies": {
    "@qynpm/qy-address-dialog": "workspace:*"
  }
}

本地 serve 时可通过 workspace / vite alias 直接联调源码。