## 项目概述

Extend UI 是一套开源 React 组件库，专为文档代理、面向用户的文档流程和内部工具而设计。它由 Extend 公司开发并维护，最初作为其内部组件层，现已开源并采用 MIT 许可证。该库包含 14 个组件和示例，涵盖 PDF、DOCX、XLSX 查看器、边界框引用、文件上传、文件缩略图、电子签名、文档拆分、布局块以及类似 Finder 的文件浏览等功能。所有组件均可完全自定义，并通过 shadcn 组件注册表分发。

## 核心功能

- **文档查看器**：支持 PDF、DOCX、XLSX 格式的查看器组件。
- **边界框引用**：在 PDF 页面上显示字段级引用，支持可编辑表单控件和 JSON 差异对比。
- **布局块**：检查 OCR 和布局输出，支持可选择的块、置信度、Markdown 文本和 PDF 叠加层。
- **文件系统浏览器**：类似 Finder 的文件浏览器，支持图标、列表、列和图库视图，并可打开 PDF、DOCX、XLSX 和图像文件。
- **文件上传与缩略图**：提供文件上传组件和文件缩略图组件。
- **电子签名**：支持电子签名组件。
- **文档拆分**：支持文档拆分功能。
- **完全可定制**：组件以源代码形式安装，可自由修改以适应应用需求。

## 适用与不适用场景

**适用场景：**

- 需要构建文档查看、审阅或文件管理界面的产品。
- 需要为文档代理或内部工具提供用户友好的文档交互组件。
- 希望使用可编辑的 React 和 Tailwind 代码，并集成到设计系统或原型工具中。

**不适用场景：**

- 需要开箱即用的完整文档处理解决方案，而非组件库。
- 项目不使用 React 或 Tailwind CSS。
- 需要非 MIT 许可证的组件。

## 技术架构与依赖

- **语言**：TypeScript
- **框架**：React
- **样式**：Tailwind CSS
- **分发方式**：通过 shadcn 组件注册表，使用 `npx shadcn@latest add @extend/<component>` 安装。
- **依赖**：组件依赖应用已有的基础组件（如 Button、Select、Dialog、ScrollArea、Tooltip），并假设使用 `@/components/ui` 别名。
- **构建工具**：使用 pnpm 进行开发，运行 `pnpm install` 和 `pnpm v4:dev` 启动开发服务器。

## 安装与快速开始

1. 使用 shadcn CLI 安装组件，例如：

   ```bash
   npx shadcn@latest add @extend/pdf-viewer
   ```

2. 在应用中导入并渲染组件：

   ```tsx
   import { PDFViewer } from "@/components/ui/pdf-viewer"

   export default function Page() {
     return <PDFViewer file="/sample.pdf" className="h-[720px]" />
   }
   ```

3. 如果项目使用不同的别名或设计系统路径，请更新生成的导入路径，或在安装前在 `components.json` 中设置别名。

## 典型使用方法

### 布局块

```bash
npx shadcn@latest add @extend/layout-blocks-block
```

```tsx
import type { ParsedOcrOutput } from "@/components/ui/layout-blocks"
import { OcrBlocksBlock } from "@/components/blocks/layout-blocks-block"

const output: ParsedOcrOutput = {
  chunks: [
    {
      blocks: [
        {
          id: "title",
          type: "heading",
          content: "Statement of Work",
          metadata: {
            page: { number: 1, width: 612, height: 792 },
            avgOcrConfidence: 0.99,
          },
          boundingBox: { left: 72, top: 96, right: 360, bottom: 124 },
        },
      ],
    },
  ],
}

export default function Page() {
  return <OcrBlocksBlock file="/documents/statement.pdf" output={output} />
}
```

### 边界框引用

```bash
npx shadcn@latest add @extend/bounding-box-citations-block
```

```tsx
import type { ReviewField } from "@/components/ui/bounding-box-citations"
import { HumanReviewBlock } from "@/components/blocks/bounding-box-citations-block"

const fields: ReviewField[] = [
  {
    key: "invoice_total",
    schema: {
      type: "number",
      title: "Invoice total",
      description: "Total amount due on the invoice.",
    },
    actual: 1280.5,
    expected: 1280.5,
    location: {
      page: 1,
      area: { left: 62, top: 82, width: 22, height: 4 },
    },
  },
]

export default function Page() {
  return (
    <HumanReviewBlock
      file="/documents/invoice.pdf"
      fields={fields}
      className="h-[720px]"
    />
  )
}
```

### 文件系统浏览器

```bash
npx shadcn@latest add @extend/file-system-block
```

```tsx
import type { FileSystemItem } from "@/components/ui/file-system"
import { FileSystemBlock } from "@/components/blocks/file-system-block"

const items: FileSystemItem[] = [
  {
    kind: "folder",
    path: "reports/",
    hasChildren: true,
  },
  {
    kind: "file",
    path: "bank-statement.pdf",
    contentType: "application/pdf",
    url: "/documents/bank-statement.pdf",
    previewImageUrl: "/documents/bank-statement-preview.png",
  },
]

export default function Page() {
  return (
    <FileSystemBlock
      items={items}
      title="Documents"
      defaultView="icons"
      className="h-[720px]"
      getFileUrl={(file) =>
        `/api/files/sign?path=${encodeURIComponent(file.path)}`
      }
      loadChildren={async ({ path }) => {
        const response = await fetch(
          `/api/files?prefix=${encodeURIComponent(path)}`
        )
        return response.json()
      }}
    />
  )
}
```

## 配置与部署要点

- **别名配置**：在 `components.json` 中设置别名，使生成的组件导入路径符合项目结构。
- **基础组件**：确保项目已具备 Button、Select、Dialog、ScrollArea、Tooltip 等基础组件，或调整导入路径。
- **开发环境**：使用 pnpm 安装依赖，运行 `pnpm v4:dev` 启动开发服务器，默认端口 4000。
- **生产部署**：组件以源代码形式安装，可直接打包部署，无需额外配置。

## 限制、风险与许可证

- **许可证**：MIT 许可证，允许自由使用、修改和分发。
- **限制**：组件依赖 React 和 Tailwind CSS，不适用于其他框架。
- **风险**：组件以源代码形式提供，可能需要根据项目结构调整导入路径；依赖的基础组件需自行维护。
- **维护状态**：由 Extend 公司维护，用于生产环境，处理数百万页面的工作流，持续更新。

## 官方链接

- 文档：https://www.extend.ai/ui
- GitHub 仓库：https://github.com/extend-hq/ui
- 注册表命名空间：`@extend/*`

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README（https://github.com/extend-hq/ui）
- 分析时间：2025-04-11