@litianxiang/portal-ui 0.0.6 → 0.0.8

package/README.md

@@ -1,11 +1,407 @@
 # @litianxiang/portal-ui
 
-统一的流程表单公共控件库。
+统一的流程表单公共控件库，聚焦：
 
-目前只是搭好包结构，后续可以从各项目的 `components/control` 中逐步抽取 Base/Busi 系列组件到此包，并通过 pnpm workspace 或 npm 发布给各微服务项目复用。
+- Base 系列基础表单控件
+- Busi 系列业务控件
+- 统一消息弹框与文件预览能力
+- 与 `@litianxiang/portal-core` 对齐的 http 初始化桥接
 
-## 别名约定
+> 样式边界约定：
+>
+> - `portal-ui` 负责 `element-ui.scss`、`form.scss`、`portal-ui.css`
+> - `iconfont.css` 与 `global.scss` 已拆分到 `@litianxiang/portal-layout`
+
+## 安装
+
+```bash
+pnpm add @litianxiang/portal-ui
+# 或
+npm i @litianxiang/portal-ui
+```
+
+## 快速接入
+
+### 1) 在 `main.ts` 引入样式
+
+```ts
+import '@litianxiang/portal-ui/styles/portal-ui.css'
+import '@litianxiang/portal-ui/styles/element-ui.scss'
+import '@litianxiang/portal-ui/styles/form.scss'
+```
+
+### 2) 初始化 portal-ui 的 http
+
+推荐在应用启动时注入已有实例，或由 portal-ui 自行初始化：
+
+```ts
+import { initPortalUiHttp } from '@litianxiang/portal-ui'
+
+initPortalUiHttp({
+	getUserStore: () => useUserStore(),
+	getLoadingStore: () => useLoadingStore(),
+	baseURL: '',
+	onShowError: (msg) => warning(msg)
+})
+```
+
+如果你已有统一 http：
+
+```ts
+import { setPortalUiHttp } from '@litianxiang/portal-ui'
+
+setPortalUiHttp(http, logoutToAuth)
+```
+
+## 导出 API
+
+### 组件导出（详细）
+
+> 所有组件均可通过以下方式按需引入：
+
+```ts
+import {
+	BaseInput,
+	BaseSelect,
+	BaseDate,
+	BaseUpload,
+	BaseTable
+} from '@litianxiang/portal-ui'
+```
+
+#### Base 系列
+
+1. **BaseInput**
+
+- 用途：单行文本输入。
+- 适用场景：姓名、标题、编号、关键字等普通输入。
+- 示例：
+
+```vue
+<BaseInput v-model="formData.name" placeholder="请输入姓名" clearable />
+```
+
+2. **BaseButton**
+
+- 用途：统一按钮风格封装。
+- 适用场景：提交、查询、重置、删除等操作按钮。
+- 示例：
+
+```vue
+<BaseButton type="primary" @click="handleSubmit">提交</BaseButton>
+```
+
+3. **BaseCollapseToggle**
+
+- 用途：展开/折叠状态切换按钮。
+- 适用场景：高级筛选区域、表单分段折叠。
+- 示例：
+
+```vue
+<BaseCollapseToggle v-model="expanded" />
+```
+
+4. **BaseSwitch**
+
+- 用途：布尔状态开关。
+- 适用场景：启用/禁用、开/关类字段。
+- 示例：
+
+```vue
+<BaseSwitch v-model="formData.enabled" />
+```
+
+5. **BaseTable**
+
+- 用途：统一表格封装（表头、操作列、插槽能力）。
+- 适用场景：列表页、主从明细、可编辑网格。
+- 示例：
+
+```vue
+<BaseTable :data="tableData" :columns="columns" row-key="id" />
+```
+
+6. **BaseSelect**
+
+- 用途：下拉单选/多选封装。
+- 适用场景：字典项、状态、分类等选项输入。
+- 示例：
+
+```vue
+<BaseSelect v-model="formData.status" :options="statusOptions" clearable />
+```
+
+7. **BaseNumber**
+
+- 用途：数字输入封装。
+- 适用场景：数量、金额、排序号等数值字段。
+- 示例：
+
+```vue
+<BaseNumber v-model="formData.count" :min="0" :max="9999" />
+```
+
+8. **BaseTextarea**
+
+- 用途：多行文本输入。
+- 适用场景：备注、说明、审批意见。
+- 示例：
+
+```vue
+<BaseTextarea v-model="formData.remark" :rows="4" placeholder="请输入备注" />
+```
+
+9. **BaseDate**
+
+- 用途：日期/日期区间选择。
+- 适用场景：申请日期、生效日期、统计区间。
+- 示例：
+
+```vue
+<BaseDate v-model="formData.applyDate" type="date" />
+```
+
+10. **BaseTime**
+
+- 用途：时间选择。
+- 适用场景：上班时间、会议时间、时段配置。
+- 示例：
+
+```vue
+<BaseTime v-model="formData.startTime" />
+```
+
+11. **BaseUpload**
+
+- 用途：统一附件上传控件。
+- 适用场景：流程附件、证明材料、图片/PDF/文档上传。
+- 示例：
+
+```vue
+<BaseUpload v-model="formData.files" :proc-bid="procBid" />
+```
+
+12. **BaseCheckbox**
+
+- 用途：多选复选框组。
+- 适用场景：标签多选、权限项多选、条件组合。
+- 示例：
+
+```vue
+<BaseCheckbox v-model="formData.tags" :options="tagOptions" />
+```
+
+13. **BaseRadio**
+
+- 用途：单选按钮组。
+- 适用场景：性别、类型、单一状态选择。
+- 示例：
+
+```vue
+<BaseRadio v-model="formData.type" :options="typeOptions" />
+```
+
+14. **BaseLink**
+
+- 用途：统一样式的链接文本。
+- 适用场景：详情跳转、附件下载、辅助操作入口。
+- 示例：
+
+```vue
+<BaseLink @click="openDetail(row)">查看详情</BaseLink>
+```
+
+15. **BaseDialog**
+
+- 用途：弹窗容器封装。
+- 适用场景：新增/编辑弹窗、确认操作弹窗。
+- 示例：
+
+```vue
+<BaseDialog v-model="dialogVisible" title="编辑信息">
+	<div>...</div>
+</BaseDialog>
+```
+
+16. **BaseChinaArea**
+
+- 用途：中国省市区联动选择。
+- 适用场景：户籍地址、办公地址、收件地址。
+- 示例：
+
+```vue
+<BaseChinaArea v-model="formData.area" />
+```
+
+17. **BasePagination**
+
+- 用途：统一分页组件。
+- 适用场景：列表分页与查询联动。
+- 示例：
+
+```vue
+<BasePagination
+	:current-page="page.current"
+	:page-size="page.size"
+	:total="page.total"
+	@change="handlePageChange"
+/>
+```
+
+#### Busi 系列
+
+18. **BaseApprovalRecord**
+
+- 用途：审批记录展示（业务封装）。
+- 适用场景：流程单据详情中的审批轨迹。
+- 示例：
+
+```vue
+<BaseApprovalRecord :proc-inst-id="procInstId" />
+```
+
+19. **BaseUser**
+
+- 用途：人员选择控件。
+- 适用场景：申请人、审批人、抄送人选择。
+- 示例：
+
+```vue
+<BaseUser v-model="formData.user" />
+```
+
+20. **BusiDept**
+
+- 用途：部门选择控件。
+- 适用场景：组织归属、发起部门、统计维度部门。
+- 示例：
+
+```vue
+<BusiDept v-model="formData.dept" />
+```
+
+21. **BusiOutUser**
+
+- 用途：外包顾问选择控件。
+- 适用场景：外包人员派工、顾问信息录入。
+- 示例：
+
+```vue
+<BusiOutUser v-model="formData.outUser" />
+```
+
+22. **BusiUserDialog**
+
+- 用途：人员选择弹窗组件。
+- 适用场景：复杂筛选+批量选择人员。
+- 示例：
+
+```vue
+<BusiUserDialog v-model="userDialogVisible" @confirm="handleUserConfirm" />
+```
+
+#### 文件预览组件
+
+23. **BaseFilePreview**
+
+- 用途：基础文件预览容器。
+- 适用场景：单文件预览、附件详情预览。
+- 示例：
+
+```vue
+<BaseFilePreview :file-url="fileUrl" :file-name="fileName" />
+```
+
+24. **BusiFilePreview**
+
+- 用途：业务场景文件预览组件（推荐）。
+- 适用场景：流程单附件列表预览。
+- 示例：
+
+```vue
+<BusiFilePreview :files="attachmentList" />
+```
+
+25. **WorkflowFilePreview（兼容导出，已废弃）**
+
+- 用途：历史命名兼容。
+- 说明：已等价映射到 `BusiFilePreview`，新代码请直接使用 `BusiFilePreview`。
+
+### 方法导出（详细）
+
+#### 1) `baseMessageBox`
+
+- 作用：统一消息弹框能力（`confirm/alert/success/warning`）。
+- 典型场景：提交前确认、删除确认、统一警告提示。
+- 示例：
+
+```ts
+import { baseMessageBox } from '@litianxiang/portal-ui'
+
+await baseMessageBox.confirm('确认提交当前表单吗？')
+baseMessageBox.success('保存成功')
+baseMessageBox.warning('请先完善必填项')
+```
+
+#### 2) `initPortalUiHttp(options)`
+
+- 作用：创建并注册 portal-ui 默认 http（内部基于 `@litianxiang/portal-core` 的 `createAuthHttpClient`）。
+- 入参：
+	- `getUserStore: () => any`：返回 user store。
+	- `getLoadingStore: () => any`：返回 loading store。
+	- `baseURL?: string`：可选请求前缀。
+	- `onShowError?: (msg: string) => void`：可选统一错误提示。
+- 返回：`{ http, logoutToAuth }`。
+- 示例：
+
+```ts
+import { initPortalUiHttp } from '@litianxiang/portal-ui'
+
+const { http, logoutToAuth } = initPortalUiHttp({
+	getUserStore: () => useUserStore(),
+	getLoadingStore: () => useLoadingStore(),
+	onShowError: (msg) => warning(msg)
+})
+```
+
+#### 3) `setPortalUiHttp(http, logoutToAuth?)`
+
+- 作用：将业务系统已创建的 http 实例注入 portal-ui，避免重复创建拦截器。
+- 入参：
+	- `http: any`：宿主项目的统一 http 实例。
+	- `logoutToAuth?: () => void`：可选统一退出函数。
+- 典型场景：主项目已有 `http.ts`，portal-ui 只复用。
+- 示例：
+
+```ts
+import { setPortalUiHttp } from '@litianxiang/portal-ui'
+import { http, logoutToAuth } from '@/utils/http'
+
+setPortalUiHttp(http, logoutToAuth)
+```
+
+## 与 portal-core / portal-layout 的关系
+
+- `portal-ui`：控件与表单样式
+- `portal-layout`：布局组件、iconfont、global 样式
+- `portal-core`：路由、鉴权、请求拦截、权限/菜单/用户状态内核
+
+建议业务站点统一按此分层依赖，避免职责交叉。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm run build
+pnpm run pack:check
+```
+
+`pack:check` 会先构建再打包到临时目录，用于发布前检查产物。
+
+## 发布建议
+
+1. 修改版本号（遵循 patch 递增）
+2. 执行 `pnpm run pack:check`
+3. 确认产物仅包含预期的 `dist` 与类型声明
+4. 执行 `npm publish --access public --registry=https://registry.npmjs.org/`
 
-- `portal.ui` 内部新增专属别名：`@ui/* -> src/*`
-- 该别名仅用于 `portal.ui` 工程内的类型解析与开发体验
-- 当前包以 `src` 源码形式发布给宿主项目，库内运行时导入建议继续使用相对路径，避免宿主缺少 `@ui` 解析配置导致构建失败

package/dist/index.d.ts

@@ -22,16 +22,6 @@ export { default as BaseUser } from './components/control/busi/busi-user.vue'
 export { default as BusiDept } from './components/control/busi/busi-dept.vue'
 export { default as BusiOutUser } from './components/control/busi/busi-outuser.vue'
 export { default as BusiUserDialog } from './components/control/busi/busi-user-dialog.vue'
-export { default as MainLayout } from './components/layout/main-layout.vue'
-export { default as MainAside } from './components/layout/main-aside.vue'
-export { default as MainHeader } from './components/layout/main-header.vue'
-export { default as MainHeaderCrumb } from './components/layout/main-header-crumb.vue'
-export { default as MainHeaderInfo } from './components/layout/main-header-info.vue'
-export { default as MainHeaderTab } from './components/layout/main-header-tab.vue'
-export { default as MainFullscreen } from './components/layout/main-fullscreen.vue'
-export { default as MainLanguage } from './components/layout/main-language.vue'
-export { default as MainMenu } from './components/layout/main-menu.vue'
-export { default as GlobalLoading } from './components/layout/global-loading.vue'
 export { baseMessageBox } from './components/control/base/base-messagebox.vue'
 
 export type { InitPortalUiHttpOptions } from './utils/http'