@composy/address-book-vue

@composy/address-book-vue

@composy/address-book-core 的 Vue 3 适配层：提供 AddressBook / PeoplePicker 类型化组件、useAddressBook / usePeoplePicker 组合式函数与全局组件注册插件，目录逻辑全部保留在框架无关的核心包中。

✨ 核心能力

• 🧩 声明式组件：AddressBook 与 PeoplePicker 以 TS defineComponent 封装核心实例，Props 响应式同步
• 🛠️ 实例方法暴露：组件通过 expose 透出核心方法，可用模板 ref 直接调用
• 🧰 组合式函数：useAddressBook() / usePeoplePicker() 管理实例生命周期并跟踪选中部门 / 分组状态
• 🔌 全局插件：createAddressBookPlugin(options?) 一键全局注册两个组件，支持自定义注册名
• 🎨 Token 化样式：宿主节点 ldesign-address-book-vue-host，样式复用核心包的 --ldesign-address-book-* 变量体系

📦 安装

pnpm add @composy/address-book-vue vue

• Peer 依赖：vue ^3.5.32
• 运行依赖：@composy/address-book-core ^0.0.1

子路径导出：.、./components、./composables、./plugins。

🚀 快速开始

<script setup lang="ts">
import { AddressBook, PeoplePicker } from '@composy/address-book-vue'

const departments = [/* Department[] */]
const persons = [/* Person[] */]
</script>

<template>
  <AddressBook
    :departments="departments"
    :persons="persons"
    enable-multi-select
    show-alphabet-index
    @selection-change="selected => console.log(selected)"
    @department-select="department => console.log(department?.name)"
  />

  <PeoplePicker
    :departments="departments"
    :persons="persons"
    mode="multiple"
    :max="20"
    @confirm="selected => console.log(selected)"
  />
</template>

📖 API 参考

组件

常用事件：person-click、department-select、group-select、search、selection-change；选人器：change、confirm、cancel。

通过 ref 可调用的暴露方法（与核心实例一致）：

• AddressBook：search、clearSearch、selectDepartment、selectGroup、selectVisiblePersons、getSelectedPersons、setSelectedPersons、clearSelection、exportData、print、setTheme、setLocale 及数据变更方法
• PeoplePicker：getSelected、setSelected、clearSelection、selectDepartment、removeSelected、setDepartments、setPersons、setTheme、setLocale

组合式函数

import { useAddressBook, usePeoplePicker } from '@composy/address-book-vue'

const addressBook = useAddressBook()
const picker = usePeoplePicker()

addressBook.create(container, { departments, persons, enableHistory: true })
addressBook.search('alice')
addressBook.selectVisiblePersons()
picker.setSelected(['u1'])

• useAddressBook()：返回实例 ref、create(container, config?) 与代理核心方法的操作集，并维护 selectedDepartment / selectedGroup 响应式状态
• usePeoplePicker()：返回实例 ref 与选人器操作集

AddressBook 的 persistenceKey 会透传给 Core，用于隔离树面板收起状态等持久化偏好。Core 查询方法返回防御性快照，Vue 侧修改查询结果不会反向改变内部目录。

插件

import { createAddressBookPlugin } from '@composy/address-book-vue'
import { createApp } from 'vue'

createApp(App)
  .use(
    createAddressBookPlugin({
      addressBookName: 'LdesignAddressBook', // 默认 'AddressBook'
      peoplePickerName: 'LdesignPeoplePicker', // 默认 'PeoplePicker'
    })
  )
  .mount('#app')

同时导出 AddressBookPlugin（默认配置的插件对象）。

类型重导出

主入口重导出核心类型：AddressBookConfig、AddressBookInstance、PeoplePickerConfig、PeoplePickerInstance、Department、Person、ContactGroup、PersonFilterOptions、SearchCondition、ThemeMode、Locale、I18nConfig、AccessibilityConfig、ContextMenuItem、SelectionMode、OnlineStatus 等。

🎨 样式与主题

• Vue 宿主元素使用 ldesign-address-book-vue-host 类名；核心组件类名为 ldesign-address-book-*。
• 样式系统由核心包注入：--ldesign-address-book-* 组件变量映射到 LDesign 生成的 --ld-* 颜色 / 尺寸 token（如 --ld-primary-default、--ld-bg-surface、--ld-spacing-md）。
• 宿主应用需先引入 LDesign 全局 color / size token 样式，再挂载组件。

🔨 构建产物与验证

使用 @composy/builder 构建，产出 dist/、es/、esm/、lib/ 四类产物。

验证命令（取自包 package.json）：

pnpm build           # @composy/builder + output normalization/checks
pnpm type-check      # vue-tsc + ESM/CJS TypeScript checks
pnpm test            # ltesting run:unit
pnpm lint:check      # strict ESLint using .ldesign/eslint.config.js

注意：Vue 包类型检查会读取 core 已生成的 es/index.d.ts，修改 core 公共类型后请先构建 core 再执行本包 typecheck。

Builder and TypeScript configs live in .ldesign/:

• packages/vue/.ldesign/builder.config.ts
• packages/vue/.ldesign/tsconfig.json
• packages/vue/.ldesign/tsconfig.cjs.json
• packages/vue/.ldesign/tsconfig.typecheck.json

🔗 相关链接

• 工作区总览
• @composy/address-book-core — 核心库完整 API、配置项与数据模型