# @bigbinary/neeto-pdf-frontend 中文文档

规范地址：https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/

版本：1\.0\.31
npm 元数据更新时间：2026-10-26T04:39:39.343Z
中文译文更新时间：2026-11-08T02:28:41.743Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40bigbinary/neeto-pdf-frontend
原文对照：https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/?lang=original
项目主页：https://github.com/neetozone/neeto-pdf-nano
源码仓库：https://github.com/neetozone/neeto-pdf-nano

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

- 包体积（解压后）：1.4 MB，135 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13
- 运行依赖：3 个
- peer 依赖：qs 6\.16\.1，url 0\.11\.4，yup 0\.32\.11，antd 5\.22\.1，util ^0\.12\.5，axios 1\.20\.0，ramda 0\.29\.0，react 18\.3\.1，buffer ^6\.0\.3，formik 2\.4\.6，i18next 22\.5\.1，pdf-lib 1\.17\.1，zustand 4\.4\.2，dompurify 3\.4\.17，js-logger 1\.6\.1，react-dom 18\.3\.1，classnames 2\.5\.1，pdfjs-dist 6\.2\.108，stream-http 3\.2\.0，tailwindcss 4\.1\.17，lucide-react ^1\.8\.0，react-helmet ^6\.1\.0，os-browserify 0\.3\.0，react-i18next 12\.3\.1，vm-browserify 1\.1\.2，@babel/runtime 7\.29\.7，react-toastify 8\.0\.2，tty-browserify 0\.0\.1，path-browserify ^1\.0\.1，https-browserify 1\.0\.0，mixpanel-browser 2\.45\.0，react-router-dom 5\.3\.3，crypto-browserify 3\.12\.1，source-map-loader 4\.0\.1，stream-browserify ^3\.0\.0，@bigbinary/neetoui 8\.8\.3，@honeybadger-io/js 6\.10\.1，@bigbinary/neeto-cist 1\.0\.17，@honeybadger-io/react 6\.1\.25，@tanstack/react-query 5\.59\.20，@bigbinary/neeto-atoms 1\.1\.0，@bigbinary/neeto-icons 1\.20\.89，@bigbinary/neeto-molecules 5\.9\.7，@tanstack/react-query-devtools 5\.59\.20，@bigbinary/neeto-commons-frontend 4\.14\.4，@bigbinary/neeto-filters-frontend 4\.5\.1
- 首次发布：2026-07-15T06:55:29.503Z
- 最新版本发布：2026-10-26T04:39:39.128Z
- 近 30 天下载量：2432（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

一个回波作为新纳米结构,配置,数据等的真理来源.

## 安装

```sh
npm install @bigbinary/neeto-pdf-frontend
```

也可以使用：`pnpm add @bigbinary/neeto-pdf-frontend`、`yarn add @bigbinary/neeto-pdf-frontend`、`bun add @bigbinary/neeto-pdf-frontend`

## README

# 需要 - pdf - nano 数据

`neeto-pdf-nano` 添加可重复使用的 PDF 模板、 字段映射、 预览、 下载、, 和电子邮件附件到 Rails and React 应用程序.

它作为两个包裹:

-   `neeto-pdf-engine`:"铁路"发动机.
-   `@bigbinary/neeto-pdf-frontend`: React 组件库.

## 目录

-   [纳米能提供什么](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-what-the-nano-provides)
-   [东道产品必须提供什么](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-what-the-host-product-must-provide)
-   [快开始](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-quick-start)
    -   [后端引擎](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-backend-engine)
    -   [前端软件包](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-frontend-package)
-   [构成部分](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-components)
    -   [页 次](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-documents-page)
    -   [编辑器](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-editor)
    -   [电子邮件附件控制](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-email-attachment-controls)
-   [服务器侧渲染](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-server-side-rendering)
-   [API 终点](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-api-endpoints)
-   [测试](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-testing)
-   [地方发展](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-local-development)
-   [出版](https://npmcn.com/package/%40bigbinary/neeto-pdf-frontend/#readme-publishing)

## 纳米能提供什么

铁路机车拥有:

-   PDF 文档存储和活性存储模板附件.
-   租户范围文档 API.
-   绘制持久性和验证图.
-   服务器侧 PDF 渲染 .
-   文件克隆和输出文件名模板 .

前端软件包拥有:

-   PDF 文档列表和上传流.
-   野外映射编辑器.
-   预览和下载控制.
-   电子邮件附件选择和预览组件 .

以下示例使用当前 `@bigbinary/neeto-pdf-frontend/v2` 进入点。 软件包还保留了现有软件包的根入点 消费者.

## 东道产品必须提供什么

主办方提供 **拥有者** 可重复使用的模板和a **数据记录** 其值填充每个 PDF 。 它还拥有:

-   租户授权和产品路线.
-   外地正常化和价值格式化.
-   预览-录相页.
-   电子邮件设置和附件发送.
-   酌情进行所有者克隆和生命周期清理.

主机必须使用 Rails, Active Record, Active Survey, PostgreSQL, 以及 `NeetoCommonsBackend::Api::BaseController`。前端软件包使用端点 于 `package.json`,包括 React Query, Axios, i18next, 福尔米克,泰尔温德CSS, 需要Atoms, 需要UI, 和需要Molecules.

## 快开始

### 后端引擎

#### 1\. 安装发动机

```ruby
source "NEETO_GEM_SERVER_URL" do
  gem "neeto-pdf-engine"
end
```

```sh
bundle install
```

#### 2\. 复制文件迁移

```text
db/migrate/20260706120000_create_neeto_pdf_engine_documents.rb
```

给它免费的宿主时间戳,然后运行:

```sh
bundle exec rails db:migrate
```

不运行普通引擎迁移安装器; 此寄存器包含 不相关的模板迁移 . `owner_id` 是一个UUID。 调整和测试复制的 如果所有者使用另一种主键类型,则首先迁移.

#### 3\. 配置所有者并渲染上下文

创建 `config/initializers/neeto_pdf_engine.rb`数字 :

```ruby
# frozen_string_literal: true

NeetoPdfEngine.owner_class = "DocumentOwner"
NeetoPdfEngine.render_context_resolver = lambda do |owner:, record_id:|
  PdfDocuments::RenderContextResolver.call(owner:, record_id:)
end
```

替换 `DocumentOwner` 与真正的模型。 一定是现在的组织 或支持 `where(organization: current_organization)`添加:

```ruby
class DocumentOwner < ApplicationRecord
  belongs_to :organization

  has_many :neeto_pdf_documents,
    as: :owner,
    class_name: "NeetoPdfEngine::Document",
    dependent: :destroy
end
```

执行渲染语境 :

```ruby
module PdfDocuments
  class RenderContextResolver
    def self.call(owner:, record_id:)
      record = owner.data_records.find(record_id) # Use the real association.

      {
        value_resolver: ValueResolver.new(owner:, record:),
        filename_context: { id: record.id }
      }
    end
  end
end
```

总是通过所有者找到数据记录. 数值解析器必须响应 改为 `call(mapping)`数字 :

```ruby
module PdfDocuments
  class ValueResolver
    def initialize(owner:, record:)
      @owner = owner
      @record = record
    end

    def call(mapping)
      return system_value(mapping["field_slug"]) if mapping["source"] == "system"

      value_for(mapping["field_slug"])
    end

    private

      attr_reader :owner, :record

      def value_for(field_slug)
        # Return the host-formatted value.
      end

      def system_value(field_slug)
        case field_slug
        when "form_name" then owner.name
        when "submission_id" then record.id
        when "submission_date" then I18n.l(record.created_at, format: :long)
        else ""
        end
      end
  end
end
```

内置的系统密钥是 `form_name`, (中文(简体) ), `submission_id`,以及 `submission_date`; 主机定义了它们的含义. 对于图像,返回 :

```ruby
{
  type: "image",
  data: attachment.download,
  content_type: attachment.blob.content_type
}
```

使用 `image/svg+xml` 用于SVG数据。 返回文本,一个数字,或 `""` 其他费用 测绘.

#### 4\. 安装和保护发动机

挂载引擎 :

```ruby
mount NeetoPdfEngine::Engine, at: "/neeto_pdf"
```

```js
const PDF_API_BASE_URL = "/neeto_pdf/api/v1";
```

引擎认证和瞄准镜所有者为当前组织. 东道主 必须添加服务器授权到 `NeetoPdfEngine::Api::V1::DocumentsController`, (中文(简体) ), 包括采取行动. `canManage` 只更改用户界面.

#### 5\. 处理东道主生命周期规则

适用时,添加 `NeetoPdfEngine::Document` 用于主机焚化, 克隆 PDF 带有克隆所有者的文档,并保存重新映射 `record_id` 要克隆的数值 字段.

### 前端软件包

#### 1\. 安装软件包和PDF运行时间

```sh
yarn add @bigbinary/neeto-pdf-frontend pdf-lib@1.17.1 pdfjs-dist@6.2.108
```

软件包使用主机的 Axios 大小写转换器, React 查询提供者,以及 i18next example. (原始内容存档于2018-09-29).

#### 2\. 包括样式和翻译

没有 PDF 样式表 。 保持需要UI和需要Molecules风格的功能 做尾风扫描 `@bigbinary` 软件包。 对于 Tailwind CSS 4, 调整此路径 相对于主机样式表 :

```css
@import "tailwindcss" important;
@source "../../../../node_modules/@bigbinary";
```

标准的 neto- commons 构建负载包翻译. 其他建筑必须 合并 `@bigbinary/neeto-pdf-frontend/app/javascript/src/translations/en.json` 输入他们的 i18 next 资源.

#### 3\. 为PDF.js工人服务

添加:

```json
{
  "scripts": {
    "sync:pdf-worker": "mkdir -p public && cp -f node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdf.worker.min.js"
  }
}
```

运行它之前 `dev` 财务报告和审定财务报表 `build`。结果为:

```text
/pdf.worker.min.js
```

生成的工人可能在基特被忽略.

## 构成部分

### 页 次

```jsx
import { PdfDocumentsPage } from "@bigbinary/neeto-pdf-frontend/v2";

const PdfDocuments = ({ ownerId, emailAttachments }) => (
  <PdfDocumentsPage
    apiBaseUrl="/neeto_pdf/api/v1"
    canManage={canManagePdfDocuments}
    emailAttachments={emailAttachments}
    ownerId={ownerId}
    onOpenEditor={document => openEditor(document.id)}
  />
);
```

该页列出表格中的文档。 上传一个直接打开编辑器 因此,绘图是下一步,而不是单独的决定.

-   `onOpenEditor` 接收完整的文档对象。 两者都叫做当 在成功上传后打开行并右侧 .
-   `emailAttachments` 描述文档可附加的电子邮件, 如 `[{ key, label, dataTestId, onSelect }]`。它驱动“从 PDF 到电子邮件 ” 菜单。 物品只导航; 邮件页上有附着的,不是这里.
-   `renderHeader` 财务报告和审定财务报表 `renderContent` 可以将页面放入主机布局.
-   过 `canManage` 当然 它只会改变UI.

上传使用 netoMolecules `FileUpload`。主动存储必须返回 `signedId`。 。 。 . 模板必须是10 MB或更少的PDF.

### 编辑器

```jsx
import { PdfEditorPage } from "@bigbinary/neeto-pdf-frontend/v2";

<PdfEditorPage
  apiBaseUrl="/neeto_pdf/api/v1"
  canManage={canManagePdfDocuments}
  documentId={documentId}
  emailAttachments={emailAttachments}
  fields={pdfFields}
  homeUrl={pdfDocumentsUrl}
  isPreviewLoading={isPreviewLoading}
  mode={mode}
  ownerId={ownerId}
  previewPage={previewPage}
  previewRecord={previewRecord}
  previewTotal={previewTotal}
  onBack={goToPdfDocuments}
  onModeChange={setMode}
  onPreviewPageChange={setPreviewPage}
/>;
```

使用真实 `homeUrl`。 。 。 . `mode` 财务报告和审定财务报表 `onModeChange` 仅用于 主机控制模式状态 .

#### 字段形状

```js
const pdfField = {
  id: "field-id",
  key: "stable-field-key",
  recordId: "field-id",
  slug: "stable-field-key",
  label: "Display label",
  kind: "email",
  renderType: "text",
  icon: EmailIcon,
  typeLabel: "Email",
};
```

使用一个稳定 `recordId`,纯文本标签,以及 `renderType: "image"` 仅限 图像数据。 排除不能包含值的字段.

#### 预览记录形状

```js
const previewRecord = { id: "data-record-id" };
```

编辑器将这个ID发送到渲染端点. 引擎就打来 `render_context_resolver`,保留预览和附件渲染 值路径.

### 电子邮件附件控制

```jsx
import {
  PdfAttachmentSelector,
  PdfAttachmentsPreview,
} from "@bigbinary/neeto-pdf-frontend/v2";
import { Form, Formik } from "formik";

<Formik
  initialValues={{ pdfDocumentIds: persistedPdfDocumentIds }}
  onSubmit={saveEmailSettings}
>
  <Form>
    <PdfAttachmentSelector
      documents={pdfDocuments}
      maxTotalSize={25 * 1024 * 1024}
    />
    <PdfAttachmentsPreview documents={pdfDocuments} />
  </Form>
</Formik>;
```

```text
Formik:       pdfDocumentIds
Frontend API: customFields.pdfDocumentIds
Rails:        custom_fields["pdf_document_ids"]
```

许可 `custom_fields[:pdf_document_ids]` 作为数组。 删除或 保存前无法访问 ID 。 用同一所有者ID获取文档 编辑。 过 `maxTotalSize` 以字节表示,防止选择其组合 模板大小将超过电子邮件附件限制 。 当一个选择会 超过限制, 选择器保留它并解释文档大小 和剩余空间.

## 服务器侧渲染

```ruby
render_context = PdfDocuments::RenderContextResolver.call(
  owner:,
  record_id: record.id
)

owner.neeto_pdf_documents.where(id: selected_pdf_document_ids).map do |document|
  NeetoPdfEngine::Documents::RendererService.new(
    document,
    **render_context
  ).process
end
```

每项结果包括:

```ruby
{
  filename: "document-record-id.pdf",
  mime_type: "application/pdf",
  content: "<binary PDF>",
  truncated_mapping_ids: []
}
```

主机附加或编码 `content`。加密的 PDF 提升 `NeetoPdfEngine::EncryptedDocumentError`。内置字体支持 ASCII 和 Latin-1;服务器渲染时会去掉其他字符.

## API 终点

发动机安装在 `/neeto_pdf`数字 :

```text
GET    /neeto_pdf/api/v1/documents
POST   /neeto_pdf/api/v1/documents
GET    /neeto_pdf/api/v1/documents/:id
PATCH  /neeto_pdf/api/v1/documents/:id
PUT    /neeto_pdf/api/v1/documents/:id
PATCH  /neeto_pdf/api/v1/documents/:id/template_file
POST   /neeto_pdf/api/v1/documents/:id/clone
POST   /neeto_pdf/api/v1/documents/:id/render
DELETE /neeto_pdf/api/v1/documents/:id
```

每个请求都需要 `owner_id`; 客户端无法选择 `owner_type`. 渲染器 还要求 `record_id` 并接受临时 `mappings` 不持续 他们。 上传接受已签名的 blob ID 或多部分的主动存储 `template_file`。 。 。 .

默认输出文件名是 :

```text
<parameterized-document-name>-{{id}}.pdf
```

`filename_context[:id]` 替换 `{{id}}`。 。 。 .

## 测试

在发布前运行 Rails 测试套件并构建前端软件包 更改:

```sh
bundle exec rails test
yarn build
```

对于仅用于文档的更改,也运行:

```sh
yarn prettier --check README.md
git diff --check -- README.md
```

## 地方发展

```ruby
gem "neeto-pdf-engine", path: "../neeto-pdf-nano"
```

对于本地前端工作,请遵循 [前端软件包开发指南](https://neetozone.neetokb.com/p/a-d34cb4b0)。 。 。 .

## 出版

跟着 [构建和释放软件包](https://neetozone.neetokb.com/articles/building-and-releasing-packages) 用于发布前端软件包和 Rails 引擎的指南.

## 常见问题

### @bigbinary/neeto-pdf-frontend 是什么？

一个回波作为新纳米结构,配置,数据等的真理来源\.

### 如何安装 @bigbinary/neeto-pdf-frontend？

在项目目录运行 npm install @bigbinary/neeto-pdf-frontend，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：qs（6\.16\.1）、url（0\.11\.4）、yup（0\.32\.11）、antd（5\.22\.1）、util（^0\.12\.5）、axios（1\.20\.0）、ramda（0\.29\.0）、react（18\.3\.1）、buffer（^6\.0\.3）、formik（2\.4\.6）、i18next（22\.5\.1）、pdf-lib（1\.17\.1）、zustand（4\.4\.2）、dompurify（3\.4\.17）、js-logger（1\.6\.1）、react-dom（18\.3\.1）、classnames（2\.5\.1）、pdfjs-dist（6\.2\.108）、stream-http（3\.2\.0）、tailwindcss（4\.1\.17）、lucide-react（^1\.8\.0）、react-helmet（^6\.1\.0）、os-browserify（0\.3\.0）、react-i18next（12\.3\.1）、vm-browserify（1\.1\.2）、@babel/runtime（7\.29\.7）、react-toastify（8\.0\.2）、tty-browserify（0\.0\.1）、path-browserify（^1\.0\.1）、https-browserify（1\.0\.0）、mixpanel-browser（2\.45\.0）、react-router-dom（5\.3\.3）、crypto-browserify（3\.12\.1）、source-map-loader（4\.0\.1）、stream-browserify（^3\.0\.0）、@bigbinary/neetoui（8\.8\.3）、@honeybadger-io/js（6\.10\.1）、@bigbinary/neeto-cist（1\.0\.17）、@honeybadger-io/react（6\.1\.25）、@tanstack/react-query（5\.59\.20）、@bigbinary/neeto-atoms（1\.1\.0）、@bigbinary/neeto-icons（1\.20\.89）、@bigbinary/neeto-molecules（5\.9\.7）、@tanstack/react-query-devtools（5\.59\.20）、@bigbinary/neeto-commons-frontend（4\.14\.4）、@bigbinary/neeto-filters-frontend（4\.5\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bigbinary/neeto-pdf-frontend 支持 TypeScript 吗？

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

### @bigbinary/neeto-pdf-frontend 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bigbinary/neeto-pdf-frontend 需要什么版本的 Node\.js？

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

### @bigbinary/neeto-pdf-frontend 可以商用吗？

@bigbinary/neeto-pdf-frontend 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bigbinary/neeto-pdf-frontend 的下载量有多少？

根据 npm 官方下载统计，@bigbinary/neeto-pdf-frontend 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,432 次，日均约 81 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bigbinary/neeto-pdf-frontend 还在维护吗？

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