@jari-ace/element-plus-component 0.3.4 → 0.4.1

package/packages/components/radioGroup/README.md

@@ -0,0 +1,24 @@
+# JaRadioGroup 单选框组组件
+
+`JaRadioGroup` 是对 Element Plus `ElRadioGroup` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中创建单选框组，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElRadioGroup](https://element-plus.org/zh-CN/component/radio.html#radiogroup-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElRadioGroup 属性 |
+
+## 使用示例
+
+```vue
+<ja-radio-group>
+  <el-radio :label="3">Option A</el-radio>
+  <el-radio :label="6">Option B</el-radio>
+</ja-radio-group>
+```

package/packages/components/scrollbar/README.md

@@ -0,0 +1,23 @@
+# Scrollbar 滚动条组件
+
+`Scrollbar` 是对 Element Plus `ElScrollbar` 的扩展，支持可视区域检测（Intersection Observer）。
+
+## 组件用途
+
+用于内容滚动，并支持检测子元素是否在可视区域内（用于懒加载等场景）。
+
+## 属性 API
+
+该组件继承了 [ElScrollbar](https://element-plus.org/zh-CN/component/scrollbar.html#scrollbar-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElScrollbar 属性 |
+
+## 使用示例
+
+```vue
+<scrollbar height="400px">
+  <div v-for="item in 100" :key="item">{{ item }}</div>
+</scrollbar>
+```

package/packages/components/scrollbar/Scrollbar.vue

@@ -1,11 +1,18 @@
 <script setup lang="ts">
 import {ElScrollbar} from "element-plus";
-import {nextTick, onMounted, onUnmounted, provide, type Ref, ref, watch} from "vue";
+import type { ScrollbarProps } from "element-plus";
+import {nextTick, onMounted, onUnmounted, provide, type Ref, ref, watch, computed} from "vue";
 import {
     SCROLL_BAR_WRAPPED_INJECT_KEY,
     type ScrollbarWrapped
 } from "./utils";
 
+export interface JaScrollbarProps extends Partial<ScrollbarProps> {
+    // Custom props if any
+}
+
+const props = defineProps<JaScrollbarProps>()
+
 const scroll = ref<InstanceType<typeof ElScrollbar>>();
 const wrappedItems: Ref<ScrollbarWrapped[]> = ref([]);
 const wrappedItemsMap: Map<Element, ScrollbarWrapped> = new Map();
@@ -35,7 +42,7 @@ const observer = new IntersectionObserver((entries) => {
 async function observeWrappedItemInView() {
     await nextTick();
     const wrap = scroll.value?.$el;
-    if (!wrappedItems.value) return;
+    if (!wrappedItems.value || !wrap) return;
     try {
         for (let i = 0; i < wrappedItems.value.length; i++) {
             if (wrappedItems.value[i]) {
@@ -74,11 +81,15 @@ onUnmounted(() => {
     })
 })
 
+const elementProps = computed(() => {
+    return props
+})
+
 </script>
 
 <template>
     <el-scrollbar ref="scroll" class="scroll-container"
-                  v-bind="$attrs">
+                  v-bind="{ ...elementProps, ...$attrs }">
         <template v-for="(_, name) in $slots" v-slot:[name]>
             <slot :name="name"></slot>
         </template>

package/packages/components/select/JaSelect.vue

@@ -1,36 +1,48 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, ref, watch} from "vue";
+import {inject, ref, watch, computed} from "vue";
 import {ElSelect} from "element-plus";
+import type { SelectProps } from 'element-plus'
 import type {EpPropFinalized} from "element-plus/es/utils";
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const input = ref<typeof ElSelect>({} as typeof ElSelect)
+const input = ref<InstanceType<typeof ElSelect>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
 const emit = defineEmits<{
-    change: [value: string]
+    change: [value: any]
 }>()
 
-function onChange(value: string) {
+export interface JaSelectProps extends Partial<SelectProps> {
+}
+
+const props = defineProps<JaSelectProps>()
+
+function onChange(value: any) {
     validator.removeFieldError(prop)
     setValue(model.formData, prop, mv.value);
     emit('change', value)
 }
 
-type modelType = EpPropFinalized<(ArrayConstructor | ObjectConstructor | NumberConstructor | BooleanConstructor | StringConstructor)[], unknown, unknown, undefined, boolean>;
+// type modelType = EpPropFinalized<(ArrayConstructor | ObjectConstructor | NumberConstructor | BooleanConstructor | StringConstructor)[], unknown, unknown, undefined, boolean>;
+type ModelType = any; // Select value can be complex
 
-const mv = ref(getValue(model.formData, prop) as modelType);
+const mv = ref(getValue(model.formData, prop) as ModelType);
 watch(() => model.formData, () => {
-    mv.value = getValue(model.formData, prop) as modelType
+    mv.value = getValue(model.formData, prop) as ModelType
 }, {
     deep: true
 })
 
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props as any
+    return rest
+})
+
 defineExpose({
-    focus: () => input.value.focus(),
-    blur: () => input.value.blur(),
+    focus: () => input.value?.focus?.(),
+    blur: () => input.value?.blur?.(),
     elSelect: input
 })
 </script>
@@ -40,7 +52,7 @@ defineExpose({
         ref="input"
         v-model="mv"
         @change="onChange"
-        v-bind="$attrs">
+        v-bind="{ ...elementProps, ...$attrs }">
         <template v-for="(_, name) in $slots" v-slot:[name]>
             <slot :name="name"></slot>
         </template>

package/packages/components/select/README.md

@@ -0,0 +1,24 @@
+# JaSelect 选择器组件
+
+`JaSelect` 是对 Element Plus `ElSelect` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中进行选择，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElSelect](https://element-plus.org/zh-CN/component/select.html#select-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElSelect 属性 |
+
+## 使用示例
+
+```vue
+<ja-select>
+  <el-option label="Zone 1" value="shanghai" />
+  <el-option label="Zone 2" value="beijing" />
+</ja-select>
+```

package/packages/components/switch/JaSwitch.vue

@@ -1,11 +1,12 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, ref, watch} from "vue";
+import {inject, ref, watch, computed} from "vue";
 import {ElSwitch} from "element-plus";
+import type { SwitchProps } from 'element-plus'
 import {getValue, setValue} from "../../utils/objectUtils";
 import type {EpPropMergeType} from "element-plus/es/utils";
 
-const input = ref<typeof ElSwitch>()
+const input = ref<InstanceType<typeof ElSwitch>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
@@ -13,6 +14,11 @@ const emit = defineEmits<{
     change: [value: boolean | string | number]
 }>()
 
+export interface JaSwitchProps extends Partial<SwitchProps> {
+}
+
+const props = defineProps<JaSwitchProps>()
+
 function onChange(value: boolean | string | number) {
     validator.removeFieldError(prop)
     setValue(model.formData, prop, mv.value);
@@ -30,9 +36,14 @@ watch(() => model.formData, () => {
     deep: true
 })
 
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props
+    return rest
+})
+
 defineExpose({
-    focus: () => input.value?.focus(),
-    blur: () => input.value?.blur(),
+    focus: () => (input.value as any)?.focus?.(),
+    blur: () => (input.value as any)?.blur?.(),
     elSwitch: input
 })
 </script>
@@ -42,7 +53,7 @@ defineExpose({
         ref="input"
         v-model="mv"
         @change="onChange"
-        v-bind="$attrs">
+        v-bind="{ ...elementProps, ...$attrs }">
         <template v-for="(_, name) in $slots" v-slot:[name]>
             <slot :name="name"></slot>
         </template>

package/packages/components/switch/README.md

@@ -0,0 +1,21 @@
+# JaSwitch 开关组件
+
+`JaSwitch` 是对 Element Plus `ElSwitch` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中切换状态，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElSwitch](https://element-plus.org/zh-CN/component/switch.html#switch-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElSwitch 属性 |
+
+## 使用示例
+
+```vue
+<ja-switch />
+```

package/packages/components/timePicker/JaTimePicker.vue

@@ -1,10 +1,11 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, onMounted, ref, watch} from "vue";
+import {inject, onMounted, ref, watch, computed} from "vue";
 import {ElTimePicker} from "element-plus";
+import type { TimePickerDefaultProps } from 'element-plus'
 import {getValue, setValue} from "../../utils/objectUtils";
 
-const input = ref<typeof ElTimePicker>({} as typeof ElTimePicker)
+const input = ref<InstanceType<typeof ElTimePicker>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
@@ -12,6 +13,11 @@ const emit = defineEmits<{
     change: [value: string]
 }>()
 
+export interface JaTimePickerProps extends Partial<TimePickerDefaultProps> {
+}
+
+const props = defineProps<JaTimePickerProps>()
+
 const exposeMethods = ref<any>({})
 
 function onChange(value: string) {
@@ -20,7 +26,7 @@ function onChange(value: string) {
     emit('change', value);
 }
 
-type ModelType = string | number | object;
+type ModelType = string | number | object | any;
 
 const mv = ref(getValue(model.formData, prop) as ModelType);
 watch(() => model.formData, () => {
@@ -29,11 +35,18 @@ watch(() => model.formData, () => {
     deep: true
 })
 
+const elementProps = computed(() => {
+    const { modelValue, ...rest } = props
+    return rest
+})
+
 onMounted(() => {
-    const refMethods = Object.entries(input.value).filter(([_, v]) => v instanceof Function);
-    refMethods.forEach(([key, val]) => {
-        exposeMethods.value[key] = val;
-    })
+    if (input.value) {
+        const refMethods = Object.entries(input.value).filter(([_, v]) => v instanceof Function);
+        refMethods.forEach(([key, val]) => {
+            exposeMethods.value[key] = val;
+        })
+    }
 })
 
 defineExpose(exposeMethods.value);
@@ -44,7 +57,7 @@ defineExpose(exposeMethods.value);
         ref="input"
         v-model="model.formData[prop]"
         @change="onChange"
-        v-bind="$attrs">
+        v-bind="{ ...elementProps, ...$attrs }">
         <template v-for="(_, name) in $slots" v-slot:[name]>
             <slot :name="name"></slot>
         </template>

package/packages/components/timePicker/README.md

@@ -0,0 +1,21 @@
+# JaTimePicker 时间选择器组件
+
+`JaTimePicker` 是对 Element Plus `ElTimePicker` 的封装，集成了 `JaForm` 表单上下文注入。
+
+## 组件用途
+
+用于在 `JaForm` 中选择时间，自动绑定数据模型。
+
+## 属性 API
+
+该组件继承了 [ElTimePicker](https://element-plus.org/zh-CN/component/time-picker.html#timepicker-attributes) 的所有属性。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| - | - | - | 支持所有 ElTimePicker 属性 |
+
+## 使用示例
+
+```vue
+<ja-time-picker placeholder="Arbitrary time" />
+```

package/packages/components/tip/README.md

@@ -0,0 +1,20 @@
+# AceTip 提示组件
+
+`AceTip` 是一个简单的提示信息展示组件。
+
+## 组件用途
+
+用于显示警告、提示或说明信息。
+
+## 属性 API
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `type` | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'primary'` | 提示类型（颜色） |
+| `text` | `string` | `''` | 提示文本 |
+
+## 使用示例
+
+```vue
+<ace-tip type="warning" text="请注意，此操作不可逆！" />
+```

package/packages/components/tip/src/AceTip.vue

@@ -14,10 +14,18 @@
 </template>
 
 <script setup lang="ts">
-const props = withDefaults(defineProps<{
+export interface AceTipProps {
+    /**
+     * 提示类型
+     */
     type?: "primary" | "success" | "warning" | "danger" | "info";
+    /**
+     * 提示文本
+     */
     text?: string;
-}>(), {
+}
+
+const props = withDefaults(defineProps<AceTipProps>(), {
     type: "primary",
     text: "",
 });

package/packages/components/upload/FilePreviewer.vue

@@ -0,0 +1,245 @@
+<!--
+  - 版权所有 (c) 2026 江苏杰瑞信息科技有限公司
+  -
+  - 此文件属于JARI.ACE平台项目，修改、分发必须遵守杰瑞信科商业软件许可协议
+  -
+  -->
+
+<!--
+ * FilePreviewer 组件
+ *
+ * 用途：用于根据 attachToken 预览附件列表中的第一个可预览文件
+ *
+ * 功能特点：
+ * - 自动获取附件列表并识别可预览文件
+ * - 支持多种文件格式预览（PDF、Office文档、图片等）
+ * - 使用 Element Plus 按钮组件，支持完整的外观自定义
+ * - 集成 PdfViewerModal 进行文件预览
+ *
+ * 使用示例：
+ *
+ * 基础用法：
+ * <FilePreviewer attachToken="your-attach-token" />
+ *
+ * 自定义按钮外观：
+ * <FilePreviewer
+ *   attachToken="your-attach-token"
+ *   buttonType="primary"
+ *   buttonSize="medium"
+ *   buttonText="查看文件"
+ *   buttonIcon="View"
+ * />
+ *
+ * 高级自定义：
+ * <FilePreviewer
+ *   attachToken="your-attach-token"
+ *   buttonClass="my-custom-button"
+ *   buttonRound
+ *   buttonPlain={false}
+ * />
+-->
+
+<script setup lang="ts">
+import {createAxiosWithoutCache, type FileInfo, useFilesApi} from "@jari-ace/app-bolts";
+import {computed, ref} from "vue";
+import {ElButton} from "element-plus";
+import PdfViewerModal from "./pdf-viewer/PdfViewerModal.vue";
+
+/**
+ * FilePreviewer 组件属性定义
+ *
+ * @property {string} attachToken - 附件令牌，用于获取文件列表（必需）
+ * @property {string} [buttonType='warning'] - 按钮类型，可选值：primary/success/warning/danger/info
+ * @property {string} [buttonSize='small'] - 按钮尺寸，可选值：large/medium/small
+ * @property {boolean} [buttonPlain=true] - 是否使用朴素按钮样式
+ * @property {boolean} [buttonRound=false] - 是否圆角按钮
+ * @property {boolean} [buttonCircle=false] - 是否圆形按钮
+ * @property {boolean} [buttonDisabled=false] - 按钮是否禁用
+ * @property {any} [buttonIcon] - 按钮图标，可以是 Element Plus 图标组件
+ * @property {string} [buttonText='预览'] - 按钮文本内容
+ * @property {string} [buttonClass] - 自定义按钮 CSS 类名
+ */
+const props = defineProps<{
+    /**
+     * 附件令牌
+     */
+    attachToken: string,
+    /**
+     * 按钮类型
+     */
+    buttonType?: 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'text' | 'default',
+    /**
+     * 按钮尺寸
+     */
+    buttonSize?: string,
+    /**
+     * 按钮是否朴素
+     */
+    buttonPlain?: boolean,
+    /**
+     * 按钮是否圆角
+     */
+    buttonRound?: boolean,
+    /**
+     * 按钮是否圆形
+     */
+    buttonCircle?: boolean,
+    /**
+     * 按钮是否禁用
+     */
+    buttonDisabled?: boolean,
+    /**
+     * 按钮图标
+     */
+    buttonIcon?: any,
+    /**
+     * 按钮文本
+     */
+    buttonText?: string,
+    /**
+     * 按钮类名
+     */
+    buttonClass?: string,
+}>();
+
+/**
+ * 组件内部状态管理
+ */
+const axios = createAxiosWithoutCache();
+const api = useFilesApi(axios);
+const files = ref<FileInfo[]>([]); // 存储文件列表
+const pdfViewerVisible = ref(false); // 控制 PDF 查看器模态框显示
+const pdfSrc = ref(""); // PDF 文件源地址
+const loading = ref(false); // 加载状态
+
+/**
+ * 按钮属性计算属性
+ * 用于处理 Element Plus 按钮的类型安全
+ */
+const buttonProps = computed(() => (
+    {
+        type: (
+            props.buttonType || 'warning'
+        ) as any,
+        size: (
+            props.buttonSize || 'small'
+        ) as any
+    }
+));
+
+/**
+ * 可预览文件扩展名列表
+ * 支持多种文档格式：Office文档、PDF、图片、文本等
+ */
+const previewableFileExts = [".doc", ".docx", ".xls", ".xlsx", ".wps", ".et",
+    ".csv", ".txt", ".rtf", ".odt", "ods", ".mht", ".ppt", ".pptx", ".odp", ".pdf", "xps", "."];
+
+/**
+ * 计算属性：检查是否存在可预览的文件
+ * 遍历文件列表，检查是否有文件扩展名在可预览列表中
+ */
+const hasPreviewableFiles = computed(() => {
+    return files.value.some(file => previewableFileExts.some(ext => file.fileName.endsWith(ext)));
+});
+
+/**
+ * 计算属性：获取第一个可预览的文件
+ * 用于确定要预览哪个文件
+ */
+const firstPreviewableFile = computed(() => {
+    return files.value.find(file => previewableFileExts.some(ext => file.fileName.endsWith(ext)));
+});
+
+/**
+ * 加载文件列表
+ * 根据 attachToken 从服务器获取关联的文件列表
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+async function loadFileInfos() {
+    if (!props.attachToken) {
+        files.value = [];
+        return;
+    }
+
+    try {
+        loading.value = true;
+        files.value = await api.getFileList(props.attachToken);
+    } catch (error) {
+        console.error('Failed to load file list:', error);
+        files.value = [];
+    } finally {
+        loading.value = false;
+    }
+}
+
+/**
+ * 预览第一个可预览的文件
+ * 构建预览 URL 并显示 PDF 查看器模态框
+ *
+ * @returns {void}
+ */
+function previewFirstFile() {
+    const file = firstPreviewableFile.value;
+    if (!file) {
+        console.warn('No previewable files found');
+        return;
+    }
+
+    // 构建预览 URL，使用文件 token 或 ID
+    pdfSrc.value = new URL("uploads/preview/" + (
+        file.token || file.id
+    ), location.origin).toString();
+    pdfViewerVisible.value = true;
+}
+
+/**
+ * 组件初始化
+ * 自动加载文件列表
+ */
+loadFileInfos();
+</script>
+
+<template>
+    <div class="file-previewer">
+        <!--
+         * 预览按钮
+         * 支持完整的 Element Plus 按钮属性自定义
+         * 当没有可预览文件时会自动禁用
+         * 点击时触发 previewFirstFile 函数
+         -->
+        <ElButton
+            :type="buttonProps.type"
+            :size="buttonProps.size"
+            :plain="buttonPlain !== undefined ? buttonPlain : true"
+            :round="buttonRound"
+            :circle="buttonCircle"
+            :loading="loading"
+            :disabled="buttonDisabled || !hasPreviewableFiles"
+            :icon="buttonIcon"
+            :class="buttonClass"
+            @click="previewFirstFile"
+            link>
+            {{ buttonText || '预览' }}
+        </ElButton>
+
+        <!--
+         * PDF 查看器模态框
+         * 用于显示可预览文件的内容
+         * 支持全屏显示和响应式布局
+         -->
+        <PdfViewerModal :src="pdfSrc" v-model="pdfViewerVisible"></PdfViewerModal>
+    </div>
+</template>
+
+<style lang="scss" scoped>
+/**
+ * FilePreviewer 组件样式
+ * 使用内联块级显示，使按钮可以与其他元素并排显示
+ * 保持简洁的样式，让按钮本身的样式起主导作用
+ */
+.file-previewer {
+    display: inline-block;
+}
+</style>

package/packages/components/upload/JaUploader.vue

@@ -1,9 +1,10 @@
 <script setup lang="ts">
 import type {ValidationInstance} from '../../hooks/useBackendValidations'
-import {inject, ref, watch} from "vue";
+import {inject, ref, watch, computed} from "vue";
 import {getValue, setValue} from "../../utils/objectUtils";
 import Uploader from "./uploader.vue";
-const props = defineProps<{
+
+export interface JaUploaderProps {
     /**
      * 应用名
      */
@@ -17,7 +18,7 @@ const props = defineProps<{
      */
     attachToken?: string,
     /**
-     * 数据密集
+     * 数据密级
      */
     classificationLevel?: number,
     /**
@@ -28,8 +29,10 @@ const props = defineProps<{
      * 文件列表最大高度
      */
     maxHeight?: string | number
-}>();
-const input = ref<typeof Uploader>({} as typeof Uploader)
+}
+
+const props = defineProps<JaUploaderProps>();
+const input = ref<InstanceType<typeof Uploader>>()
 const model = inject('aceFormModel') as Record<string, any>
 const prop = inject('aceFormItemProp') as string
 const validator = inject('aceFormValidator') as ValidationInstance
@@ -53,9 +56,7 @@ watch(() => model.formData, () => {
 })
 
 defineExpose({
-    focus: () => input.value.focus(),
-    blur: () => input.value.blur(),
-    elSelect: input
+    uploader: input
 })
 </script>