npm - @senlinz/import-export - Versions diffs - 0.1.0-beta.9 → 0.1.1 - Mend

@senlinz/import-export 0.1.0-beta.9 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/LICENSE +21 -21
package/README.md +196 -61
package/README.zh.md +188 -0
package/dist/index.js +2 -0
package/dist/types/ExcelDefinition.d.ts +116 -0
package/dist/types/index.d.ts +17 -7
package/dist/types/runtime.d.ts +20 -0
package/dist/types/utils.d.ts +8 -7
package/package.json +22 -23
package/dist/components/editable-cell.d.ts +0 -11
package/dist/components/editable-cell.js +0 -2
package/dist/components/import-export-definition.d.ts +0 -11
package/dist/components/import-export-definition.js +0 -2
package/dist/components/import-export-studio.d.ts +0 -11
package/dist/components/import-export-studio.js +0 -2
package/dist/components/import-export-table.d.ts +0 -11
package/dist/components/import-export-table.js +0 -2
package/dist/components/index.d.ts +0 -33
package/dist/components/index.js +0 -2
package/dist/components/p-3b0da608.js +0 -2
package/dist/components/p-c9904f6a.js +0 -2
package/dist/components/p-dd1bf849.js +0 -2
package/dist/components/p-ddbe189c.js +0 -2
package/dist/components/p-f7586df1.js +0 -2
package/dist/tests/dist/editable-cell.d.ts +0 -11
package/dist/tests/dist/imexport-table.d.ts +0 -11
package/dist/tests/dist/import-export-definition.d.ts +0 -11
package/dist/tests/dist/import-export-definiton.d.ts +0 -11
package/dist/tests/dist/import-export-studio.d.ts +0 -11
package/dist/tests/dist/import-export-table.d.ts +0 -11
package/dist/tests/dist/index.d.ts +0 -33
package/dist/tests/dist/table-definition.d.ts +0 -11
package/dist/types/components/editable-cell/editable-cell.d.ts +0 -18
package/dist/types/components/imexport-table/imexport-table.d.ts +0 -19
package/dist/types/components/import-export-definition/import-export-definition.d.ts +0 -7
package/dist/types/components/import-export-definition/import-export-definiton.d.ts +0 -6
package/dist/types/components/import-export-studio/import-export-studio.d.ts +0 -14
package/dist/types/components/import-export-studio/import-export-table.d.ts +0 -5
package/dist/types/components/import-export-table/import-export-table.d.ts +0 -6
package/dist/types/components/table-definition/table-definition.d.ts +0 -0
package/dist/types/components.d.ts +0 -116
package/dist/types/declarations/ExcelDefinition.d.ts +0 -17
package/dist/types/declarations/ExcelDefintion.d.ts +0 -17
package/dist/types/stencil-public-runtime.d.ts +0 -1674
package/dist/types/types/index.d.ts +0 -19
package/dist/types/utils/utils.d.ts +0 -9

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2018
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2018
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,61 +1,196 @@
-# @senlinz/import-export
-example for import and export excel file
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>IMPORT-EXPORT-TEST</title>
-</head>
-<button id="btnImport">Import</button>
-<button id="btnExport">Export</button>
-<button id="btnDownloadTemplate">Download Template</button>
-<div id="importOutput"></div>
-<body>
-  <script type="module">
-    import {
-      importExcel,
-      exportExcel,
-      downloadExcelTemplate } from 'https://cdn.jsdelivr.net/npm/@senlinz/import-export/+esm';
-    const excelInfo = {
-      name: 'TomAndJerry',
-      sheetName: 'sheet1',
-      columns: [
-        { key: 'name', name: 'Name', dataType: 0, width: 20, note: 'required' },
-        { key: 'age', name: 'Age', dataType: 1, width: 10 },
-        { key: 'category', name: 'Category', dataType: 0, allowedValues: ['Cat', 'Mouse'] }
-      ],
-      author: 'senlinz',
-      createTime: '2024-11-01T09:00:00'
-    };
-    btnImport.addEventListener('click', importClick);
-    btnExport.addEventListener('click', exportClick);
-    btnDownloadTemplate.addEventListener('click', downloadTemplateClick);
-    function exportClick() {
-      exportExcel(excelInfo, [
-        { name: 'Tom', age: 12, category: 'Cat' },
-        { name: 'Jerry', age: 13, category: 'Mouse' }
-      ]);
-    }
-    function importClick() {
-      importExcel(excelInfo).then(data => {
-        importOutput.innerText = JSON.stringify(data, null);
-      });
-    }
-    function downloadTemplateClick() {
-      downloadExcelTemplate(excelInfo);
-    }
-  </script>
-</body>
-</html>
-```
+# @senlinz/import-export
+High-level browser API for Excel template generation, export, and import.
+[中文文档](./README.zh.md)
+## Install
+```bash
+pnpm add @senlinz/import-export
+```
+## Choose your mode
+### Default mode (recommended)
+- No setup required.
+- `importExcel`, `importExcelDynamic`, `exportExcel`, `fromExcel`, `fromExcelDynamic`, `toExcel`, `downloadExcelTemplate`, and `generateExcelTemplate` automatically initialize the bundled WASM runtime.
+- Best for most browser applications.
+### Advanced mode
+- Call `initializeWasm(...)` yourself before using the Excel APIs.
+- Use this when you want custom WASM hosting, bundler control, or to reuse bytes/modules that you loaded elsewhere.
+- Supported manual inputs: `source`, `bytes`, or `module`.
+- `bundledWasmSource` is also exported for self-contained demos/tests that still want explicit manual initialization.
+```ts
+import { initializeWasm, toExcel } from '@senlinz/import-export';
+const wasmBytes = new Uint8Array(
+  await (await fetch('/assets/imexport_wasm_bg.wasm')).arrayBuffer()
+);
+initializeWasm({ bytes: wasmBytes });
+const workbook = await toExcel({
+  name: 'TomAndJerry',
+  columns: [{ key: 'name', name: 'Name', dataType: 'text' }],
+}, [{ name: 'Tom' }]);
+```
+If you provide invalid manual input, `initializeWasm(...)` throws a clear error immediately.
+## Supported API
+### Stable definition fields
+- `name` - file name used for template/export downloads
+- `sheetName` - worksheet name used for export and preferred during import
+- `columns` - stable schema for headers, validation, and row mapping
+- `author` - optional workbook author metadata
+- `createTime` - optional workbook creation time as a `Date` or date string
+- `title`, `titleHeight`, `titleFormat` - optional merged title row and its layout/format
+- `defaultRowHeight`, `headerRowHeight` - row heights for exported data rows and header rows
+- `dx`, `dy` - horizontal and vertical offsets before the header starts
+- `isHeaderFreeze` - freezes the header area so column labels stay visible while scrolling
+- `progressCallback` - progress hook for long-running import/export work
+- `imageFetcher` - required resolver for `image` columns during export
+### Schema-less import
+Use `importExcelDynamic(options?)` when you want to open the browser file picker without defining `columns` ahead of time.
+```ts
+import { importExcelDynamic } from '@senlinz/import-export';
+const result = await importExcelDynamic({
+  sheetName: 'sheet1',
+  headerRow: 1,
+});
+console.log(result.headers);
+console.log(result.rows);
+```
+Use `fromExcelDynamic(buffer, options?)` when you want to read caller-provided workbook bytes without defining `columns` ahead of time.
+```ts
+import { fromExcelDynamic } from '@senlinz/import-export';
+const result = await fromExcelDynamic(fileBytes, {
+  sheetName: 'sheet1',
+  headerRow: 1,
+});
+console.log(result.headers);
+console.log(result.rows);
+```
+- `importExcelDynamic(...)` depends on DOM/browser file upload APIs.
+- `sheetName` is optional and falls back to the first worksheet when missing.
+- `headerRow` is optional, 1-based, and defaults to the first non-empty row in the selected sheet.
+- The result shape is `{ sheetName, headers, rows }`.
+- Dynamic import requires non-empty, unique header names in the selected header row.
+### Stable column fields
+- `key` - unique programmatic field key
+- `name` - visible worksheet header label
+- `width` - exported column width
+- `note` - header note/comment shown in Excel
+- `dataType` - scalar cell type
+- `allowedValues` - validation list for allowed cell values
+- `parent` - parent header key for multi-row headers
+- `format` - base cell format for the column
+- `valueFormat` - direct or conditional format overrides for exported values
+- `dataGroup` - logical group identifier for nested export data
+- `dataGroupParent` - parent group identifier for nested export data
+### Supported `dataType` values
+- `text` - default text cells
+- `number` - finite numeric values
+- `date` - `Date` instances or parseable date strings on export
+- `image` - image URLs or identifiers resolved through `imageFetcher`
+## Import/export flow
+```ts
+import { downloadExcelTemplate, exportExcel, importExcel } from '@senlinz/import-export';
+const definition = {
+  name: 'TomAndJerry',
+  sheetName: 'sheet1',
+  columns: [
+    { key: 'name', name: 'Name', dataType: 'text', width: 20, note: 'required' },
+    { key: 'age', name: 'Age', dataType: 'number', width: 10 },
+    { key: 'birthday', name: 'Birthday', dataType: 'date', width: 18 },
+    { key: 'category', name: 'Category', allowedValues: ['Cat', 'Mouse'] },
+    { key: 'image', name: 'Image', dataType: 'image', width: 10 },
+  ],
+  imageFetcher: async (url: string) => new Uint8Array(await (await fetch(url)).arrayBuffer()),
+};
+await downloadExcelTemplate(definition);
+await exportExcel(definition, [
+  { name: 'Tom', age: 12, birthday: '2024-11-01 00:00:00', category: 'Cat', image: '/Tom.jpg' },
+  { name: 'Jerry', age: null, birthday: null, category: 'Mouse', image: '/Jerry.png' },
+]);
+const rows = await importExcel(definition);
+```
+## Import behavior
+- Headers must match the configured `columns[].name` values exactly.
+- Imported `number` columns are returned as numbers.
+- Empty imported `number` and `date` cells are returned as `null`.
+- Imported `date` values are returned as formatted strings.
+- Unknown or malformed schemas fail fast before any workbook operation starts.
+- Use `importExcelDynamic(...)` for browser uploads without a schema, or `fromExcelDynamic(...)` when you already have workbook bytes.
+## Export behavior
+- `null` and `undefined` values are exported as blank cells.
+- Number columns reject non-finite values.
+- Date columns accept `Date` instances or parseable date strings.
+- Grouped export objects must use `{ value?, children: [...] }` for configured `dataGroup` columns.
+- Image columns require `imageFetcher`.
+## Advanced supported features
+These advanced features are supported and considered part of the public API:
+- merged title rows
+- frozen headers
+- column notes
+- allowed value validation lists
+- conditional `valueFormat`
+- nested grouped export data via `dataGroup` and `dataGroupParent`
+- image export via `imageFetcher`
+## Browser/runtime support
+- Browser ESM runtimes are the primary target.
+- `downloadExcelTemplate`, `exportExcel`, `importExcel`, and `importExcelDynamic` require DOM/browser APIs.
+- `fromExcel`, `toExcel`, and `generateExcelTemplate` can be used in other runtimes when browser-compatible globals are available.
+- `fromExcelDynamic` can also be used in other runtimes when browser-compatible globals are available.
+- `initializeWasm` can be used to pre-initialize the runtime with caller-managed `source`, `bytes`, or `module`.
+## Examples
+- [Basic browser example](./examples/basic-browser.html)
+- [Manual WASM browser example](./examples/manual-wasm-browser.html)
+- [Grouped export example](./examples/grouped-export.html)
+- [Definition validation example](./examples/definition-errors.html)
+These examples are covered by Playwright tests in [`./tests/import-export.spec.ts`](./tests/import-export.spec.ts).
+## Known limitations
+- Parent headers and data groups must be declared before dependent columns.
+- Date imports normalize to strings instead of `Date` instances.
+- Import currently validates a single worksheet at a time.

package/README.zh.md ADDED Viewed

@@ -0,0 +1,188 @@
+# @senlinz/import-export
+面向浏览器的高阶 Excel 模板生成、导出与导入 API。
+[English](./README.md)
+## 安装
+```bash
+pnpm add @senlinz/import-export
+```
+## 选择使用模式
+### 默认模式（推荐）
+- 无需额外初始化。
+- `importExcel`、`importExcelDynamic`、`exportExcel`、`fromExcel`、`fromExcelDynamic`、`toExcel`、`downloadExcelTemplate`、`generateExcelTemplate` 会自动初始化内置 WASM 运行时。
+- 适合绝大多数浏览器场景。
+### 高级模式
+- 在使用这些 Excel API 之前，先手动调用 `initializeWasm(...)`。
+- 适用于自定义 WASM 托管、需要自己控制 bundler 行为，或希望复用已加载 bytes / module 的场景。
+- 支持的手动输入：`source`、`bytes`、`module`。
+- 同时也导出了 `bundledWasmSource`，方便在自包含 demo / 测试中显式走手动初始化流程。
+```ts
+import { initializeWasm, toExcel } from '@senlinz/import-export';
+const wasmBytes = new Uint8Array(
+  await (await fetch('/assets/imexport_wasm_bg.wasm')).arrayBuffer()
+);
+initializeWasm({ bytes: wasmBytes });
+const workbook = await toExcel({
+  name: 'TomAndJerry',
+  columns: [{ key: 'name', name: 'Name', dataType: 'text' }],
+}, [{ name: 'Tom' }]);
+```
+如果手动传入的 WASM 输入无效，`initializeWasm(...)` 会立即抛出清晰的错误信息。
+## 支持的 API
+### 稳定的 definition 字段
+- `name`：模板 / 导出下载时使用的文件名
+- `sheetName`：导出时使用、导入时优先匹配的工作表名称
+- `columns`：表头、校验和行映射使用的稳定列定义
+- `author`：可选的工作簿作者元数据
+- `createTime`：可选的工作簿创建时间，支持 `Date` 或日期字符串
+- `title`、`titleHeight`、`titleFormat`：可选的合并标题行及其高度、样式
+- `defaultRowHeight`、`headerRowHeight`：导出时数据行和表头行的行高
+- `dx`、`dy`：表头写入前的横向、纵向偏移量
+- `isHeaderFreeze`：冻结表头区域，滚动时仍保持列标题可见
+- `progressCallback`：长时间导入 / 导出过程中的进度回调
+- `imageFetcher`：导出 `image` 列时必需的图片数据解析回调
+### 稳定的列字段
+- `key`：唯一的程序字段名
+- `name`：工作表中显示的列表头
+- `width`：导出列宽
+- `note`：附加在表头单元格上的备注 / 注释
+- `dataType`：标量单元格类型
+- `allowedValues`：单元格允许值的校验列表
+- `parent`：多级表头时的父级表头 key
+- `format`：列的基础单元格格式
+- `valueFormat`：导出值的直接或条件格式覆盖
+- `dataGroup`：嵌套导出数据使用的逻辑分组标识
+- `dataGroupParent`：嵌套导出数据使用的父级分组标识
+### 支持的 `dataType`
+- `text`：默认文本类型
+- `number`：有限数值
+- `date`：导出时支持 `Date` 实例或日期字符串
+- `image`：通过 `imageFetcher` 解析图片 URL 或标识
+## 导入 / 导出流程
+```ts
+import { downloadExcelTemplate, exportExcel, importExcel } from '@senlinz/import-export';
+const definition = {
+  name: 'TomAndJerry',
+  sheetName: 'sheet1',
+  columns: [
+    { key: 'name', name: 'Name', dataType: 'text', width: 20, note: 'required' },
+    { key: 'age', name: 'Age', dataType: 'number', width: 10 },
+    { key: 'birthday', name: 'Birthday', dataType: 'date', width: 18 },
+    { key: 'category', name: 'Category', allowedValues: ['Cat', 'Mouse'] },
+    { key: 'image', name: 'Image', dataType: 'image', width: 10 },
+  ],
+  imageFetcher: async (url: string) => new Uint8Array(await (await fetch(url)).arrayBuffer()),
+};
+await downloadExcelTemplate(definition);
+await exportExcel(definition, [
+  { name: 'Tom', age: 12, birthday: '2024-11-01 00:00:00', category: 'Cat', image: '/Tom.jpg' },
+  { name: 'Jerry', age: null, birthday: null, category: 'Mouse', image: '/Jerry.png' },
+]);
+const rows = await importExcel(definition);
+```
+## 动态导入
+当你不想预先定义 `columns`，并希望直接使用浏览器文件选择框时，可使用 `importExcelDynamic(options?)`。
+```ts
+import { importExcelDynamic } from '@senlinz/import-export';
+const result = await importExcelDynamic({
+  sheetName: 'sheet1',
+  headerRow: 1,
+});
+```
+当你已经拿到工作簿字节数据时，可继续使用 `fromExcelDynamic(buffer, options?)`。
+```ts
+import { fromExcelDynamic } from '@senlinz/import-export';
+const result = await fromExcelDynamic(fileBytes, {
+  sheetName: 'sheet1',
+  headerRow: 1,
+});
+```
+- `importExcelDynamic(...)` 依赖 DOM / 浏览器文件上传 API。
+- `sheetName` 可选，未提供或不存在时会回退到第一个工作表。
+- `headerRow` 可选，使用从 `1` 开始的行号，默认会自动选择首个非空行。
+- 返回值结构为 `{ sheetName, headers, rows }`。
+## 导入行为
+- 表头必须与 `columns[].name` 完全一致。
+- `number` 列导入后返回数字。
+- 空的 `number` / `date` 单元格导入后返回 `null`。
+- `date` 列导入后返回格式化字符串。
+- 非法或不完整的 schema 会在读取工作簿前立即失败。
+- 无 schema 导入时，可使用 `importExcelDynamic(...)`（浏览器上传）或 `fromExcelDynamic(...)`（字节缓冲）。
+## 导出行为
+- `null` 和 `undefined` 会导出为空单元格。
+- 数字列会拒绝非有限值。
+- 日期列支持 `Date` 实例或日期字符串。
+- 分组导出对象必须使用 `{ value?, children: [...] }` 结构。
+- 图片列必须提供 `imageFetcher`。
+## 已支持的高级能力
+以下高级能力已纳入公开 API：
+- 合并标题行
+- 冻结表头
+- 列备注
+- 下拉候选值
+- 条件 `valueFormat`
+- 使用 `dataGroup` / `dataGroupParent` 的嵌套分组导出
+- 通过 `imageFetcher` 导出图片
+## 浏览器 / 运行时支持
+- 主要面向浏览器 ESM 运行时。
+- `downloadExcelTemplate`、`exportExcel`、`importExcel`、`importExcelDynamic` 依赖 DOM / 浏览器 API。
+- 当运行时提供兼容的浏览器全局对象时，也可以使用 `fromExcel`、`fromExcelDynamic`、`toExcel`、`generateExcelTemplate`。
+- `initializeWasm` 可用于使用调用方提供的 `source`、`bytes` 或 `module` 预初始化运行时。
+## 示例
+- [基础浏览器示例](./examples/basic-browser.html)
+- [手动初始化 WASM 的浏览器示例](./examples/manual-wasm-browser.html)
+- [分组导出示例](./examples/grouped-export.html)
+- [Definition 校验示例](./examples/definition-errors.html)
+这些示例由 [`./tests/import-export.spec.ts`](./tests/import-export.spec.ts) 中的 Playwright 用例覆盖。
+## 已知限制
+- 父级表头和数据分组必须先于依赖它们的列声明。
+- `date` 导入结果会规范化为字符串，而不是 `Date` 实例。
+- 当前一次只校验一个工作表。