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

@senlinz/import-export 0.1.0-beta.8 → 0.1.0

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 +158 -61
package/README.zh.md +158 -0
package/dist/index.js +2 -0
package/dist/types/ExcelDefinition.d.ts +102 -0
package/dist/types/index.d.ts +11 -6
package/dist/types/runtime.d.ts +20 -0
package/dist/types/utils.d.ts +6 -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-3c6b6bbf.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,158 @@
-# @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`, `exportExcel`, `fromExcel`, `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
+### 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.
+## 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`, and `importExcel` require DOM/browser APIs.
+- `fromExcel`, `toExcel`, and `generateExcelTemplate` can 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,158 @@
+# @senlinz/import-export
+面向浏览器的高阶 Excel 模板生成、导出与导入 API。
+[English](./README.md)
+## 安装
+```bash
+pnpm add @senlinz/import-export
+```
+## 选择使用模式
+### 默认模式（推荐）
+- 无需额外初始化。
+- `importExcel`、`exportExcel`、`fromExcel`、`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[].name` 完全一致。
+- `number` 列导入后返回数字。
+- 空的 `number` / `date` 单元格导入后返回 `null`。
+- `date` 列导入后返回格式化字符串。
+- 非法或不完整的 schema 会在读取工作簿前立即失败。
+## 导出行为
+- `null` 和 `undefined` 会导出为空单元格。
+- 数字列会拒绝非有限值。
+- 日期列支持 `Date` 实例或日期字符串。
+- 分组导出对象必须使用 `{ value?, children: [...] }` 结构。
+- 图片列必须提供 `imageFetcher`。
+## 已支持的高级能力
+以下高级能力已纳入公开 API：
+- 合并标题行
+- 冻结表头
+- 列备注
+- 下拉候选值
+- 条件 `valueFormat`
+- 使用 `dataGroup` / `dataGroupParent` 的嵌套分组导出
+- 通过 `imageFetcher` 导出图片
+## 浏览器 / 运行时支持
+- 主要面向浏览器 ESM 运行时。
+- `downloadExcelTemplate`、`exportExcel`、`importExcel` 依赖 DOM / 浏览器 API。
+- 当运行时提供兼容的浏览器全局对象时，也可以使用 `fromExcel`、`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` 实例。
+- 当前一次只校验一个工作表。