# gridcraft-preview 中文文档

规范地址：https://npmcn.com/package/gridcraft-preview/

版本：0\.1\.0
npm 元数据更新时间：2026-11-03T17:37:20.918Z
中文译文更新时间：2026-11-03T19:10:46.578Z
软件包许可：\(MIT OR Apache-2\.0\)

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/gridcraft-preview
原文对照：https://npmcn.com/package/gridcraft-preview/?lang=original
项目主页：https://getartcraft.com/apps/gridcraft
源码仓库：https://github.com/storytold/gridcraft

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：25.1 MB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：0 个
- 首次发布：2026-11-03T17:32:09.118Z
- 最新版本发布：2026-11-03T17:37:20.771Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

只读的XLSX/XLS电子表格浏览器的网络，由GridCraft提供支持

## 安装

```sh
npm install gridcraft-preview
```

也可以使用：`pnpm add gridcraft-preview`、`yarn add gridcraft-preview`、`bun add gridcraft-preview`

## README

# GridCraft预览

只读的XLSX/XLS电子表格浏览器为web，由 [GridCraft](https://getartcraft.com/apps/gridcraft)。

## 特性

-   ✅ **打开XLSX/XLS文件** 从文件/Blob对象
-   ✅ **表导航** -在工作表之间切换
-   ✅ **缩放控件** -放大/缩小/适合窗口
-   ✅ **细胞的选择** —选择和查看单元格内容（只读）
-   ✅ **搜索** -查找当前工作表中的文本
-   ✅ **复制** -复制单元格内容到剪贴板
-   ✅ **多语言** - 19种语言，包括英文和中文
-   ✅ **主题切换** -明暗或自动（跟随系统）
-   ❌ **没有编辑** —禁用所有编辑功能

## 安装

```bash
npm install gridcraft-preview
```

## 用法

### 基本的例子

```typescript
import init, { GridCraftPreview } from 'gridcraft-preview';

// Initialize WASM module (must be called once before using the preview)
await init();

// Create preview instance
const preview = new GridCraftPreview();

// Load a file
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    await preview.loadFile(file);
  }
});

// Control the view
preview.zoomIn();
preview.zoomOut();
preview.zoomToFit();
preview.setZoom(125); // 125%

// Navigate sheets
const sheets = preview.getSheetNames();
console.log('Available sheets:', sheets);
preview.switchSheet('Sheet2');

// Search
const matchCount = preview.find('total', { matchCase: false });
console.log(`Found ${matchCount} matches`);
preview.findNext();

// Internationalization
preview.setLanguage('zh'); // Switch to Chinese
preview.setLanguage('en'); // Switch back to English

// Theme
preview.setTheme('dark');
preview.setTheme('auto'); // Follow system preference
```

### 从URL加载

```typescript
import init, { GridCraftPreview } from 'gridcraft-preview';

await init();

const preview = new GridCraftPreview();

// Fetch and load a spreadsheet
const response = await fetch('/data/spreadsheet.xlsx');
const blob = await response.blob();
await preview.loadFile(blob, 'spreadsheet.xlsx');
```

### HTML集成

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>GridCraft Preview Example</title>
</head>
<body>
  <div>
    <input type="file" id="fileInput" accept=".xlsx,.xls" />
    <button onclick="preview.zoomIn()">Zoom In</button>
    <button onclick="preview.zoomOut()">Zoom Out</button>
    <button onclick="preview.zoomToFit()">Fit</button>
  </div>
  
  <canvas id="gridcraft_canvas" style="width: 100%; height: 600px;"></canvas>

  <script type="module">
    import init, { GridCraftPreview } from './node_modules/gridcraft-preview/dist/index.js';

    await init();
    window.preview = new GridCraftPreview();

    document.getElementById('fileInput').addEventListener('change', async (e) => {
      const file = e.target.files[0];
      if (file) {
        await window.preview.loadFile(file);
      }
    });
  </script>
</body>
</html>
```

## API参考

看到 [index.d.ts](https://npmcn.com/package/gridcraft-preview/index.d.ts) 获取完整的TypeScript定义。

### `GridCraftPreview`

用于控制预览的主类。

#### 构造函数

```typescript
const preview = new GridCraftPreview();
```

#### 方法

##### 文件操作

-   `loadFile(file: File | Blob, filename?: string): Promise<void>` —加载电子表格文件

##### 视图控件

-   `zoomIn(): void` -放大
-   `zoomOut(): void` -缩小
-   `zoomToFit(): void` -缩放以适应窗口
-   `setZoom(percentage: number): void` —设置具体的缩放级别

##### 表导航

-   `getSheetNames(): string[]` -获取所有表单名称
-   `getCurrentSheet(): string` -获取当前工作表名称
-   `switchSheet(name: string): void` -切换到工作表

##### 选择

-   `getSelection(): string` -获取当前选择范围
-   `selectRange(range: string): void` —选择范围

##### 搜索

-   `find(query: string, options?: FindOptions): number` -查找文本
-   `findNext(): boolean` -查找下一个事件
-   `findPrevious(): boolean` -查找以前的事件

##### 本地化

-   `setLanguage(lang: Language): void` -设置界面语言
-   `setTheme(theme: Theme): void` -设置颜色主题

### 支持的语言

英语(`en`), 简体中文 (`zh`), Español (`es`), 日本語 (`ja`), (`ko`)， Русский (`ru`), Português (`pt`)、德语(`de`)， Čeština (`cs`)，法国(`fr`)， Српски (`sr`)、<s:1> rk<e:1> (`tr`)，波兰(`pl`)，意大利语(`it`)， Українська (`uk`), Tiếng Việt (`vi`)、荷兰(`nl`)、romnui (`ro`)， Ελληνικά (`el`）

### 支持的文件格式

-   **XLSX** - Excel 2007+工作簿（完全支持）
-   **XLSM** -支持Excel宏的工作簿（仅查看，不支持宏）
-   **XLS** - Excel 97-2003工作簿（值和公式，格式有限）

## 浏览器兼容性

需要支持WebGPU或WebGL2的现代浏览器：

-   Chrome /边缘79 +
-   Firefox 51 +
-   Safari 15 +
-   歌剧66 +

## 大小

-   未压缩的WASM: ~ 3mb
-   压缩：~ 1mb

## 许可证

双重许可下 [麻省理工学院](https://npmcn.com/package/gridcraft-preview/LICENSE-MIT) 或 [apache - 2.0](https://npmcn.com/package/gridcraft-preview/LICENSE-APACHE)，由你选择。

## 学分

建立与 [GridCraft](https://getartcraft.com/apps/gridcraft) - ArtCraft团队的开源电子表格软件。

## 链接

-   [GridCraft](https://getartcraft.com/apps/gridcraft)
-   [GitHub库](https://github.com/storytold/gridcraft)
-   [ArtCraft](https://getartcraft.com/)
-   [不和谐社会](https://discord.gg/artcraft)

## 常见问题

### gridcraft-preview 是什么？

只读的XLSX/XLS电子表格浏览器的网络，由GridCraft提供支持

### 如何安装 gridcraft-preview？

在项目目录运行 npm install gridcraft-preview，或使用 pnpm add / yarn add / bun add。

### gridcraft-preview 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### gridcraft-preview 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### gridcraft-preview 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### gridcraft-preview 可以商用吗？

gridcraft-preview 使用 \(MIT OR Apache-2\.0\) 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### gridcraft-preview 还在维护吗？

最新版本 0\.1\.0 发布于 2026/11/04（今天）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。