matrix_components 2.0.441 → 2.0.460

package/README.md

@@ -1,5 +1,16 @@
-# **组件库2.0**
-组件使用示例参考dist/ComponentDemo
+# Matrix Components 组件库
+
+## 简介
+
+Matrix Components 是一个功能丰富的 Vue 3 企业级组件库，提供办公文档预览、动态表单、视频播放、权限控制等完整解决方案。
+
+组件使用示例参考 `dist/ComponentDemo`
+
+## 📸 组件预览
+
+以下是组件库的架构和功能概览图：
+
+<iframe src="https://www.processon.com/embed/695db575faec1a656002a2ae" width="100%" height="80vh" frameborder="0" scrolling="no" style="min-height: 400px; max-height: 800px;"></iframe>
 
 ```
 version:2.0.440
@@ -152,7 +163,6 @@ version:2.0.308
 1.增加Demo示例目录：组件使用示例在dist/ComponentDemo
 ```
 
-
 ```
 version:2.0.305
 2025年10月21日15:05:11
@@ -240,6 +250,40 @@ version:2.0.292
 1.NsPdf预览组件支持搜索功能
 ```
 
+
+## 📊 功能特性总结
+
+### 组件功能
+
+- ✅ **NsOffice**: 办公文档统一预览（Excel/PDF/Word）
+- ✅ **NsForm**: 动态表单生成和管理
+- ✅ **NsVideo**: 专业视频播放器
+- ✅ **NsDialog**: 灵活弹窗对话框
+- ✅ **NsPdf**: PDF文档预览和搜索
+- ✅ **NsExcel**: Excel预览和编辑
+- ✅ **NsWord**: Word文档预览
+- ✅ **NsImage**: 图片预览
+- ✅ **NsMD**: Markdown编辑器
+- ✅ **NsSaturationline**: 浸润线
+- ✅ **NsAutoScreen**: 自适应屏幕工具
+
+### 指令功能
+
+- ✅ **v-permission**: 按钮权限控制
+- ✅ **v-length**: 输入长度和格式限制
+- ✅ **v-sline**: 单行文本省略
+- ✅ **v-event-unuse/use**: 事件穿透控制
+
+### 工具函数
+
+- ✅ **HTTP请求**: 完整的RESTful API封装
+- ✅ **资源加载**: 动态JS/CSS资源管理
+- ✅ **表格排序**: 表格排序功能
+- ✅ **SM2加密**: 国密算法加密
+- ✅ **CSS变量**: 主题样式管理
+- ✅ **通用工具**: 常用工具函数
+
+
 ## 创建公共组件库步骤
 
 - npm create vue@latest
@@ -264,7 +308,6 @@ version:2.0.292
   // 全局导入
   export default NsComponents
   ```
-
 - 子目录：NsXX目录，创建独立导出index.ts
 
   ```
@@ -277,7 +320,6 @@ version:2.0.292
   // 导出子组件
   export default NsXX
   ```
-
 - 配置package.json
 
   ```
@@ -305,7 +347,6 @@ version:2.0.292
     ...
   }
   ```
-
 - 配置vite.config.ts
 
   ```
@@ -344,13 +385,11 @@ version:2.0.292
     },
   }
   ```
-
 - 打包
 
   ```
    npm run build
   ```
-
 - 当前项目main.ts使用
 
   ```
@@ -363,7 +402,6 @@ version:2.0.292
   // app.use(NsXX)
 
   ```
-
 - 当前项目Test.vue使用
 
   ```
@@ -399,217 +437,693 @@ version:2.0.292
 
 ```
 
-### 1. 视频组件（NsVideo）
+## 📋 组件列表
+
+### 1. NsOffice - 办公文档统一预览组件
+
+支持格式：Excel(.xlsx/.xls)、PDF(.pdf)、Word(.docx/.doc)
+
+```vue
+<template>
+  <!-- 基础使用 -->
+  <NsOffice :url="fileUrl" />
+  
+  <!-- Excel编辑模式 -->
+  <NsOffice :url="excelUrl" :isEdit="true" />
+  
+  <!-- 获取组件引用 -->
+  <NsOffice ref="officeRef" :url="fileUrl" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NsOffice } from 'matrix_components'
+
+const officeRef = ref()
+
+// 获取文件类型
+const fileType = officeRef.value?.getFileType() // 'excel' | 'pdf' | 'word' | 'unsupported'
+
+// 获取当前激活的组件实例
+const activeComponent = officeRef.value?.getActiveComponent()
+
+// 刷新组件
+officeRef.value?.refresh()
+</script>
+```
+
+### 2. NsForm - 动态表单组件
+
+```vue
+<template>
+  <NsForm :rows="formConfig" ref="formRef" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NsForm } from 'matrix_components'
+
+const formRef = ref()
+const formConfig = [
+  {
+    key: 'name',
+    label: '姓名',
+    component: 'el-input',
+    props: { placeholder: '请输入姓名' }
+  },
+  {
+    key: 'age',
+    label: '年龄',
+    component: 'el-input-number',
+    props: { min: 0, max: 100 }
+  }
+]
+
+// 获取表单数据
+const formData = formRef.value?.getFormData()
+
+// 重置表单
+formRef.value?.resetForm()
+
+// 验证表单
+const isValid = formRef.value?.validate()
+</script>
+```
+
+### 3. NsVideo - 视频播放组件
+
+```vue
+<template>
+  <NsVideo 
+    ref="nsVideoRef" 
+    v-bind="videoData" 
+    v-on="videoEvent" 
+    @changeSplit='changeSplitHandler'
+  >
+    <!-- 自定义插槽 -->
+    <template #video-tree><span>左侧树-自定义插槽</span></template>
+    <template #video-player-head><span>播放区域头部-自定义插槽</span></template>
+    <template #video-player-view><span>播放区域主体-自定义插槽</span></template>
+    <template #video-player-foot><span>播放区域底部控制按钮-自定义插槽</span></template>
+    <template #video-player-cover><span>播放器canvas画布区域（除head+foot+tree区域）</span></template>
+  </NsVideo>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NsVideo } from 'matrix_components'
+
+const nsVideoRef = ref()
+
+// 视频配置数据
+const videoData = {
+  // 显示视频关闭按钮
+  showClose: true,
+  // 是否支持全屏
+  hasFullScreen: true,
+  // 显示树
+  showTree: true,
+  // 树数据
+  treeData: [
+    {
+      id: '1',
+      label: '分组1',
+      children: [
+        {
+          videoModel: 'easyplayer',
+          id: '111',
+          label: '视频A',
+          url: 'ws://example.com/rtp/video.live.flv',
+          deviceId: 'a1',
+          channelId: 'a11',
+          icontype: 'on',
+        }
+      ]
+    }
+  ],
+  // 树节点对应的key
+  treeNodeKey: 'id',
+  // 树节点展开的key
+  treeExpandedKeys: ['11'],
+  // 树节点属性
+  treeOptions: {
+    icontype: 'icontype',
+    background: 'background',
+    videoUrlKey: 'url',
+    children: 'children',
+    label: 'label',
+  },
+  // 获取、设置打开的播放视频信息
+  videoInfos: [
+    {
+      index: 0,
+      url: 'https://example.com/video.flv',
+      info: {
+        videoModel: 'easyplayer',
+        id: 'video1',
+        url: 'https://example.com/video.flv',
+        deviceId: 'c1',
+        channelId: 'c11',
+      },
+    }
+  ],
+  // 单点播放
+  videoSingleUrl: false,
+  // 已经在播放的是否关闭后再点击打开
+  videoSingleClose: false,
+  // 播放模式: 1: 单击,2: 双击
+  videoPlayModel: 1,
+  // 分屏模式: 1: 单屏, 2: 四屏, 3: 九屏
+  videoSplitType: 1,
+  // 显示分屏按钮
+  showVideoSplit: true,
+  // 显示方向控制按钮
+  showVideoCtrls: false,
+  // 禁止控制按钮默认请求行为
+  stopVideoCtrlMethods: true,
+  // 单个视频错误最大次数
+  videoErrorMaxCount: 3,
+  // easyplayer配置
+  videoConfig: {
+    MSE: true,
+    WCS: true,
+    WASM: true,
+    WASMSIMD: true,
+    isLive: true,
+    hasAudio: false,
+    stretch: false
+  },
+  // 事件回调
+  treeClick: () => { console.log('点击树节点') },
+  treeDBClick: () => { console.log('双击树节点') },
+  treeRightMenu: () => { console.log('右键树菜单') },
+  treeExpand: () => { console.log('展开树节点') },
+  videoError: () => { console.log('视频错误') },
+}
+
+// 视频操作事件
+const videoEvent = {
+  videoOriginalInfo: (info) => { console.log('视频原始信息:', info) },
+  up: () => { console.log('向上移动') },
+  down: () => { console.log('向下移动') },
+  left: () => { console.log('向左移动') },
+  right: () => { console.log('向右移动') },
+  zoomin: () => { console.log('放大') },
+  zoomout: () => { console.log('缩小') },
+  stop: () => { console.log('停止') },
+  speed: () => { console.log('设置速度') },
+  speak: () => { console.log('开始说话') },
+  scan: () => { console.log('扫描') },
+  cruise: () => { console.log('巡航') },
+  call: () => { console.log('调用') },
+}
 
+// 获取原始视频信息
+const videoInfo = nsVideoRef.value?.getOriginalInfo()
+
+// 设置视频URL
+nsVideoRef.value?.setVideoUrl('ws://example.com/rtp/video.live.flv', false, 1, {
+  videoModel: 'easyplayer'
+})
+
+// 移除视频
+nsVideoRef.value?.removeVideo(1, true)
+
+// 分屏变化回调
+function changeSplitHandler(num) {
+  console.log('分屏模式:', num)
+}
+</script>
 ```
-// 1. 复制播放器资源
-js文件夹 到 public/目录中
-cdn文件夹 到 public/目录中
 
-// 2. index.html中引入
+**前置准备：**
+
+1. 复制播放器资源：`js文件夹` 到 `public/` 目录中
+2. 复制播放器资源：`cdn文件夹` 到 `public/` 目录中
+3. 在 `index.html` 中引入：
+
+```html
 <script src="./js/EasyPlayer-pro.js"></script>
 <script src="./cdn/h5player/h5player.min.js"></script>
+```
 
-// 3.安装公共组件库 (安装过则无需安装)
-//@ts-ignore
-import NsComponents from 'matrix_components'
-import 'matrix_components/dist/matrix_components.css'
-app.use(NsComponents)
+### 4. NsDialog - 弹出框组件
+
+```javascript
+import { NsDialog, closeAllNsDialog } from 'matrix_components'
+
+// 打开对话框
+NsDialog({
+  title: '测试',
+  // 任何组件添加 $emit('close') 时，会触发关闭弹出框事件
+  dom: VideoDemo, // 也可以通过异步方式：import("@/views/VideoDemo.vue") 和 () => import("@/views/VideoDemo.vue")
+  option: {
+    // dom对应的自定义组件props属性
+    ...data,
+  },
+  events: {
+    // dom组件内部自定义事件emit('btnClick', xxx)
+    btnClick: () => {
+      console.log("点击中间区域内容");
+    },
+  },
+  modalColor: 'rgb(0 21 115 / 20%)', // 遮罩层颜色
+  width: '800px', // 宽度, 整个弹出框的高度，非内容高度
+  height: '450px', // 高度, 不配置则默认为内容高度
+  dialogPadding: [10, 20], // 弹窗内padding
+  showFooter: true, // 默认显示底部按钮
+  immediately: false, // true立即取消弹出框, false异步请求后取消弹出框，默认false
+  draggable: true, // 是否可拖拽，默认false
+
+  confirm: async (closeFn, componentRef, footerLoading) => { // 底部确认按钮回调事件
+    // componentRef可以调用内部函数，前提需要defineExpose
+    try{
+      const selectRows = componentRef?.value?.getSelectedRows();
+      console.log("点击确认，选择数据：", selectRows);
+    } catch(e) {
+      console.log(e)
+      await new Promise(resolve => setTimeout(resolve, 1000))
+    }
+    // footerLoading可以控制底部loading状态
+    if(footerLoading) {
+      footerLoading.value = false
+    }
+    // 请求数据，再关闭
+    if(closeFn) {
+      closeFn()
+    }
+  },
+  close: () => { // 关闭弹出时立即出发
+    console.log("点击关闭");
+  },
+  closed: () => { // 弹窗销毁时触发
+    console.log("完成关闭");
+  },
+  // 头部+底部自定义配置
+  headerDom: xxx,
+  headerOption: {},
+  headerEvents: {},
+  footerDom: yyy,
+  footerOption: {},
+  footerEvents: {},
+  // 底部按钮名称
+  footerTitle: {
+    close: "取消",
+    confirm: "确定",
+  },
+}, true, '#app') // true为是否遮罩（非必填）， '#app'为挂载点（非必填）
+
+// 关闭所有对话框
+closeAllNsDialog()
+```
+
+### 5. NsPdf - PDF预览组件
+
+```vue
+<template>
+  <NsPdf ref="pdfRef" :url="pdfUrl"></NsPdf>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NsPdf } from 'matrix_components'
+
+const pdfRef = ref()
+
+// 搜索关键词
+function searchKeyword() {
+  pdfRef.value?.search('关键词')
+}
+</script>
+```
+
+### 6. NsExcel - Excel预览/编辑组件
 
-// 4. 项目组件中引入视频组件, NsVideo组件配置参考NsVideo目录ReadMe.md和VideoDemo.vue
+```vue
 <template>
-    <NsVideo class="nsvideo" ref="nsVideoRef" v-bind="videoData" v-on="videoEvent" @changeSplit='changeSplitHandler'>
-      <!-- 自定义插槽
-      <template #video-tree><span>左侧树-自定义插槽</span></template>
-      <template #video-player-head><span>播放区域头部-自定义插槽</span></template>
-      <template #video-player-view><span>播放区域主体-自定义插槽</span></template>
-      <template #video-player-foot><span>播放区域底部控制按钮-自定义插槽</span></template>
-      -->
-    </NsVideo>
+  <NsExcel :url="excelUrl" :isEdit="true" />
 </template>
 ```
 
-### 2. 自适应函数（autoScaleInit）
+### 7. NsWord - Word预览组件
 
+```vue
+<template>
+  <NsWord :url="wordUrl" />
+</template>
+```
+
+### 8. NsImage - 图片预览组件
+
+```vue
+<template>
+  <NsImage :src="imageUrl" :defaultImg="defaultImage" />
+</template>
 ```
-// 1. 安装公共组件库 (安装过则无需安装)
-//@ts-ignore
-import NsComponents, { autoScaleInit } from 'matrix_components'
-import 'matrix_components/dist/matrix_components.css'
-app.use(NsComponents)
 
-// 2. 在main.t中初始化，建议在App创建之前
+### 9. NsMD - Markdown编辑器组件
+
+```vue
+<template>
+  <NsMD v-model="markdownContent" />
+</template>
+```
+
+### 10. NsSaturationline - 饱和度线组件
+
+```vue
+<template>
+  <NsSaturationline :data="saturationData" />
+</template>
+```
+
+### 11. NsAutoScreen - 自适应屏幕工具
+
+```javascript
+import { autoScaleInit, sacle_x, sacle_y } from 'matrix_components'
+
+// 初始化自适应
 autoScaleInit(document.querySelector('body'), {
-    designWidth: 1920,
-    designHeight: 920,
-    mode: 'stretch', // 可选 horizontal/vertical/stretch
+  designWidth: 1920,
+  designHeight: 920,
+  mode: 'stretch', // 可选 horizontal/vertical/stretch
 });
 
+// 获取缩放比例
+const scaleX = sacle_x()
+const scaleY = sacle_y()
 ```
 
-### 3. 弹出框组件（NsDialog）
+
+
+## 🔧 自定义指令
+
+### 1. v-permission - 按钮权限控制
+
+```vue
+<template>
+  <!-- 使用class控制权限，无权限时隐藏 -->
+  <el-button v-permission.class.display>查看</el-button>
+  
+  <!-- 使用id控制权限，无权限时隐藏 -->
+  <el-button v-permission.id>编辑</el-button>
+  
+  <!-- 默认使用id控制权限 -->
+  <el-button id="zuhu_list_add" v-permission>新增</el-button>
+</template>
+
+<script setup>
+// 权限配置（需要在引入组件库之前设置）
+import { createApp } from 'vue'
+
+const app = createApp(App)
+const btnsPermission = {
+  'zuhu_list_add': true, // 有权限
+  'zuhu_list_edit': false // 无权限
+}
+
+app.provide('btnsPermission', btnsPermission)
+app.use(NsComponents) // 引入组件库
+</script>
 ```
-import { NsDialog } from 'matrix_components'
-NsDialog({
-    title: '测试',
-    // 任何组件添加 $emit('close') 时，会触发关闭弹出框事件
-    dom: VideoDemo, // 也可以通过异步方式：import("@/views/VideoDemo.vue") 和 () => import("@/views/VideoDemo.vue")
-    option: {
-        // dom对应的自定义组件props属性
-        ...data,
-    },
-    events: {
-        // dom组件内部自定义事件emit('btnClick', xxx)
-        btnClick: () => {
-            console.log("点击中间区域内容");
-        },
-    },
-    modalColor: 'rgb(0 21 115 / 20%)', // 遮罩层颜色
-    width: '800px', // 宽度, 整个弹出框的高度，非内容高度
-    height: '450px', // 高度, 不配置则默认为内容高度
-    dialogPadding: [10, 20], // 弹窗内padding
-    showFooter: true, // 默认显示底部按钮
-    immediately: false, // true立即取消弹出框, false异步请求后取消弹出框，默认false
-    draggable: true, // 是否可拖拽，默认false
-
-    confirm: async (closeFn: any, componentRef: any, footerLoading: any) => { // 底部确认按钮回调事件
-        // 2.componentRef可以调用内部函数，前提需要defineExpose
-        try{
-          const selectRows = componentRef?.value?.getSelectedRows();
-          console.log("点击确认，选择数据：", selectRows);
-        } catch(e) {
-          console.log(e)
-          await new Promise(resolve => setTimeout(resolve, 1000))
-        }
-        // 3.footerLoading可以控制底部loading状态
-        if(footerLoading) {
-          footerLoading.value = false
-        }
-        // 1.请求数据，再关闭
-        if(closeFn) {
-          closeFn()
-        }
-    },
-    close: () => { // 关闭弹出时立即出发
-        console.log("点击关闭");
-    },
-    closed: () => { // 弹窗销毁时触发
-        console.log("完成关闭");
-    },
-    // 头部+底部自定义配置
-    // 任何组件添加 $emit('close') 时，会触发关闭弹出框事件
-    headerDom: xxx,
-    headerOption: {},
-    headerEvents: {},
-    // 任何组件添加 $emit('close') 时，会触发关闭弹出框事件
-    footerDom: yyy,
-    footerOption: {},
-    footerEvents: {},
-    // 底部按钮名称
-    footerTitle: {
-      close: "取消",
-      confirm: "确定",
-    },
-  }, true, '#app') // true为是否遮罩（非必填）， '#app'为挂载点（非必填）
+
+### 2. v-length - 输入长度限制
+
+```vue
+<template>
+  <!-- 限制最大长度50（默认） -->
+  <el-input v-length placeholder="请输入用户名" />
+  
+  <!-- 自定义长度限制 -->
+  <el-input v-length="100" placeholder="最多100字符" />
+  
+  <!-- 仅允许输入数字 -->
+  <el-input v-length.number="11" placeholder="请输入手机号" />
+  
+  <!-- 自定义正则表达式 -->
+  <el-input v-length.regex="{ maxLength: 10, pattern: /^[a-zA-Z]*$/ }" placeholder="仅允许字母" />
+  
+  <!-- 数字范围限制 -->
+  <el-input v-length.range="{ min: 0, max: 100, int: true, maxLength: 10 }" placeholder="0-100整数" />
+</template>
+```
+
+### 3. v-sline - 单行文本省略
+
+```vue
+<template>
+  <span v-sline>这是一段很长的文本内容，超出部分会自动显示省略号...</span>
+</template>
 ```
 
-### 4. 指令集（v-permission / v-length / v-event-unuse / v-event-use / v-sline）
+### 4. v-event-unuse / v-event-use - 事件穿透控制
+
+```vue
+<template>
+  <!-- 阻止事件穿透 -->
+  <div v-event-use>
+    <button>这个按钮可以点击</button>
+  </div>
+  
+  <!-- 允许事件穿透 -->
+  <div v-event-unuse>
+    <div>这个区域的事件会穿透到下层</div>
+  </div>
+</template>
 ```
-// 使用方法
-// 1. 按钮权限 v-permission.class.display / v-permission.id.display / v-permission.class / v-permission.id(默认)
-<button id="zuhu_list_add" v-permission>新增</button>
 
-// 使用按钮权限时，需要在外部项目中通过注入权限数据实现（注意：需要在引入公共组件库之前！！！）
-app.provide('btnsPermission', btnsPermission)
-// NsComponents为引入公共组件库
-app.use(NsComponents)
+## 🔧 工具函数
 
-// 2. 长度限制(默认50位)：v-length[.number][="100"]， 如：v-length.number="11" / v-length
-// .number 修饰符会限制只能输入数字（通过输入事件过滤非数字字符）
-<el-input placeholder="请输入手机号" v-length.number="11"/>
-<el-input placeholder="请输入用户名" v-length />
+### 1. 通用工具函数
 
-// 3. span单行显示并隐藏溢出文本： 'v-sline'
-<span v-sline >xxxx</span>
+```javascript
+import { isNotNull } from 'matrix_components'
+
+// 检查值是否非空
+const result = isNotNull(value) // 返回布尔值
+```
 
-// 4. 用在能点击下层事件时：event-use (阻止穿透事件) / event-unuse (穿透事件)
-<div v-event-use></div>
-<div>无法点击到</div>
+### 2. 动态资源加载
 
-<div v-event-unuse></div>
-<div>可以点击到</div>
+```javascript
+import { loadAccess, removeDynamicAccess } from 'matrix_components'
 
+// 加载JS/CSS资源
+await loadAccess('https://example.com/script.js', 'script-tag', false)
+
+// 移除动态加载的资源
+removeDynamicAccess('script-tag')
 ```
 
+### 3. CSS变量管理
+
+```javascript
+import { loadCssVars } from 'matrix_components'
 
-### 5. sm2加密（getEncryptSm2）
+// 获取所有CSS变量
+const cssVars = loadCssVars()
+console.log(cssVars['--matrix-primary-color'])
 ```
-// 使用方法
-import NsComponents, { getEncryptSm2 } from 'matrix_components'
-app.use(NsComponents)
-const encrypArrs = getEncryptSm2(publicKey, ["xxx", "yyy"], isAdd04=false, cipherMode=1)
 
+### 4. 表格排序工具
+
+```javascript
+import { handleSortChange, headerClick, handleHeaderCellClass } from 'matrix_components'
+
+// 在表格组件中使用
+<el-table
+  @sort-change="(sort) => handleSortChange(sort, searchForm, getList)"
+  @header-click="headerClick"
+  :header-cell-class-name="(params) => handleHeaderCellClass(params, searchForm)"
+>
+  <!-- 表格内容 -->
+</el-table>
 ```
 
-### 6. get/post请求（http/get）
+### 5. SM2加密工具
+
+```javascript
+import { getEncryptSm2 } from 'matrix_components'
+
+// 使用SM2加密
+const encrypted = getEncryptSm2(publicKey, ["xxx", "yyy"], isAdd04=false, cipherMode=1)
 ```
-// 使用方法
-// 1. main.ts中引入, 并指定app.config.globalProperties.$BaseUrl全局请求地址
+
+### 6. 动态表单工具函数
+
+```javascript
+import { 
+  useFileUpload, 
+  getAllFormNodeByKey, 
+  getAllFormKvData, 
+  getAllFormNodeRefByKey 
+} from 'matrix_components'
+
+// 表单文件上传hook
+const { uploadFile, deleteFile } = useFileUpload()
+
+// 根据key获取表单节点信息
+const formNode = getAllFormNodeByKey(formRows, 'username')
+
+// 获取表单所有键值对数据
+const formData = getAllFormKvData(formRows)
+
+// 根据key获取表单节点引用
+const nodeRef = getAllFormNodeRefByKey(formRows, 'username')
+```
+
+
+
+### 7. 屏幕自适应函数
+
+```javascript
+import { sacle_x, sacle_y, autoScaleInit } from 'matrix_components'
+
+// 初始化自适应
+autoScaleInit(document.querySelector('body'), {
+  designWidth: 1920,
+  designHeight: 920,
+  mode: 'stretch' // 可选 horizontal/vertical/stretch
+})
+
+// 获取当前缩放比例
+const scaleX = sacle_x()
+const scaleY = sacle_y()
+```
+
+## 🌐 HTTP请求函数
+
+### 1. 基础HTTP请求方法
+
+```javascript
+import { get, post, put, del, download, downLoadLocalFile, getTokenInfo } from 'matrix_components'
+
+// GET请求
+const result = await get('/api/users', { page: 1, size: 10 })
+
+// POST请求
+const result = await post('/api/users', { name: '张三', age: 25 })
+
+// PUT请求
+const result = await put('/api/users/1', { name: '李四', age: 30 })
+
+// DELETE请求
+const result = await del('/api/users/1')
+
+// 文件下载
+await download('/api/export', 'report.xlsx', 'get', { type: 'excel' })
+
+// 下载本地文件
+downLoadLocalFile('/public/', 'template.xlsx', 'template.xlsx')
+
+// 获取token信息
+const tokenInfo = getTokenInfo()
+```
+
+### 2. 初始化配置
+
+```javascript
+// main.ts中配置
+import { createApp } from 'vue'
 import NsComponents from 'matrix_components'
 
+const app = createApp(App)
+
 // 请求地址的baseUrl，建议在app.use(NsComponents)之前设置
-app.config.globalProperties.$BaseUrl = 'http://请求ip：端口/'
+app.config.globalProperties.$BaseUrl = 'http://api.example.com/'
+
 // 图片、文件请求地址的ImageBaseUrl，建议在app.use(NsComponents)之前设置
-app.config.globalProperties.$ImageBaseUrl = 'http://请求ip：端口/'
-app.use(NsComponents)
+app.config.globalProperties.$ImageBaseUrl = 'http://api.example.com/'
 
 // 【可选】401无权显示回调
-app.config.globalProperties.$LogoutCallback = logoutHandler // 无权显示回调
-// 【可选】请求添加的token头的key，默认为satoken。token的key和value需要在外部项目中自己设置
-sessionStorage.setItem('tokenName',  'xxx')
-sessionStorage.setItem('tokenValue', 'yyy')
+app.config.globalProperties.$LogoutCallback = logoutHandler
 
-// 2. xx.vue / xx.ts  调用获取get、post请求
-import { get, post } from 'matrix_components'
-export const login = (data) => post('/mag/AccAdmin/doLogin', data);
-```
+// 【可选】请求添加的token头的key，默认为satoken
+sessionStorage.setItem('tokenName', 'Authorization')
+sessionStorage.setItem('tokenValue', 'Bearer your-token-here')
 
-### 7. NsPdf组件
+app.use(NsComponents)
 ```
-// 使用方法
-import { NsPdf } from 'matrix_components'
-<NsPdf ref="pdfRef" :url="pdfUrl"></NsPdf>
-const pdfRef = ref()
 
-function searchKeyword() {
-  pdfRef.value?.search('人')
-}
+### 3. 实际使用示例
+
+```javascript
+// api/user.js
+import { get, post } from 'matrix_components'
+
+export const getUserList = (params) => get('/api/users', params)
+
+export const createUser = (data) => post('/api/users', data)
+
+export const updateUser = (id, data) => put(`/api/users/${id}`, data)
+
+export const deleteUser = (id) => del(`/api/users/${id}`)
+
+export const exportUsers = () => download('/api/users/export', 'users.xlsx')
 ```
 
-### 8. NsOffice组件
+## 🚀 完整安装和使用
+
+### 1. 安装依赖
+
+```bash
+# 安装Element Plus
+pnpm i element-plus
+
+# 安装组件库
+pnpm i matrix_components -S --registry=http://199.10.9.178:8081/repository/npm-group/
+
+# 如果安装失败，使用备用地址
+pnpm i matrix_components --registry=http://199.10.9.178:8081/repository/npm-hosted/
 ```
-// 统一的办公文档预览组件，根据文件URL自动选择合适的组件
-// 支持格式：Excel(.xlsx/.xls)、PDF(.pdf)、Word(.docx/.doc)
 
-// 使用方法
-import { NsOffice } from 'matrix_components'
+### 2. 全局引入
 
-// 基础使用
-<NsOffice :url="fileUrl" />
+```javascript
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
 
-// Excel编辑模式（仅对Excel文件有效）
-<NsOffice :url="excelUrl" :isEdit="true" />
+// 安装 Element-Plus
+import 'element-plus/dist/index.css'
+import ElementPlus from 'element-plus'
+import zhCn from 'element-plus/es/locale/lang/zh-cn'
 
-// 获取组件信息
-<NsOffice ref="officeRef" :url="fileUrl" />
-const officeRef = ref()
+// 安装组件库
+// @ts-ignore
+import NsComponents from 'matrix_components'
+import 'matrix_components/dist/matrix_components.css'
 
-// 获取文件类型
-const fileType = officeRef.value?.getFileType() // 'excel' | 'pdf' | 'word' | 'unsupported'
+const app = createApp(App)
+
+// 配置请求地址
+app.config.globalProperties.$BaseUrl = 'http://your-api-server/'
+app.config.globalProperties.$ImageBaseUrl = 'http://your-api-server/'
+
+app.use(ElementPlus, {
+  locale: zhCn,
+})
+app.use(NsComponents)
+
+app.mount('#app')
+```
+
+### 3. 按需引入
+
+```javascript
+// 按需引入组件和函数
+import { NsForm, NsVideo, get, post, autoScaleInit } from 'matrix_components'
+
+// 在组件中使用
+const app = createApp(App)
+app.use(NsForm)
+app.use(NsVideo)
+
+autoScaleInit(document.querySelector('body'), {
+  designWidth: 1920,
+  designHeight: 920,
+  mode: 'stretch'
+})
+```
 
-// 获取当前激活的组件实例
-const activeComponent = officeRef.value?.getActiveComponent()
 
-// 刷新组件
-officeRef.value?.refresh()
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matrix_components",
-  "version": "2.0.441",
+  "version": "2.0.460",
   "private": false,
   "type": "module",
   "files": [