@gspwidget/knowledge-selector

v0.1.2

Published

21 days ago

Vue 3 知识库、目录与文档范围选择弹窗

0High
0Medium
0Low

toxiic

chengchen

@wisedoc/knowledge-selector

Vue 3 知识库选择弹窗，按设计稿「20.3 知识库选择-帮助」实现知识库目录页。提供左侧知识库、右侧目录/文档、跨库混选、初始回显、已选标签、加载更多和错误重试。不依赖 vue-router、Farris、原工程 App 或任何全局组件注册。

安装

当前交付为本地 npm 安装包（尚未发布到 npm 仓库）：

npm install "D:\\path\\to\\wisedoc-knowledge-selector-0.1.2.tgz"

宿主需使用 Vue 3.4+。Ant Design Vue 4 和 Axios 作为包依赖安装；Vue 是 peer dependency，复用宿主实例。支持 ESM、CommonJS，提供 TypeScript 声明。包内图标已内联，无需额外复制静态资源。

最小接入

<script setup lang="ts">
import { ref } from 'vue'
import { KnowledgeSelectorModal } from '@wisedoc/knowledge-selector'
import type { KnowledgeSelection, KnowledgeSelectionResult } from '@wisedoc/knowledge-selector'
import '@wisedoc/knowledge-selector/style.css'

const open = ref(false)
const selected = ref<KnowledgeSelection[]>([])

function handleConfirm(result: KnowledgeSelectionResult) {
  console.log(result.KBIds, result.DirIds, result.DocIds)
  // 将范围提交给宿主业务；组件自身不写入知识库。
}
</script>

<template>
  <button @click="open = true">选择知识</button>
  <KnowledgeSelectorModal
    v-model:open="open"
    v-model="selected"
    @confirm="handleConfirm"
  />
</template>

必须引入 style.css。不需要调用 app.use(Antd)，也不需要引入原工程的全局样式。弹窗默认挂载到 document.body，适用于浏览器端 Vue 应用。

接口和鉴权

默认请求同源的下列现有接口。开发时由宿主配置代理；部署时由网关转发 /api。

| 接口 | 参数/响应 | | --- | --- | | GET /api/wisedoc/rest/columns/findAllMyKB | [{ id, name }] | | GET /api/wisedoc/rest/columns/findMyDirectory | parentId；[{ id, name }] | | GET /api/wisedoc/rest/columncontent/findContentList/paged | channelId, page, size, offset=0, orderBy=id, order=asc；{ data: [{ id, title }], total } |

文档分页从 1 开始，每页 50 条。后端分页后才做权限过滤，因此通过 page * size < total 判断是否还有下一页，不会因空页漏掉后续内容。错误和登录页 HTML 会明确提示，不会用示例数据替换真实接口结果。

复用宿主 Axios 实例及其鉴权拦截器：

import { createKnowledgeDataSource } from '@wisedoc/knowledge-selector'
import { http } from './your-http-client'

// 在 setup 中创建一次，不要在模板表达式中反复创建。
const dataSource = createKnowledgeDataSource({ http })

<KnowledgeSelectorModal v-model:open="open" v-model="selected" :data-source="dataSource" />

也可以配置 createKnowledgeDataSource({ baseURL: 'https://your-api.example', withCredentials: true })。跨域鉴权和 CORS 由宿主/网关负责；组件不会从 localStorage 猜测或提取令牌。传入 http 时优先使用该实例，baseURL、withCredentials 应直接配置在实例上。

如果其他项目接口不同，直接实现导出的 KnowledgeDataSource：

interface KnowledgeDataSource {
  getLibraries(signal?: AbortSignal): Promise<KnowledgeNode[]>
  getChildren(parent: KnowledgeNode, page: number, size: number,
    signal?: AbortSignal): Promise<KnowledgeChildren>
}

节点必须含完整 libraryId、parentId、ancestorIds、pathNames；库自身祖先为空。文档节点还必须提供字符串类型的 attachments。 getChildren 第 1 页返回所有直接子目录及本页文档，后续页只返回文档；total 是文档分页总数。可利用 AbortSignal 在弹窗关闭时终止请求。

选择规则和返回值

勾选知识库，覆盖整个库内的目录和文档，含尚未加载的内容。下级勾选并禁用。
勾选目录，覆盖其所有后代；祖先显示半选，下级勾选并禁用。
支持整库 + 其他库的目录 + 单独文档混选。
勾选父级会合并并移除冗余下级选择；取消父级后，其覆盖的下级一起取消，不恢复合并前的选择。
单独选择全部已加载子项不会自动选中父级，避免扩大到未加载的内容。
切换知识库保留选择；取消/关闭弹窗丢弃本轮修改；仅确定时更新 v-model 并触发 confirm。
可以确定空数组，供宿主清除原选择。

confirm 返回 { KBIds: string[], DirIds: string[], DocIds: string[] }；不返回 version 字段。v-model 仍使用带祖先路径和文档 attachments 的内部选择项数组，以便弹窗回显父子关系。三个数组只包含去重后的显式范围，不枚举整库中每个文档：

{
  "KBIds": ["kb-a"],
  "DirIds": ["dir-b"],
  "DocIds": ["attachment-metadata-c"]
}

当 KBIds 中有知识库 ID 时，表示选中整座知识库；当 DirIds 中有目录 ID 时，表示选中该目录及全部后代；DocIds 保存单独选中文档的 attachments 字段，不再保存文档主键。范围由业务消费方解析，实际检索/读取时仍应由业务后端校验权限。请完整保存 v-model 项以便回显，尤其是 ancestorIds 和文档 attachments；仅传确认结果无法恢复父子覆盖关系。初始输入必须满足类型和祖先路径约定，可使用导出的 normalizeSelection 校验/合并。初始值在每次打开时复制；弹窗开启期间需要刷新输入，可调用组件 ref 的 reload()。

Props、事件

| 属性 | 类型 | 默认值 | | --- | --- | --- | | open / v-model:open | boolean | 必传 | | modelValue / v-model | KnowledgeSelection[] | [] | | dataSource | KnowledgeDataSource | 同源 wisedoc 接口 | | showAddLibrary | boolean | false |

| 事件 | 说明 | | --- | --- | | confirm | 确认后返回 { KBIds, DirIds, DocIds } | | cancel | 取消、右上角关闭、Esc；不更新选择值 | | add-library | 点击「添加知识库」，由宿主决定打开何种管理入口 | | update:open | 控制弹窗可见性 | | update:modelValue | 仅确定时更新数组 |

showAddLibrary 默认关闭，以便不同项目自行接入创建流程。开启后应处理 add-library 事件。新增完成可以调用 reload() 刷新，注意该操作从传入的 modelValue 重新初始化本轮选择。

搜索说明

组件不提供搜索。kn-center-ibp 当前没有同时返回所有可见知识库、目录、文档及完整层级路径的统一搜索接口。早期实现曾在前端遍历所有知识库和目录，再分页请求每个目录的文档，这会随知识库和目录数量产生大量请求，因此已经移除。后端现有的指定栏目文档搜索、全局目录名称搜索和 EISP 全文检索只能分别覆盖部分对象；EISP 还依赖索引配置，无法安全拼成本选择器所需的统一结果。正常浏览仍按需加载：打开弹窗加载知识库和首个库的直接内容，用户展开某个目录时才请求该目录，文档超过一页时才显示“加载更多”。

在源码工程内开发和构建

在 D:\Java\wisedoc-frontend 根目录执行：

npx [email protected] install --frozen-lockfile
npm run test:selector
npm run build
npm run build:selector
npm run pack:selector

原工程 lockfile 为 pnpm 8 格式；无需升级或重写锁文件。 npm run pack:selector 只构建并打包 src/modules/knowledge-selector/ 对应的 packages/knowledge-selector/，不会把整个前端工程打进 npm 包。包内只有组件 ESM/CJS、CSS、类型声明、包清单和 README。

完整应用：dist/
组件 ESM/CJS/CSS/类型：packages/knowledge-selector/dist/
npm 安装包：packages/knowledge-selector/wisedoc-knowledge-selector-0.1.2.tgz
源码：src/modules/knowledge-selector/
实际接口入口：http://localhost:4202/#/dc/knowledge-selector
明确标注的示例入口：http://localhost:4202/#/dc/knowledge-selector?demo=1

开发服务器默认代理 http://localhost:5300；可用环境变量 WISEDOC_API_TARGET 覆盖。例如 PowerShell：

$env:WISEDOC_API_TARGET = 'http://localhost:5200'
npm run dev

完整应用部署到既有 /subapp/wisedoc/ 时访问 /subapp/wisedoc/index.html#/dc/knowledge-selector。示例数据和演示页面不包含在 npm 组件包中；npm 包只包含真实接口适配和可替换数据源的组件。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme