@qynpm/qy-address-dialog

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

当前提供：

• QyAddressDialog
• QyAddressDialogConfirmPayload
• AddressDialogRow
• AddressDialogExtraField
• AddressDialogRequiredField

安装

pnpm add @qynpm/qy-address-dialog

Peer Dependencies：

• vue >= 3.4
• element-plus >= 2.8
• @qynpm/ui >= 0.0.2

引入

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

设计说明

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

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

补充说明：

• 组件内部同时维护 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

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | open | boolean | false | 控制弹窗显示 | | row | AddressDialogRow | {} | 用于初始化回填的数据 | | extraFields | AddressDialogExtraField[] | [] | 业务扩展字段配置 | | title | string | '地址智能识别' | 弹窗标题 | | loading | boolean | false | 确认按钮加载状态 | | disabled | boolean | false | 是否整体禁用编辑 | | syncRawTextOnOpen | boolean | false | 是否在打开时把 row 自动拼成上方原始地址文本 | | autoParseOnOpen | boolean | false | 打开时若拆分字段为空，是否基于 rawText 自动解析旧地址 | | parseResultMode | 'full' \| 'region' | 'full' | 控制解析结果只回填省市区，还是回填完整地址、姓名、电话 | | regionMode | 'split' \| 'merged' | 'split' | 地址字段使用拆分模式还是合并模式 | | requiredFields | AddressDialogRequiredField[] | 按 regionMode 决定默认值 | 当前页面实际启用的必填字段 | | parseMethod | (rawText) => Promise<{ data?: { express_extract?: Record<string, unknown> } }> | undefined | 自定义地址解析方法 | | onlineSyncEnabled | boolean | 全局配置，默认 false | 是否执行线上地址同步保存 | | offlineNotice | string | 全局配置提示文案 | 关闭线上同步时展示的提示 | | saveOnConfirm | boolean | false | 确认时是否先执行 saveMethod | | saveMethod | (payload) => Promise<void> \| void | undefined | 自定义保存逻辑 |

Emits

| 事件 | 参数 | 说明 | | --- | --- | --- | | update:open | boolean | 更新弹窗开关 | | confirm | QyAddressDialogConfirmPayload | 点击确认后的标准地址结果 | | cancel | - | 点击取消 |

Expose

| 字段 | 类型 | 说明 | | --- | --- | --- | | validate | () => Promise<true> | 执行表单校验 | | getPayload | () => QyAddressDialogConfirmPayload | 获取当前弹窗表单值 | | syncFromRow | (row?: AddressDialogRow) => void | 按外部数据重新回填 |

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 直接联调源码。