@ticatec/batch-data-uploader 0.0.3 → 0.0.9

package/dist/i18n_resources/batch_en_resource.d.ts

@@ -13,9 +13,14 @@ declare const langRes: {
             upload: string;
             save: string;
             open: string;
+            confirm: string;
         };
         errorTitle: string;
         sheetName: string;
+        labelStatus: string;
+        labelValid: string;
+        textValid: string;
+        textInvalid: string;
     };
 };
 export default langRes;

package/dist/i18n_resources/batch_en_resource.js

@@ -1,21 +1,26 @@
 const langRes = {
     batchUploading: {
         status: {
-            pending: 'To upload',
+            pending: "To upload",
             uploading: "Uploading...",
-            successful: 'Success',
-            fail: 'Failure'
+            successful: "Success",
+            fail: "Failure"
         },
-        parsing: 'Parsing file...',
-        parseFailure: 'Cannot parse file: {{name}}',
-        waitUploading: 'Cannot exit on uploading!',
+        parsing: "Parsing file...",
+        parseFailure: "Cannot parse file: {{name}}",
+        waitUploading: "Cannot exit during uploading!",
         button: {
-            upload: 'Upload',
-            save: 'Error data',
-            open: 'File'
+            upload: "Upload",
+            save: "Save error data",
+            open: "Open",
+            confirm: "Confirm"
         },
-        errorTitle: 'Error',
-        sheetName: 'Abnormal data'
+        errorTitle: "Error",
+        sheetName: "Abnormal data",
+        labelStatus: "Status",
+        labelValid: "Validity",
+        textValid: "Yes",
+        textInvalid: "No"
     }
 };
 export default langRes;

package/dist/i18n_resources/i18nKeys.d.ts

@@ -17,6 +17,14 @@ declare const i18nKeys: {
             text: string;
         };
     };
+    labelValid: {
+        key: string;
+        text: string;
+    };
+    labelStatus: {
+        key: string;
+        text: string;
+    };
     parsing: {
         key: string;
         text: string;
@@ -42,6 +50,10 @@ declare const i18nKeys: {
             key: string;
             text: string;
         };
+        confirm: {
+            key: string;
+            text: string;
+        };
     };
     errorTitle: {
         key: string;
@@ -51,5 +63,13 @@ declare const i18nKeys: {
         key: string;
         text: string;
     };
+    textValid: {
+        key: string;
+        text: string;
+    };
+    textInvalid: {
+        key: string;
+        text: string;
+    };
 };
 export default i18nKeys;

package/dist/i18n_resources/i18nKeys.js

@@ -18,6 +18,14 @@ const i18nKeys = {
             text: langRes.batchUploading.status.fail
         }
     },
+    labelValid: {
+        key: 'batchUploading.labelValid',
+        text: langRes.batchUploading.labelValid
+    },
+    labelStatus: {
+        key: 'batchUploading.labelStatus',
+        text: langRes.batchUploading.labelStatus
+    },
     parsing: {
         key: 'batchUploading.parsing',
         text: langRes.batchUploading.parsing
@@ -42,6 +50,10 @@ const i18nKeys = {
         open: {
             key: 'batchUploading.button.open',
             text: langRes.batchUploading.button.open
+        },
+        confirm: {
+            key: 'batchUploading.button.confirm',
+            text: langRes.batchUploading.button.confirm
         }
     },
     errorTitle: {
@@ -51,6 +63,14 @@ const i18nKeys = {
     sheetName: {
         key: 'batchUploading.sheetName',
         text: langRes.batchUploading.sheetName
+    },
+    textValid: {
+        key: 'batchUploading.textValid',
+        text: langRes.batchUploading.textValid
+    },
+    textInvalid: {
+        key: 'batchUploading.textInvalid',
+        text: langRes.batchUploading.textInvalid
     }
 };
 export default i18nKeys;

package/documents/BaseEncodingTemplate.md

@@ -0,0 +1,156 @@
+# BaseEncodingTemplate Class
+
+An abstract base class for parsing Excel files, encoding data, and performing validation, extending `BaseTemplate`, with support for data validity checks and column expansion.
+
+## [BaseTemplate](./BaseTemplate.md)
+
+## Overview
+
+The `BaseEncodingTemplate` class extends `BaseTemplate`, adding data validity verification and encoding functionality. It supports parsing Excel files, validating the legitimacy of each row of data, and implementing custom data encoding logic through subclasses. The class adds a column to display data validity (showing "Valid" or "Invalid" status).
+
+## Usage
+
+To use `BaseEncodingTemplate`, you must extend the class and implement the `isRowValid`, `encodeData` methods, and the `valid` property. Below is an example:
+
+```typescript
+import BaseEncodingTemplate from './BaseEncodingTemplate';
+import type { DataColumn } from './DataColumn';
+
+const columns: DataColumn[] = [
+    {
+        field: 'user.name',
+        text: 'Name',
+        width: 150,
+        parser: (value) => String(value).trim()
+    },
+    {
+        field: 'user.age',
+        text: 'Age',
+        width: 100,
+        parser: (value) => Number(value) || 0
+    }
+];
+
+class MyEncodingTemplate extends BaseEncodingTemplate {
+    constructor() {
+        super(columns, rowOffset);
+    }
+
+    protected isRowValid(row: any): boolean {
+        return row.id != null;
+    }
+
+    protected async encodeData(rows: Array<any>): Promise<Array<any>> {
+        // Implement data encoding logic, e.g., calling an API and replacing or merging with local data
+        return rows.map(item => ({ ...item, encoded: true }));
+    }
+
+    get valid(): boolean {
+        // Check if the entire dataset is valid
+        return this._list.filter(item => item.id == null).length > 0;
+    }
+}
+```
+
+### Parsing Excel Files
+
+```typescript
+const file: File = // ... Obtain the file (e.g., from an input element)
+const template = new MyEncodingTemplate();
+await template.parseExcelFile(file); // Parse and encode data
+console.log(template.list); // Access processed data
+console.log(template.valid); // Check data validity
+```
+
+## Class Details
+
+### Constructor
+
+```typescript
+protected constructor(columns: Array<DataColumn>, rowOffset: number = 1)
+```
+
+- **Parameters**:
+  - `columns`: An array of `DataColumn` objects defining the data structure (field names, display text, and optional parsers).
+  - `rowOffset`: The number of starting rows to skip in the Excel sheet (default: 1, e.g., to skip the header row).
+- **Description**: Initializes the template, setting column definitions and row offset.
+
+### Methods
+
+#### `isRowValid` (Abstract Method)
+
+```typescript
+protected abstract isRowValid(row: any): boolean
+```
+
+- **Parameters**:
+  - `row`: A single row data object.
+- **Description**: Subclasses must implement this method to validate the legitimacy of a single row of data, returning `true` for valid and `false` for invalid.
+- **Override**: Subclasses must implement specific validation logic.
+
+#### `encodeData` (Abstract Method)
+
+```typescript
+protected abstract encodeData(rows: Array<any>): Promise<Array<any>>
+```
+
+- **Parameters**:
+  - `rows`: An array of data to be encoded.
+- **Description**: Subclasses must implement this method to define data encoding logic (e.g., calling a server API for data processing). Returns the encoded data array.
+- **Override**: Subclasses must implement specific encoding logic.
+
+#### `valid` (Abstract Getter)
+
+```typescript
+abstract get valid(): boolean
+```
+
+- **Returns**: A boolean indicating whether the entire dataset is valid.
+- **Description**: Subclasses must implement this getter to check the validity of all data.
+- **Override**: Subclasses must implement specific logic.
+
+#### `consolidateData`
+
+```typescript
+protected async consolidateData(rows: Array<any>): Promise<Array<any>>
+```
+
+- **Parameters**:
+  - `rows`: An array of raw row objects parsed from the Excel file.
+- **Description**: Overrides the `BaseTemplate` method, calling `encodeData` to encode data and merge the encoded results with the original rows.
+- **Logic**: Iterates through each row, merging encoded results with the original data.
+
+#### `columns` (Getter)
+
+```typescript
+get columns(): Array<TableColumn>
+```
+
+- **Returns**: An array of `TableColumn` objects representing column definitions, including data columns and a match status column.
+- **Description**: Extends `BaseTemplate`'s `columns`, adding a match status column (`validColumn`) to display the validity of each row ("Valid" or "Invalid").
+
+### Match Status Column
+
+Defines an additional `validColumn` to display the validity of each row:
+
+```typescript
+private validColumn: TableColumn = {
+    text: getI18nText(i18nKeys.labelMatch),
+    width: 90,
+    align: 'center',
+    escapeHTML: true,
+    formatter: row => this.isRowValid(row) ? ValidData : InvalidData
+}
+```
+
+- **Display**:
+  - `ValidData`: `<span style="color: #76FF03">Valid</span>` (green text).
+  - `InvalidData`: `<span style="color: #ff3e00">Invalid</span>` (red text).
+- **Internationalization**: Uses `getI18nText` to retrieve column titles and status text.
+
+## Notes
+
+- This class is abstract and must be extended with implementations of `isRowValid`, `encodeData`, and the `valid` property.
+- `rowOffset` can be used to skip header rows in Excel files.
+- The match status column visually displays data validation results with green (valid) and red (invalid) text.
+- Data encoding typically involves server interaction, and subclasses must ensure `encodeData` handles asynchronous operations.

package/documents/BaseEncodingTemplate_cn.md

@@ -0,0 +1,156 @@
+# BaseEncodingTemplate 类
+
+一个用于解析 Excel 文件并进行数据编码和验证的抽象基类，继承自 `BaseTemplate`，支持数据有效性检查和列扩展。
+
+## [BaseTemplate](./BaseTemplate_cn.md)
+
+## 概述
+
+`BaseEncodingTemplate` 类扩展了 `BaseTemplate`，增加了数据有效性验证和编码功能。它支持解析 Excel 文件、验证每行数据的合法性，并通过子类实现自定义的数据编码逻辑。类中添加了一个用于显示数据有效性的列（显示“有效”或“无效”状态）。
+
+## 使用方法
+
+要使用 `BaseEncodingTemplate`，需继承该类并实现 `isRowValid`、`encodeData` 方法以及 `valid` 属性。以下是一个示例：
+
+```typescript
+import BaseEncodingTemplate from './BaseEncodingTemplate';
+import type { DataColumn } from './DataColumn';
+
+const columns: DataColumn[] = [
+    {
+        field: 'user.name',
+        text: '姓名',
+        width: 150,
+        parser: (value) => String(value).trim()
+    },
+    {
+        field: 'user.age',
+        text: '年龄',
+        width: 100,
+        parser: (value) => Number(value) || 0
+    }
+];
+
+class MyEncodingTemplate extends BaseEncodingTemplate {
+    constructor() {
+        super(columns, rowOffset);
+    }
+
+    protected isRowValid(row: any): boolean {
+        return row.id != null;
+    }
+
+    protected async encodeData(rows: Array<any>): Promise<Array<any>> {
+        // 实现数据编码逻辑，例如调用 API，然后将返回的数据取代本地数据或者和本地数据融合
+        return rows.map(item => ({ ...item, encoded: true }));
+    }
+
+    get valid(): boolean {
+        // 检查整个数据集是否有效
+        return this._list.filter(iem=>item.id==null).length > 0;
+    }
+}
+```
+
+### 解析 Excel 文件
+
+```typescript
+const file: File = // ... 获取文件（例如，从输入元素获取）
+const template = new MyEncodingTemplate();
+await template.parseExcelFile(file); // 解析并编码数据
+console.log(template.list); // 访问处理后的数据
+console.log(template.valid); // 检查数据有效性
+```
+
+## 类详情
+
+### 构造函数
+
+```typescript
+protected constructor(columns: Array<DataColumn>, rowOffset: number = 1)
+```
+
+- **参数**：
+    - `columns`：定义数据结构（字段名、显示文本和可选解析器）的 `DataColumn` 对象数组。
+    - `rowOffset`：Excel 表中要跳过的起始行数（默认：1，例如跳过标题行）。
+- **描述**：初始化模板，设置列定义和行偏移。
+
+### 方法
+
+#### `isRowValid` (抽象方法)
+
+```typescript
+protected abstract isRowValid(row: any): boolean
+```
+
+- **参数**：
+    - `row`：单行数据对象。
+- **描述**：子类必须实现此方法以验证单行数据的合法性，返回 `true` 表示有效，`false` 表示无效。
+- **重写**：子类需实现具体验证逻辑。
+
+#### `encodeData` (抽象方法)
+
+```typescript
+protected abstract encodeData(rows: Array<any>): Promise<Array<any>>
+```
+
+- **参数**：
+    - `rows`：要编码的数据数组。
+- **描述**：子类必须实现此方法以定义数据编码逻辑（例如，调用服务器 API 进行数据处理）。返回编码后的数据数组。
+- **重写**：子类需实现具体编码逻辑。
+
+#### `valid` (抽象获取器)
+
+```typescript
+abstract get valid(): boolean
+```
+
+- **返回**：布尔值，表示整个数据集是否有效。
+- **描述**：子类必须实现此获取器以检查所有数据的有效性。
+- **重写**：子类需实现具体逻辑。
+
+#### `consolidateData`
+
+```typescript
+protected async consolidateData(rows: Array<any>): Promise<Array<any>>
+```
+
+- **参数**：
+    - `rows`：从 Excel 文件解析出的原始行对象数组。
+- **描述**：重写 `BaseTemplate` 的方法，调用 `encodeData` 对数据进行编码，并将编码结果合并到原始行中。
+- **逻辑**：遍历每行数据，将编码结果与原始数据合并。
+
+#### `columns`（获取器）
+
+```typescript
+get columns(): Array<TableColumn>
+```
+
+- **返回**：`TableColumn` 对象的数组，表示列定义，包含数据列和匹配状态列。
+- **描述**：扩展 `BaseTemplate` 的 `columns`，添加一个匹配状态列（`validColumn`），用于显示每行数据的有效性（“有效”或“无效”）。
+
+### 匹配状态列
+
+定义了一个额外的 `validColumn` 用于显示每行数据的有效性：
+
+```typescript
+private validColumn: TableColumn = {
+    text: getI18nText(i18nKeys.labelMatch),
+    width: 90,
+    align: 'center',
+    escapeHTML: true,
+    formatter: row => this.isRowValid(row) ? ValidData : InvalidData
+}
+```
+
+- **显示**：
+    - `ValidData`：`<span style="color: #76FF03">有效</span>`（绿色文本）。
+    - `InvalidData`：`<span style="color: #ff3e00">无效</span>`（红色文本）。
+- **国际化**：使用 `getI18nText` 获取列标题和状态文本。
+
+## 注意事项
+
+- 该类为抽象类，必须继承并实现 `isDataValid`、`encodeData` 方法和 `valid` 属性。
+- `rowOffset` 可用于跳过 Excel 文件中的标题行。
+- 匹配状态列通过绿色（有效）和红色（无效）文本直观显示数据验证结果。
+- 数据编码通常涉及与服务器交互，子类需确保 `encodeData` 方法处理异步操作。

package/documents/BaseTemplate.md

@@ -0,0 +1,222 @@
+# BaseTemplate Class
+
+An abstract base class for parsing Excel files and handling data with customizable column definitions.
+
+## Overview
+
+The `BaseTemplate` class provides a foundation for processing Excel files using the `xlsx` library. It supports parsing Excel data into a structured format and enables custom column definitions and data transformations through subclassing. The class is designed to be extensible for specific use cases.  
+Typically, there is no need to directly inherit from `BaseTemplate`; instead, you can use its subclasses `BaseEncodingTemplate` or `BaseUploadTemplate` based on business requirements.
+
+## Usage
+
+To use `BaseTemplate`, you must extend the class and implement the necessary custom data processing logic. Below is an example:
+
+```typescript
+import BaseTemplate from './BaseTemplate';
+import type { DataColumn } from './DataColumn';
+
+class MyTemplate extends BaseTemplate {
+    constructor(columns: DataColumn[], rowOffset: number = 1) {
+        super(columns, rowOffset);
+    }
+
+    // Optionally override consolidateData for custom data processing
+    protected async consolidateData(rows: Array<any>): Promise<Array<any>> {
+        // Add custom logic here
+        return rows;
+    }
+}
+```
+
+### Parsing Excel Files
+
+To parse an Excel file, call the `parseExcelFile` method with a `File` object:
+
+```typescript
+const file: File = // ... Obtain the file (e.g., from an input element)
+const columns: DataColumn[] = [
+    { field: 'name', parser: (value) => String(value) },
+    { field: 'age', parser: (value) => Number(value) }
+];
+const template = new MyTemplate(columns);
+await template.parseExcelFile(file);
+console.log(template.list); // Access parsed data
+```
+
+## Class Details
+
+### Constructor
+
+```typescript
+protected constructor(columns: Array<DataColumn>, rowOffset: number = 1)
+```
+
+- **Parameters**:
+  - `columns`: An array of `DataColumn` objects defining the data structure (field names and optional parsers).
+  - `rowOffset`: The number of starting rows to skip in the Excel sheet (default: 1, e.g., to skip the header row).
+- **Description**: Initializes the template with column definitions and row offset.
+
+### Methods
+
+#### `parseExcelFile`
+
+```typescript
+async parseExcelFile(file: File): Promise<void>
+```
+
+- **Parameters**:
+  - `file`: The Excel file to parse.
+- **Description**: Reads and parses the Excel file, processes each row based on column definitions, and stores the result in the internal `_list` after applying `consolidateData`.
+- **Dependencies**: Uses `xlsx` for reading Excel files and `utils` for nested value operations.
+
+#### `consolidateData`
+
+```typescript
+protected async consolidateData(rows: Array<any>): Promise<Array<any>>
+```
+
+- **Parameters**:
+  - `rows`: An array of raw row objects parsed from the Excel file.
+- **Description**: A hook method that subclasses can override for additional data processing. By default, it returns the unchanged rows.
+- **Override**: Subclasses can override this method to implement custom data transformation logic.
+
+#### `extractData`
+
+```typescript
+protected extractData(arr: Array<any>): Array<any>
+```
+
+- **Parameters**:
+  - `arr`: An array of data objects to process.
+- **Description**: Filters and maps input data to include only visible and non-ignored columns, returning a new array of processed objects.
+- **Purpose**: Used internally to prepare data for upload or further processing.
+
+#### `wrapData`
+
+```typescript
+protected wrapData(data: any): any
+```
+
+- **Parameters**:
+  - `data`: A single row object.
+- **Description**: A hook method for wrapping or transforming a single row of data. By default, it returns the unchanged data.
+- **Override**: Subclasses can override this method to wrap data into a specific structure.
+
+#### `columns` (Getter)
+
+```typescript
+get columns(): Array<TableColumn>
+```
+
+- **Returns**: An array of `TableColumn` objects representing column definitions.
+- **Description**: Provides a copy of the column definitions for use in data tables or other UI components.
+
+#### `list` (Getter)
+
+```typescript
+get list(): Array<any>
+```
+
+- **Returns**: A copy of the parsed and processed data list.
+- **Description**: Provides external access to the processed data.
+
+## DataColumn Interface
+
+A TypeScript interface that defines the structure and behavior of data table columns, used to describe column metadata and support features like column display, data parsing, and formatting.  
+The `DataColumn` interface defines the properties and behavior of columns in a data table, including column titles, field mappings, formatting, alignment, and specific fields for data parsing and upload control. It is suitable for scenarios involving table data processing and Excel file parsing.
+
+### Usage
+
+The `DataColumn` interface is used to define the column structure of a data table, typically in conjunction with `BaseTemplate` or its derived classes (e.g., `BaseUploadTemplate`, `BaseEncodingTemplate`). Below is an example:
+
+```typescript
+import type { DataColumn } from './DataColumn';
+
+const columns: DataColumn[] = [
+    {
+        field: 'user.name',
+        text: 'Name',
+        width: 150,
+        align: 'left',
+        parser: (value) => String(value).trim(),
+        visible: true,
+        ignore: false
+    },
+    {
+        field: 'user.age',
+        text: 'Age',
+        width: 100,
+        align: 'center',
+        parser: (value) => Number(value) || 0,
+        visible: true,
+        ignore: false,
+        formatter: (row) => `${row['user.age']} years`
+    }
+];
+```
+
+### Properties
+
+- **field**: `string`
+  - The field name used to map properties in the data object, supporting nested paths with dot notation (e.g., `user.name`).
+- **text**: `string`
+  - The column header text displayed in the data table.
+- **frozen?**: `boolean`
+  - Whether the column is frozen (fixed to the left side of the table), effective only if preceding columns are also `frozen`.
+- **align?**: `'left' | 'center' | 'right'`
+  - The alignment of cell content, defaults to unspecified (determined by the renderer).
+- **width**: `number`
+  - The column width in pixels.
+- **minWidth?**: `number`
+  - The minimum column width in pixels (optional).
+- **formatter?**: `FormatCell`
+  - A function for customizing cell display content.
+- **escapeHTML?**: `boolean`
+  - Whether to escape HTML characters to prevent XSS attacks (default: unspecified).
+- **visible?**: `boolean`
+  - Whether the column is visible, controlling its display in the table (default: unspecified).
+- **resizable?**: `boolean`
+  - Whether the column width can be resized (default: unspecified).
+- **ignore?**: `boolean`
+  - Whether to ignore the column; if `true`, the column is used only for frontend display and not included in data uploads (default: `false`).
+- **parser?**: `ParserText`
+  - A data parsing function defined as `(text: string) => any`, used to convert raw Excel cell values to the target format (e.g., converting strings to numbers).
+
+#### Types
+
+- **ParserText**: `(text: string) => any`
+  - A parsing function type that takes a string input and returns a value of any type, used to process cell data from Excel files.
+- **FormatCell**: A custom type (defined in `./FormatCell`) used for formatting cell display content.
+
+#### Notes
+
+- The `field` property is required in `DataColumn` to ensure correct data mapping.
+- The `parser` function is critical for processing Excel data and should be defined based on the field type (e.g., string, number, date).
+- The `ignore` property is useful for columns that should be displayed on the frontend but not included in uploads (e.g., auxiliary information columns).
+- Ensure that dependent types (e.g., `FormatCell`) are properly defined and imported.
+
+#### Example Column Definition
+
+```typescript
+const columns: DataColumn[] = [
+    {
+        field: 'user.name',
+        parser: (value) => String(value).trim(),
+        visible: true,
+        ignore: false
+    },
+    {
+        field: 'user.age',
+        parser: (value) => Number(value) || 0,
+        visible: true,
+        ignore: false
+    }
+];
+```
+
+## Notes
+
+- This class is abstract and must be extended for use.
+- Ensure that `xlsx` and `@ticatec/uniface-element/DataTable` are installed and configured.
+- The `rowOffset` can be used to skip header rows in Excel files.
+- The `parser` function in `DataColumn` allows custom parsing of cell values (e.g., converting strings to numbers).