xdc-ui-lib 2.0.1 → 2.0.3

package/README.md

@@ -32,6 +32,13 @@ app.mount('#app')
 - [BaseForm 动态表单组件](#baseform-动态表单组件)
 - [BaseModal 模态框组件](#basemodal-模态框组件)
 - [FileUpload 文件上传组件](#fileupload-文件上传组件)
+- [FullScreenContainer 全屏容器组件](#fullscreencontainer-全屏容器组件)
+
+- [Hooks / 工具](#hooks--工具)
+  - [useModalManager 模态框管理](#usemodalmanager-模态框管理)
+  - [useColumnSetting 表格列设置 Hook](#usecolumnsetting-表格列设置-hook)
+  - [useFilterTypeDisplay 筛选项显示设置 Hook](#usefiltertypedisplay-筛选项显示设置-hook)
+  - [国际化（i18n）](#国际化i18n)
 
 ---
 
@@ -1074,6 +1081,207 @@ function onExceed(file) {
 
 ---
 
+## FullScreenContainer 全屏容器组件
+
+用于页面/区域的“全屏展示”容器组件，常见于：大屏、表格/图表全屏查看、需要在不改路由的情况下临时全屏等场景。
+
+> 说明：该组件为库内注册组件，可直接从 `xdc-ui-lib` 引入使用。
+
+### 基本用法
+
+```vue
+<template>
+  <FullScreenContainer>
+    <div style="height: 300px; background: #f5f5f5">内容区域</div>
+  </FullScreenContainer>
+</template>
+
+<script setup lang="ts">
+import { FullScreenContainer } from 'xdc-ui-lib'
+</script>
+```
+
+### 常见用法（配合工具栏按钮）
+
+```vue
+<template>
+  <a-button @click="toggle">切换全屏</a-button>
+
+  <FullScreenContainer ref="fsRef">
+    <BaseTable :columns="columns" :data-source="dataSource" />
+  </FullScreenContainer>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { FullScreenContainer, BaseTable } from 'xdc-ui-lib'
+
+const fsRef = ref<any>()
+
+function toggle() {
+  // 若组件内部 expose 了方法，可在此调用（以实际实现为准）
+  // fsRef.value?.toggle?.()
+}
+</script>
+```
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| noScroll | 是否隐藏内层白色容器滚动条；`false` 时内层 `overflow:auto`，`true` 时内层 `overflow:hidden` | `boolean` | `true` |
+| fill | 是否填满父容器；`true` 外层 `width/height:100%` 且内层绝对定位铺满；`false` 外层高度随内容（`height:auto`） | `boolean` | `true` |
+| flex | 外层是否采用 `flex(column)`；用于“上面标题/筛选区 + 下面表格自适应吃满剩余高度” | `boolean` | `true` |
+| gutter | 外层 padding（外层与内层之间间隙） | `number \| string` | `16` |
+| padding | 内层白色容器 padding（内容与白色容器边缘间距） | `number \| string` | `16` |
+| background | 内层白色容器背景色 | `string` | `'#fff'` |
+| maxHeight | 外层最大高度；用于“外层不滚、内层滚”的场景 | `number \| string` | `'100vh'` |
+| style | 透传给内层白色容器（`.fsc-content`）的 style（对象或字符串） | `Record<string, any> \| string` | `-` |
+
+### Slots
+
+| 插槽名 | 说明 |
+|------|------|
+| default | 容器内容 |
+
+### Events
+
+当前组件未定义/抛出自定义事件。
+
+---
+
+## Hooks / 工具
+
+### useModalManager 模态框管理
+
+用于对多个 BaseModal 进行注册/注销，并支持“一键关闭全部弹窗”。
+
+```ts
+import { useModalManager } from 'xdc-ui-lib'
+
+const { registerModal, unregisterModal, closeAllModals } = useModalManager()
+```
+
+**API：**
+
+- `registerModal(id: string, ref: { close?: () => void })`
+- `unregisterModal(id: string)`
+- `closeAllModals()`
+
+> 提示：`BaseModal` 内部会用到这个能力（如果你在业务里需要自行管理多个弹窗，也可以直接使用该 hook）。
+
+### useColumnSetting 表格列设置 Hook
+
+用于在业务侧**以 hook 方式**接入列设置（显隐/排序/固定/持久化），底层复用 `useColumnSettingStore` 的缓存逻辑。
+
+```ts
+import { computed } from 'vue'
+import { useColumnSetting, type ColumnSettingColumn } from 'xdc-ui-lib'
+
+const baseColumns: ColumnSettingColumn[] = [
+  { title: 'ID', dataIndex: 'id', key: 'id' },
+  { title: '名称', dataIndex: 'name', key: 'name' },
+]
+
+const {
+  tableRef,
+  selectedColumns,
+  currentSize,
+  initColumns,
+  getDisplayColumnsData,
+  handleColumnChange,
+  persist,
+} = useColumnSetting({
+  columns: () => baseColumns,
+  storageKey: 'user-list-columns',
+  disabledColumns: ['id'],
+  // hiddenColumns: ['action'],
+  // size: 'middle',
+  // persistOnChange: true,
+})
+
+initColumns()
+
+const displayColumns = computed(() => {
+  // 仅示例：你也可以直接用 selectedColumns 过滤 checked
+  return getDisplayColumnsData().filter((c) => c.checked)
+})
+```
+
+**核心入参（UseColumnSettingOptions）：**
+
+- `columns`：列定义（支持 ref/computed/function）
+- `storageKey`：本地缓存 key（建议业务传，避免 hash 变更影响）
+- `disabledColumns?`：禁止操作的列
+- `hiddenColumns?`：完全隐藏且不可操作的列
+- `size?`：表格密度（可选，参与缓存）
+- `persistOnChange?`：列变更时是否自动写缓存（默认 true；needConfirm 场景可设 false，最后手动 `persist()`）
+
+### useFilterTypeDisplay 筛选项显示设置 Hook
+
+用于 SearchPanel 的“筛选项显示/隐藏/排序”配置管理（存储与 ColumnSetting 类似）。
+
+```ts
+import { ref } from 'vue'
+import { useFilterTypeDisplay } from 'xdc-ui-lib'
+
+const storageKey = ref('search-panel:user-list')
+const filterTypes = ref<any[]>([
+  { id: 'name', label: '名称', type: 'input' },
+  { id: 'status', label: '状态', type: 'select' },
+])
+
+const {
+  selectedItems,
+  init,
+  toggleVisibility,
+  onCheckAllChange,
+  reset,
+} = useFilterTypeDisplay({
+  storageKey,
+  filterTypes,
+  disabledIds: ref(['name']),
+})
+
+init()
+```
+
+### 国际化（i18n）
+
+组件库内置了基础国际化能力（默认 `zh-CN`），并支持切换语言、以及由业务侧传入自定义语言包。
+
+```ts
+import { initI18n, setLocale, getLocale, setMessages, getMessages, zhCN, enUS } from 'xdc-ui-lib'
+
+// 1) 在 app.use(组件库) 前/后都可以初始化（组件库 install 内部也会默认 initI18n）
+initI18n({
+  locale: 'zh-CN',
+  // messages: 自定义语言包（可选）
+})
+
+// 2) 运行时切换语言
+setLocale('en-US')
+console.log(getLocale())
+
+// 3) 覆盖内置语言包（可选）
+setMessages({
+  ...zhCN,
+  // 按 LocaleMessages 结构补齐/覆盖字段
+} as any)
+
+console.log(getMessages())
+```
+
+**可用导出：**
+
+- `initI18n(options?)`
+- `setLocale(locale)` / `getLocale()`
+- `setMessages(messages)` / `getMessages()`
+- `zhCN` / `enUS` / `messages`
+- `useI18n()`：组件内部/业务侧均可使用（返回 `t(key)` 等）
+
+---
+
 ## 开发
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdc-ui-lib",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "常用组件库",
   "main": "xdc-ui-lib.js",
   "module": "xdc-ui-lib.js",