@das-fed/web-components 7.0.10 → 7.1.0-dev.2

package/README.md

@@ -1,359 +1,104 @@
-## das-ce-tabs 使用方法
+# das-web-components 组件库说明文档
 
-1. **引入 `das-ce-tabs` 组件并注册**。
+## 一、简介
 
-```js
-import { createCeTabs } from '@das-fed/web-components'
-createCeTabs('das-ce-tabs')
-```
-
-2. **定义 `options` 和 `modelValue` 属性**。
+das-web-components 是 DAS 前端体系的 Web 组件库，基于 Web Components 技术，支持 Vue、React、原生 JS 等多种框架集成，适用于企业级中后台系统的统一架构和快速开发。
 
-`das-ce-tabs` 接收 `options` 和 `modelValue` 属性，`options` 属性配置如下：
-
-```js
-interface TabOption {
-  /** 唯一标识 */
-  key: string | number
-  /** 选项卡头显示文字 */
-  tab: string
-  /** 是否禁用 */
-  disabled?: boolean
-  /** 是否隐藏 */
-  hidden?: boolean
-  /** 被隐藏时是否渲染 DOM 结构 */
-  forceRender?: boolean
-  /** tab显示文字插槽 */
-  tabSlot?: string
-  /** 关闭图标插槽 */
-  closeIconSlot?: string
-  /** 显示内容插槽 */
-  contentSlot?: string
-}
-```
+---
 
-定义实例如下：
+## 二、核心组件与用法
 
-```js
-const activeKey = ref(1)
-
-const options = ref([
-  { key: 1, tab: 'Tab 1' },
-  { key: 2, tab: 'Tab 2', disabled: true },
-  { key: 3, tab: 'Tab 3' },
-])
-```
+### 1. das-ce-tabs 页签组件
 
-3. **监听组件事件**
+- 支持动态页签、右键菜单、刷新、全屏等功能。
+- 通过 `createCeTabs('das-ce-tabs')` 注册。
+- 主要属性：
+  - `options`：页签配置数组，支持禁用、隐藏、插槽等。
+  - `modelValue`：当前激活页签 key。
+- 主要事件：
+  - `update:modelValue`：切换页签时触发，返回新激活 key。
+  - `tabClick`：点击页签时触发，返回 key。
+  - `tabDelete`：删除页签时触发，返回 key。
+  - `menuClick`：右键菜单操作，返回操作项和页签对象。
+  - `pageRefresh`：点击刷新按钮时触发。
+  - `toggleFullScreen`：切换全屏。
+- 主要方法与类型定义见下方代码示例。
 
-使用组件时，监听到的事件对象为 `customEvent` ，该对象中的 `detail` 属性是个数组，数组元素为组件事件的返回值。 `das-ce-tabs` 组件暴露了以下事件：
-
-1. `update:modelValue`：当 `modelValue` 属性变化时触发，要实现切换页签时 `activeKey` 属性自动变化，需要监听该事件。
+#### 用法示例
 
 ```js
 import { ref } from 'vue'
-import { createCeTabs } from '@das-fed/web-/components'
-createCeTabs('das-ce-tabs')
-
-const activeKey = ref(1)
-
-const options = ref([
-  { key: 1, tab: 'Tab 1' },
-  { key: 2, tab: 'Tab 2', disabled: true },
-  { key: 3, tab: 'Tab 3' },
-])
-```
-
-```html
-<das-ce-tabs
-  :modelValue="activeKey"
-  :options="options"
-  @update:modelValue="(customEvent) => (activeKey = customEvent.detail[0])"
-></das-ce-tabs>
-```
-
-2. `tabClick`：当 `tab` 被点击时触发。返回被点击页签的 `key` 值。
-
-```js
-import { ref } from 'vue'
-import { createCeTabs } from '@das-fed/web-components/components'
-createCeTabs('das-ce-tabs')
-
-const activeKey = ref(1)
-
-const options = ref([
-  { key: 1, tab: 'Tab 1' },
-  { key: 2, tab: 'Tab 2', disabled: true },
-  { key: 3, tab: 'Tab 3' },
-])
-
-const tabClick = (customEvent) => {
-  console.log('当前点击页签的key: ', customEvent.detail[0])
-}
-```
-
-```html
-<das-ce-tabs :modelValue="activeKey" :options="options" @tabClick="tabClick"></das-ce-tabs>
-```
-
-3. `tabDelete`：当 `tab` 被删除时触发。返回被删除页签的 `key` 值。
-
-```js
-import { ref } from 'vue'
-import { createCeTabs } from '@das-fed/web-components/components'
-createCeTabs('das-ce-tabs')
-
-const activeKey = ref(1)
-
-const options = ref([
-  { key: 1, tab: 'Tab 1' },
-  { key: 2, tab: 'Tab 2', disabled: true },
-  { key: 3, tab: 'Tab 3' },
-])
-
-const tabDelete = (customEvent) => {
-  console.log('当前删除页签的key：', customEvent.detail[0])
-}
-```
-
-```html
-<das-ce-tabs :modelValue="activeKey" :options="options" @tabDelete="tabDelete"></das-ce-tabs>
-```
-
-4. `menuClick`：当右键呼出的操作项选中时触发。返回被选中的操作项和当前右键操作的页签对象。
-
-```js
-import { ref } from 'vue'
-import { createCeTabs } from '@das-fed/web-components/components'
+import { createCeTabs } from '@das-fed/web-components'
 createCeTabs('das-ce-tabs')
 
 const activeKey = ref(1)
-
 const options = ref([
   { key: 1, tab: 'Tab 1' },
   { key: 2, tab: 'Tab 2', disabled: true },
   { key: 3, tab: 'Tab 3' },
 ])
-
-const menuClick = (customEvent) => {
-  console.log('当前选中操作项：', customEvent.detail[0], '当前页签对象：', customEvent.detail[1])
-}
 ```
 
 ```html
 <das-ce-tabs :modelValue="activeKey" :options="options" @menuClick="menuClick"></das-ce-tabs>
 ```
 
-操作项定义如下：
+#### 事件与类型
 
 ```js
 interface MenuListType {
-  /** 唯一标识 */
   key: string | number
-  /** 操作项名称 */
   name: string
-  /** 是否隐藏 */
   hidden?: boolean | Function
-  /** 是否禁用 */
   disabled?: boolean | Function
 }
 ```
 
-5. `pageRefresh`: 当点击右侧刷新按钮时触发。无返回值。
-
-```js
-import { ref } from 'vue'
-import { createCeTabs } from '@das-fed/web-components/components'
-createCeTabs('das-ce-tabs')
-
-const activeKey = ref(1)
-
-const options = ref([
-  { key: 1, tab: 'Tab 1' },
-  { key: 2, tab: 'Tab 2', disabled: true },
-  { key: 3, tab: 'Tab 3' },
-])
-
-const pageRefresh = () => {
-  console.log('刷新')
-}
-```
-
-```html
-<das-ce-tabs :modelValue="activeKey" :options="options" @pageRefresh="pageRefresh"></das-ce-tabs>
-```
-
-6. `toggleFullScreen`: 切换全屏状态。无返回值。
-
-```js
-import { ref } from 'vue'
-import { createCeTabs } from '@das-fed/web-components/components'
-createCeTabs('das-ce-tabs')
-
-const activeKey = ref(1)
-
-const options = ref([
-  { key: 1, tab: 'Tab 1' },
-  { key: 2, tab: 'Tab 2', disabled: true },
-  { key: 3, tab: 'Tab 3' },
-])
-
-const toggleFullScreen = () => {
-  console.log('全屏')
-}
-```
+---
 
-```html
-<das-ce-tabs :modelValue="activeKey" :options="options" @toggleFullScreen="toggleFullScreen"></das-ce-tabs>
-```
+### 2. das-ce-nav 顶部导航栏组件
 
-## das-ce-nav 使用方法
+- 支持菜单、logo、搜索、用户信息、项目树、内置页面等多种功能。
+- 通过 `createCeNav('das-ce-nav')` 注册。
+- 主要属性：
+  - `modelValue`：当前选中菜单 key。
+  - `config`：导航栏配置。
+  - `logoUrl`、`searchConfig`、`userInfoConfig`、`projectTreeConfig`、`innerPagesConfig` 等。
+- 主要事件：
+  - `handleTabClick`、`handleTabDelete`、`changeInnerPage`、`searchToPage`、`clearSearchList`、`deleteSearchItem`、`userCommandHandle`、`changeTreeHandle`。
+- 详细属性与事件见下方表格。
 
-### 1. **引入 `das-ce-nav` 组件并注册**。
+#### 用法示例
 
 ```js
 import { createCeNav } from '@das-fed/web-components'
 createCeNav('das-ce-nav')
 ```
 
-#### ① 在 vue 文件中使用
-
 ```html
 <das-ce-nav
   @update:modelValue="(event) => (activeKey = event.detail[0])"
   :modelValue="activeKey"
-  @handleTabClick="handleTabClick"
-  @handleTabDelete="handleTabDelete"
   :config="config"
   :logoUrl="logoUrl"
   :searchConfig="searchConfig"
-  @searchToPage="searchToPage"
-  @clearSearchList="clearSearchList"
-  @deleteSearchItem="deleteSearchItem"
   :userInfoConfig="userInfoConfig"
-  @userCommandHandle="userCommandHandle"
   :projectTreeConfig="projectTreeConfig"
-  @changeTreeHandle="changeTreeHandle"
   :innerPagesConfig="innerPagesConfig"
-  @changeInnerPage="changeInnerPage"
 ></das-ce-nav>
 ```
 
-#### ① 在 html 文件中使用
-
-```html
-<head>
-  <script type="module">
-    import { createCeNav } from '@das-fed/web-components'
-    createCeNav('das-ce-nav')
-    const handleTabClick = (event) => {
-      console.log(event)
-    }
-    const dasceNavEle = document.getElementsByTagName('das-ce-nav')[0]
-    dasceNavEle.addEventListener('handleTabClick', handleTabClick)
-  </script>
-</head>
-<body>
-  <das-ce-nav
-    @update:modelValue="(event) => (activeKey = event.detail[0])"
-    :modelValue="activeKey"
-    :config="config"
-    :logoUrl="logoUrl"
-    :searchConfig="searchConfig"
-    :userInfoConfig="userInfoConfig"
-    :projectTreeConfig="projectTreeConfig"
-    :innerPagesConfig="innerPagesConfig"
-  ></das-ce-nav>
-</body>
-```
-
-### 2. **属性**
-
-| 属性名            | 描述          | 类型                                      | 默认值                                    | 是否必填 |
-| ----------------- | ------------- | ----------------------------------------- | ----------------------------------------- | -------- |
-| modelValue        | 当前选中菜单  | string/number                             | -                                         | 是       |
-| config            | 导航栏配置    | [config](###config)                       | [config](###config)                       | 是       |
-| logoUrl           | logo 图片链接 | string                                    | -                                         | 否       |
-| innerPagesConfig  | 内置页面配置  | [innerPagesConfig](###innerPagesConfig)   | [innerPagesConfig](###innerPagesConfig)   | 否       |
-| searchConfig      | 搜索配置      | [searchConfig](###searchConfig)           | [searchConfig](###searchConfig)           | 否       |
-| userInfoConfig    | 用户信息配置  | [userInfoConfig](###userInfoConfig)       | [userInfoConfig](###userInfoConfig)       | 否       |
-| projectTreeConfig | 项目树配置    | [projectTreeConfig](###projectTreeConfig) | [projectTreeConfig](###projectTreeConfig) | 否       |
-
-### config
-
-| 属性名          | 描述               | 类型                               | 默认值 | 是否必填 |
-| --------------- | ------------------ | ---------------------------------- | ------ | -------- |
-| showSearch      | 是否显示搜索       | bool                               | false  | 否       |
-| showProjectTree | 是否显示项目下拉树 | bool                               | false  | 否       |
-| subAppList      | 导航栏菜单数据     | {name:string,code:string/number}[] | -      | 否       |
-
-### innerPagesConfig
-
-| 属性名              | 描述               | 类型                            | 默认值 | 是否必填 |
-| ------------------- | ------------------ | ------------------------------- | ------ | -------- |
-| activeInnerPagePath | 内置菜单当前选中值 | string/number                   | false  | 否       |
-| innerPages          | 内置菜单数据       | {title: string, path: string}[] | false  | 否       |
-
-### searchConfig
-
-| 属性名         | 描述             | 类型                          | 默认值                      | 是否必填 |
-| -------------- | ---------------- | ----------------------------- | --------------------------- | -------- |
-| defaultProps   | -                | {value: string,label: string} | {value: 'id',label: 'name'} | 否       |
-| getHistoryList | 获取历史搜索记录 | () => Promise<any>            | -                           | 否       |
-| getSearchList  | 获取菜单         | () => Promise<any>            | -                           | 否       |
-| addHistory     | 添加历史记录     | (data:any) => void            | -                           | 否       |
-
-### userInfoConfig
-
-| 属性名        | 描述           | 类型                                               | 默认值 | 是否必填 |
-| ------------- | -------------- | -------------------------------------------------- | ------ | -------- |
-| headPicture   | 用户头像       | 默认头像                                           | 否     |
-| commandList   | 用户信息操作项 | () => Promise<any>                                 | -      | 否       |
-| getSearchList | 获取菜单       | {value?: string /number,label?: string / number}[] | -      | 否       |
-
-### projectTreeConfig
-
-| 属性名              | 描述                               | 类型                                                               | 默认值                      | 是否必填 |
-| ------------------- | ---------------------------------- | ------------------------------------------------------------------ | --------------------------- | -------- |
-| projectStore        | 项目数据                           | -                                                                  | 否                          |
-| defaultProps        | -                                  | {value: string,label: string}                                      | {value: 'id',label: 'name'} | 否       |
-| treeProps           | 树组件配置                         | [TreeOptionProps](###TreeOptionProps)                              | -                           | 否       |
-| filterNode          | 搜索过滤                           | (value: any, data: any) => [projectTreeType](###projectTreeType)[] | -                           | 否       |
-| filterFlatCondition | 树切换平铺，符合条件的加入平铺列表 | (data: any) => boolean[]                                           | -                           | 否       |
-
-### TreeOptionProps
-
-```js
-interface TreeOptionProps {
-  label?: string // 默认name
-  pathName?: string // 默认pathName
-  children?: string // 默认children
-  parentId?: string // 默认parentId
-  disabled?: string | ((data: TreeNodeData, node?: Node) => boolean) // 默认disabled
-  isLeaf?: string | ((data: TreeNodeData, node?: Node) => boolean) // 默认leaf;懒加载不支持方法
-  // 允许取消选中（keepSelected为true时生效）
-  allowUnSelect?: string | ((data: TreeNodeData) => boolean) // 默认allowUnSelect
-  class?: (
-    data: TreeNodeData,
-    node: Node,
-  ) =>
-    | string
-    | {
-        [key: string]: boolean
-      }
-    | string
-}
-```
-
-### projectTreeType
-
-| 属性名   | 描述                                       | 类型                                  | 默认值 | 是否必填 |
-| -------- | ------------------------------------------ | ------------------------------------- | ------ | -------- |
-| -        | 唯一标识（可使用 defaultProps.value 配置） | id                                    | 是     |
-| -        | 项目名称（可使用 defaultProps.label 配置） | name                                  | 是     |
-| children | 树组件配置                                 | [projectTreeType](###projectTreeType) | -      | 否       |
+#### 主要属性与事件
 
-### 3. **事件**
+| 属性名            | 描述          | 类型          | 是否必填 |
+| ----------------- | ------------- | ------------- | -------- |
+| modelValue        | 当前选中菜单  | string/number | 是       |
+| config            | 导航栏配置    | object        | 是       |
+| logoUrl           | logo 图片链接 | string        | 否       |
+| innerPagesConfig  | 内置页面配置  | object        | 否       |
+| searchConfig      | 搜索配置      | object        | 否       |
+| userInfoConfig    | 用户信息配置  | object        | 否       |
+| projectTreeConfig | 项目树配置    | object        | 否       |
 
 | 事件              | 说明                        | 回调参数                        |
 | ----------------- | --------------------------- | ------------------------------- |
@@ -366,17 +111,29 @@ interface TreeOptionProps {
 | userCommandHandle | 用户信息-操作项             | function(value:any)             |
 | changeTreeHandle  | 项目树-是否确定切换选中项目 | function(status:bool,value:any) |
 
-## das-ce-menu 使用方法
+---
+
+### 3. das-ce-menu 侧边菜单栏组件
+
+- 支持菜单折叠、选中、动态数据等功能。
+- 通过 `createCeMenu('das-ce-menu')` 注册。
+- 主要属性：
+  - `modelValue`：当前选中菜单 key。
+  - `data`：菜单数据数组。
+  - `collapse`：菜单栏初始折叠状态。
+- 主要事件：
+  - `change`：选中项改变时触发。
+  - `collapse-change`：菜单折叠状态改变时触发。
+- 主要方法：
+  - `changeCollapse`：切换菜单折叠状态。
 
-1. **引入 `das-ce-menu` 组件并注册**。
+#### 用法示例
 
 ```js
 import { createCeMenu } from '@das-fed/web-components'
 createCeMenu('das-ce-menu')
 ```
 
-2. **使用**。
-
 ```html
 <das-ce-menu
   :data="menuData"
@@ -388,23 +145,23 @@ createCeMenu('das-ce-menu')
 ></das-ce-menu>
 ```
 
-3. **属性**
+---
+
+## 三、组件属性与类型定义
+
+详细属性、类型定义和事件请参考源码及注释。
+
+---
 
-| 属性名     | 描述               | 类型          | 默认值 | 是否必填 |
-| ---------- | ------------------ | ------------- | ------ | -------- |
-| modelValue | 当前选中菜单       | string/number | -      | 是       |
-| data       | 导航栏配置         | array         | []     | 是       |
-| collapse   | 菜单栏初始折叠状态 | boolean       | false  | 否       |
+## 四、常见问题与扩展
 
-4. **事件**
+- 支持在 Vue、React、原生 JS 项目中直接注册和使用。
+- 组件事件均通过 `customEvent.detail` 获取返回值。
+- 支持自定义插槽、动态数据、复杂交互。
+- 推荐结合 DAS Web 主应用统一布局和微前端架构使用。
 
-| 事件            | 描述             | 回调参数                                    |
-| --------------- | ---------------- | ------------------------------------------- |
-| change          | 选中项改变触发   | function(value: string/number, option: any) |
-| collapse-change | 折叠状态改变触发 | function(value:boolean)                     |
+---
 
-5. **方法**
+## 五、贡献与维护
 
-| 方法           | 描述         | 参数                           |
-| -------------- | ------------ | ------------------------------ |
-| changeCollapse | 切换折叠状态 | 接收一个布尔类型参数：折叠状态 |
+如需详细 API 说明、组件开发指南，请参考源码及注释。