yx-web-sdk

一个基于 Vue 3 + TypeScript 的轻量级组件库

IndexEntry 接入

IndexEntry 使用调用方传入的公开 App Key、账号、动态 Token 和 QChat 地址初始化连接。一个页面只挂载一个入口和请求桥接；已存在其他入口拥有的全局 SDK 实例时拒绝接管。连接按「实例归属 + 账号 + 连接健康度」复用，不比较 Token（后端每次签发新 Token，比较会退化为销毁后立刻重登）；账号变化时才销毁重建，同账号在途初始化直接跟随该 Promise。组件卸载不立刻释放连接，而是挂起延迟销毁：宽限期内同账号重新初始化会撤销销毁并复用会话，超时无新连接才真正释放。初始化数据失败后返回 error，由调用方响应 reconnect 获取新凭据后重试。

可选 dashboard 属性接收 { groupTitle, membersTitle, searchMembers, loadMore, loading?, failed?, retry?, empty? } 文案，启用群组／频道嵌套列表、成员搜索和继续加载入口，配套样式由 Dashboard 外层容器提供。搜索范围为已加载成员，切换频道会清空关键词；在线标识仅使用接口返回的状态。省略该属性时保留原有侧栏。主动选择频道会发出 channel-selected 事件，初始化选中频道不触发该事件，可用于移动端列表／聊天切换。

入口提供可选 message-after 插槽，参数为 { message, mine, beforeResize }，仅在未撤回的普通文本消息正文之后渲染；宿主在展开或异步内容改变前调用 beforeResize()，保持底部跟随或历史阅读锚点。宿主负责资源识别与展示，SDK 不依赖工作台业务组件。

入口提供可选 composer-attachments 插槽，参数为 { draft, disabled }。宿主可读写当前频道的 draft.resources 数组，每项至少包含 { key, url }，SDK 不解析业务资源。可选 composeResourceText(text, resources) 用于宿主组合正文并按业务规则去重；省略时按 URL 去重追加链接。禁用时宿主须禁止选择／移除。资源不写入 attach 或 ext，沿用文本发送、频道缓存及账号隔离。

文本及资源发送等待频道权限和 SDK 结果，失败保留草稿，成功仅清除发送快照中的内容。引用调用 QChat 原生 replyMessage，历史按 replyRefer 和 getReferMessages 展示；旧 ext.quoteMsg 保留历史兼容，新输入区不再复制整条原文。失败不自动发送普通消息。原文不在已加载列表时可展示读取到的预览，但无法直接滚动定位；撤回、删除或读取失败显示不可用提示。

开发进度与验证记录见 ROADMAP.md。

Dashboard 模式支持多个群组同时展开，群组名只控制展开／收起，点击频道才切换聊天。列表按群组缓存并后台刷新，列表、消息和成员分别显示加载或重试状态。邀请和创建频道收进当前群组的操作菜单，保留原有管理权限。配套主项目使用 44 px 群组行、24 px 头像和同行人数，只有当前频道高亮。非 Dashboard 模式继续使用原有侧栏。

IndexEntry 统一加载频道历史并合并重复请求；首次消息加载超过 150 ms 显示骨架，完成后 120 ms 淡入，遵循减少动态效果偏好。频道缓存保存消息、草稿、引用、附件和滚动位置，窄屏聊天区重新可见时恢复位置。消息与成员结果按频道隔离，身份与发送权限检查额外校验选择版本。身份及历史准备前禁发；权限等待期间切换会取消此次发送并保留原草稿。缓存只保留在当前入口会话，卸载或手动重连时清理。

✨ 特性

• 🚀 基于 Vue 3 + TypeScript 构建
• 📦 支持 ES Module 和 UMD 格式
• 🌲 支持按需加载（Tree Shaking）
• 💪 完整的 TypeScript 类型定义
• 🎨 支持自动导入组件和样式
• 📖 提供 VitePress 文档

📦 安装

# 使用 npm 安装
npm install yx-web-sdk

# 或使用 pnpm
pnpm add yx-web-sdk

# 或使用 yarn
yarn add yx-web-sdk

🚀 快速开始

开发环境（使用源码）

1. 在yx-web-sdk项目中使用 npm link，创建一个符号链接
2. 在你的项目使用 npm link yx-web-sdk

在开发组件库或本地调试时，使用 development 入口直接引用源码：

import { createApp } from 'vue'
// 开发环境：直接使用源码，支持热更新
import yxWebSdk from 'yx-web-sdk/development'
import App from './App.vue'

const app = createApp(App)
// 注册组件库
app.use(yxWebSdk)
app.mount('#app')

正式环境（使用打包产物）

在生产环境或正式项目中，使用主入口引用打包后的代码：

import { createApp } from 'vue'
// 正式环境：使用打包后的代码
import yxWebSdk from 'yx-web-sdk'
// 引入全量样式
import 'yx-web-sdk/style.css'
import App from './App.vue'

const app = createApp(App)
// 注册组件库
app.use(yxWebSdk)
app.mount('#app')

📖 使用方式

方式一：完整引入

适合快速开发和原型设计，一次性引入所有组件：

import { createApp } from 'vue'
// 正式环境使用打包产物
import yxWebSdk from 'yx-web-sdk'
// 引入全量样式（包含所有组件样式）
import 'yx-web-sdk/style.css'
import App from './App.vue'

const app = createApp(App)
// 注册所有组件
app.use(yxWebSdk)
app.mount('#app')

开发环境完整引入：

import { createApp } from 'vue'
// 开发环境使用源码
import yxWebSdk from 'yx-web-sdk/development'
// 引入全局样式
import 'yx-web-sdk/global.css'
import App from './App.vue'

const app = createApp(App)
app.use(yxWebSdk)
app.mount('#app')

方式二：按需引入（推荐）✨

按需引入可以减少打包体积，只引入使用的组件：

从主入口按需引入（支持 Tree Shaking）

// 正式环境：从主入口引入，支持 Tree Shaking
import { Input } from 'yx-web-sdk'
// 引入全局样式（包含 CSS 变量等基础样式）
import 'yx-web-sdk/global.css'
// 引入组件样式
import 'yx-web-sdk/input/style.css'

在 Vue 3 的 <script setup> 中使用：

<script setup>
// 正式环境：按需引入组件
import { Input } from 'yx-web-sdk'
// 引入全局样式
import 'yx-web-sdk/global.css'
// 引入组件样式
import 'yx-web-sdk/input/style.css'
</script>

<template>
  <Input placeholder="请输入内容" />
</template>

直接引入单个组件

// 正式环境：直接引入单个组件
import Input from 'yx-web-sdk/input'
// 引入全局样式
import 'yx-web-sdk/global.css'
// 引入组件样式
import 'yx-web-sdk/input/style.css'

开发环境按需引入：

// 开发环境：使用 development 入口
import yxWebSdk from 'yx-web-sdk/development'
import 'yx-web-sdk/global.css'

💡 提示：

• 按需引入时，使用 'yx-web-sdk/global.css' 引入全局样式（包含 CSS 变量等基础样式）
• 使用 'yx-web-sdk/style.css' 引入全量样式（包含所有组件样式）
• 按需引入时推荐使用 global.css，避免样式重复

方式三：自动按需引入（最优雅）🎯

这是最推荐的方式，像 Element Plus 一样，无需手动导入组件和样式！

安装依赖

npm install -D unplugin-vue-components

配置 Vite

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { YxWebSDKResolver } from 'yx-web-sdk'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [
        YxWebSDKResolver({
          importStyle: true, // 自动导入样式
          prefix: 'Yx', // 组件前缀，默认为 'Yx'
        }),
      ],
    }),
  ],
})

使用方式

配置完成后，可以直接在模板中使用组件，无需任何导入语句！

<template>
  <!-- 组件和样式会自动导入 -->
  <YxInput placeholder="请输入内容" />
</template>

<!-- 无需 script setup，组件和样式会自动导入 -->

高级配置

YxWebSDKResolver({
  importStyle: true, // 是否自动导入样式，默认: true
  prefix: 'Yx', // 组件前缀，默认: 'Yx'
  lib: 'yx-web-sdk', // 库名，默认: 'yx-web-sdk'
})

📋 组件列表

• Input - 输入框组件

更多组件正在开发中...

🛠️ 开发

环境要求

• Node.js >= 18
• npm / pnpm / yarn

开发命令

# 安装依赖
npm install

# 启动开发环境（使用本地源码，端口 3000）
npm run dev

# 启动 Demo 应用（使用打包产物，端口 4000）
npm run dev:examples

# 构建组件库
npm run build

# 构建组件库 + 预览 Demo 应用
npm run preview

# 启动文档
npm run docs:dev

# 运行测试
npm test

# 代码检查
npm run lint

# 代码格式化
npm run format

项目结构

yx-web-sdk/
├── src/                    # 组件库源码
│   ├── components/         # 组件目录
│   │   ├── input/         # Input 组件
│   │   └── index.ts       # 组件导出
│   ├── resolver/          # 自动导入解析器
│   ├── plugin/            # Vite 插件
│   ├── styles/            # 全局样式
│   ├── stores/            # 状态管理
│   ├── utils/             # 工具函数
│   └── index.ts           # 主入口
├── test/                  # 开发环境测试
│   ├── App.vue            # 测试应用
│   └── vite.config.ts     # 开发环境配置
├── examples/              # Demo 应用
│   ├── App.vue            # Demo 应用
│   └── vite.config.ts     # Demo 应用配置
├── dist/                  # 构建产物
└── docs/                  # 文档

开发环境说明

• npm run dev - 开发环境，端口 3000，使用 test/ 文件夹，引用本地源码（yx-web-sdk/development），支持热更新
• npm run dev:examples - Demo 应用，端口 4000，使用 examples/ 文件夹，引用打包产物（yx-web-sdk）
• npm run preview - 先构建再启动 Demo 应用，模拟真实使用场景

📦 构建产物结构

dist/
├── style.css                    # 全量样式
├── global.css                   # 全局样式（CSS 变量等）
├── yx-web-sdk.es.js             # ES Module 主入口
├── yx-web-sdk.umd.js            # UMD 主入口
├── index.d.ts                   # 主入口类型定义
├── input/                       # Input 组件独立目录
│   ├── index.es.js              # Input 组件 JS
│   └── style.css                # Input 组件样式
└── components/                  # TypeScript 类型定义
    └── input/
        └── index.d.ts           # Input 类型定义

🌲 按需加载原理

Tree Shaking（JS 按需加载）

组件库支持多种导入方式，都支持 Tree Shaking：

// 方式1: 从主入口导入（推荐用于多个组件）
import { Input } from 'yx-web-sdk'

// 方式2: 按需导入单个组件（推荐用于少量组件）
import Input from 'yx-web-sdk/input'

// 方式3: 自动导入（最优雅，无需手动导入）
<YxInput /> <!-- 自动导入组件和样式 -->

打包工具（Vite/Webpack）会通过 Tree Shaking 自动移除未使用的代码，只打包你使用的组件。

样式按需加载

每个组件都有独立的样式文件：

// 按需引入：先加载全局样式（包含 CSS 变量，不包含组件样式）
import 'yx-web-sdk/global.css'
// 再加载使用的组件样式
import 'yx-web-sdk/input/style.css'

// 或者使用全量样式（包含所有组件样式，适合完整引入）
import 'yx-web-sdk/style.css'

✨ 最佳实践

🚀 推荐：自动导入（最优雅）

对于新项目，强烈推荐使用自动导入方案：

# 安装依赖
npm install -D unplugin-vue-components

# 配置 vite.config.ts
import { YxWebSDKResolver } from 'yx-web-sdk'

然后直接在模板中使用，无需任何导入！

手动导入方案（备选）

小项目（使用 1-2 个组件，按需引入）：

// 正式环境
import Input from 'yx-web-sdk/input'
import 'yx-web-sdk/global.css'
import 'yx-web-sdk/input/style.css'

中型项目（使用 3-5 个组件）：

// 正式环境
import { Input } from 'yx-web-sdk'
import 'yx-web-sdk/global.css'
// 或使用全量样式
import 'yx-web-sdk/style.css'

大型项目（使用多个组件，完整引入）：

// 正式环境
import yxWebSdk from 'yx-web-sdk'
import 'yx-web-sdk/style.css'

核心优势

• ✅ 零配置导入 - 像 Element Plus 一样优雅
• ✅ 自动样式导入 - 无需手动管理 CSS
• ✅ Tree Shaking - 只打包使用的组件
• ✅ TypeScript 支持 - 完整的类型提示
• ✅ 热重载友好 - 开发体验极佳
• ✅ 打包体积最小 - 按需加载，无冗余代码

🔧 环境区分

开发环境

在开发组件库或本地调试时，使用 development 入口：

// 开发环境：直接使用源码，支持热更新
import yxWebSdk from 'yx-web-sdk/development'
import 'yx-web-sdk/global.css'

特点：

• ✅ 直接使用源码，无需构建
• ✅ 支持热更新
• ✅ 便于调试和开发

正式环境

在生产环境或正式项目中，使用主入口：

// 正式环境：使用打包后的代码
import yxWebSdk from 'yx-web-sdk'
import 'yx-web-sdk/style.css'

特点：

• ✅ 使用优化后的打包产物
• ✅ 体积更小，性能更好
• ✅ 适合生产环境

📄 License

MIT

Dashboard 入口支持 active 可见性门控及 unread 事件；隐藏入口和隐藏窗口暂停频道未读清除。已加载群组／频道可按名称筛选，输入区支持 1 至 6 行自动高度；消息操作可由宿主 message-actions 插槽提供，参数为 { message, quote, revoke }；仅可操作消息显示，revoke 不可用时为 undefined。插槽贯穿入口至消息卡片，宿主接管右键菜单时停用既有文本菜单。正文使用明确的 chatCardMessage 容器，操作扩展不参与正文宽度分配。

宿主可通过 message-body 插槽提供安全正文，通过 conversation-tools 使用当前频道的 search／find 消息工具；message-focus 插槽提供独立原文预览。messageTarget 与 messageTargetVersion 支持频道／原文直达和重试，查询按选择版本隔离；搜索使用 QChat searchMsgByPage，原文使用 getMessageHistoryByIds，权限与应用能力由云信决定。