# @alggtta/editor 中文文档

规范地址：https://npmcn.com/package/%40alggtta/editor/

版本：7\.0\.6
npm 元数据更新时间：2026-11-06T12:03:01.269Z
中文译文更新时间：2026-11-06T23:46:10.541Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40alggtta/editor
原文对照：https://npmcn.com/package/%40alggtta/editor/?lang=original
项目主页：https://alggtta.com/

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

- 包体积（解压后）：11.6 MB，851 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：58 个
- peer 依赖：yjs ^13\.6\.31，katex ^0\.18\.4，react ^18\.2\.0 \|\| ^19\.0\.0，fflate ^0\.8\.3，openai \>=6\.10\.0 \<8\.0\.0，mammoth ^1\.13\.0，mermaid ^11\.12\.3，react-dom ^18\.2\.0 \|\| ^19\.0\.0，@tiptap/pm 3\.31\.3，typescript \>=5\.3，html2pdf\.js ^0\.14\.0，y-indexeddb ^9\.0\.12，y-protocols ^1\.0\.6，@tiptap/core 3\.31\.3，@tiptap/react 3\.31\.3，@anthropic-ai/sdk \>=0\.70\.0 \<1\.0\.0，@google/generative-ai ^0\.24\.1，@tanstack/react-table ^9\.2\.6，@tiptap/extension-bubble-menu 3\.31\.3，@tiptap/extension-floating-menu 3\.31\.3
- 首次发布：2026-03-02T07:28:39.514Z
- 最新版本发布：2026-11-06T12:03:01.077Z
- 近 30 天下载量：2155（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

带有 Tiptap 3.x 和 DaisyUI 5 的 Alggtta 编辑器

## 安装

```sh
npm install @alggtta/editor
```

也可以使用：`pnpm add @alggtta/editor`、`yarn add @alggtta/editor`、`bun add @alggtta/editor`

## README

# @alggtta/编辑器

React/TypeScript Notion风格编辑器以Tiptap 3,Tailwind CSS v4和DaisyUI 5.

`@alggtta/editor` (core-first since v3)保持了默认包专注于核心编辑器. 数据库块、人鱼、人工智能和出口辅助工具等重功能可通过选择进入子路径的进口获得.

## 安装

```bash
npm install @alggtta/editor --save-exact
```

在您的应用程序中安装对等依赖 :

```bash
npm install react react-dom @tiptap/core@3.31.3 @tiptap/extension-bubble-menu@3.31.3 @tiptap/extension-floating-menu@3.31.3 @tiptap/pm@3.31.3 @tiptap/react@3.31.3 yjs@13.6.33 y-protocols@1.0.7 --save-exact
```

保持所有 Tiptap 单通对等点的准确性 `3.31.3`。需要提示包 匹配补丁版本。 此补丁修正 [GHSA-cp6q-959q-f8rh](https://github.com/advisories/GHSA-cp6q-959q-f8rh)· ; 3.28.x–3.29.x还有一个已知的回放节点维尤心回放. `@tiptap/y-tiptap` 使用其 独立 `3.0.10` 释放线. `yjs@13.6.33` 财务报告和审定财务报表 `y-protocols@1.0.7` 也为 需要单通同位素,因为主条目急切链接协作 扩展图.

Yarn Classic 1.x 消费者必须使用同样准确的同平方 `--ignore-optional`数字 :

```bash
yarn add --ignore-optional --exact @alggtta/editor react react-dom @tiptap/core@3.31.3 @tiptap/extension-bubble-menu@3.31.3 @tiptap/extension-floating-menu@3.31.3 @tiptap/pm@3.31.3 @tiptap/react@3.31.3 yjs@13.6.33 y-protocols@1.0.7
```

旗子跳过Yarn安装中的每个可选依赖性. 它的重要性 效果在此图中阻碍已解决的冗余新菜单副本 从 `@tiptap/react`'可选范围; 上面两个精确的根菜单包 保留菜单功能。 明确安装任何其他可选 包装您的应用程序需求 。 这个工作是Yarn Classic 1.x特有的,而不是a 现代要求.

## 类型脚本

最小类型脚本 : `>=5.3`

`typescript` 被宣布为 **选项** 对等依赖性 —— JavaScript 消费者需要 没什么 TypeScript 消费者需要 5.3 或更新,因为通用JS 声明服务 改为 `exports["*"].require.types` (单位:千美元)`dist/**/*.d.cts`注释其类型边缘 仅限无害环境管理的一揽子措施`yjs`, (中文(简体) ), `@tanstack/react-table`与 `with { "resolution-mode": "import" }`。TypeScript 只解析来自 5.3 的属性 上;上;上;上;下;下;上;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下;下 **语法错误** (单位:千美元)`TS1005`这 `skipLibCheck: true` 已经 **没有** 压制,因此CJS类型表面无法完全装入.

测量: 5.2.2 → `TS1005` (tsc出口2,有无) `skipLibCheck`); 5.3.2 − 干净. 无害环境管理宣言`dist/**/*.d.ts`)没有这种属性,对老年人的工作 编译器——楼层仅适用于 `require` 条件.

生产用途需要阿尔格塔代币. 本地主机开发仍然以符号形状的值工作, 例如 `tok_dev`。 。 。 .

## 基本用途

```tsx
import { AlggttaEditor } from '@alggtta/editor'
import '@alggtta/editor/styles.css'

export function EditorPage() {
  return (
    <AlggttaEditor
      token={process.env.NEXT_PUBLIC_ALGGTTA_TOKEN ?? ''}
      content="<h1>Hello</h1><p>Type / for commands.</p>"
      onUpdate={({ editor, json, html, text }) => {
        console.log({ json, html, text })
      }}
    />
  )
}
```

## Next.js App路由器

从客户端组件使用编辑器 .

```tsx
'use client'

import { AlggttaEditor } from '@alggtta/editor'
import '@alggtta/editor/styles.css'

export default function EditorClient() {
  return (
    <AlggttaEditor
      token={process.env.NEXT_PUBLIC_ALGGTTA_TOKEN ?? ''}
      variant="document"
      onUpdate={({ json }) => {
        void fetch('/api/document', {
          method: 'POST',
          body: JSON.stringify(json),
        })
      }}
    />
  )
}
```

## Vite / CRA / 反应

```tsx
import { AlggttaEditor } from '@alggtta/editor'
import '@alggtta/editor/styles.css'

export function App() {
  return (
    <AlggttaEditor
      token={import.meta.env.VITE_ALGGTTA_TOKEN}
      placeholder="Write something..."
    />
  )
}
```

## 视觉变体

使用 `variant` 使编辑器适应不同的布局 :

```tsx
<AlggttaEditor token={token} variant="document" />
<AlggttaEditor token={token} variant="embedded" />
<AlggttaEditor token={token} variant="bare" />
```

-   `document`: 带有舒适垫装的默认文档画布.
-   `embedded`:用于仪表板和管理员面板的紧凑外壳.
-   `bare`: 当您的应用程序拥有布局时, 最小包装 .

## 许可证UI

`token` 需要时间. `verifyEndpoint` 默认为 `https://cdn.alggtta.com`。 。 。 .

```tsx
<AlggttaEditor
  token={token}
  licenseFallback={({ error }) => (
    <div role="alert">Editor license check failed: {error}</div>
  )}
/>
```

## 子路径导入

```ts
import { useAlggttaEditor, useAutosave } from '@alggtta/editor/headless'
import { definePlugin, resolvePlugins, PluginSlot } from '@alggtta/editor/plugin'
import { createSchedulePlugin, ScheduleEditor } from '@alggtta/editor/schedule'
import { createGuideFlowPlugin } from '@alggtta/editor/guideflow'
import { createMathPlugin } from '@alggtta/editor/math'
import { createDatabaseExtensions, databaseSlashCommands } from '@alggtta/editor/database'
import { createMermaidExtensions, mermaidSlashCommands } from '@alggtta/editor/mermaid'
import { createAIExtensions, getDocumentContext } from '@alggtta/editor/ai'
import { markdownToHtml, htmlToMarkdown } from '@alggtta/editor/export'
import { LicensedGate, useLicenseVerification } from '@alggtta/editor/license'
import { useComments, CommentSidebar } from '@alggtta/editor/comments'
import { createCollaborationExtensions, usePresence } from '@alggtta/editor/collab'
import { UniversalEditor } from '@alggtta/editor/legacy'
```

主要条目包括核心块:段落,标题一至三,列表,任务列表,引文,分页,链接,突出显示,图像,表格,代码块,斜线菜单,泡泡菜单,和拖动手柄. 过 `preset="full"` 并挂载高级块(呼叫、切换、列、嵌入、文件附件、引用、维基链接、注释、查找/替换、同步块)及其斜线命令。 数学( KaTeX) 不包括在 `full` 以保持捆绑的倾斜——它是一个沉重的可选对等点; 添加 `createMathPlugin()` 从 `@alggtta/editor/math` 通过 `extensionConfig.plugins` (或 `MathExtension`编号 :`InlineMathExtension` 从 `@alggtta/editor/legacy` 通过 `extensionConfig.customExtensions`如果你需要的话.

用于节点20上的数学,使用 `npm install --save-exact katex@0.18.4`. KaTeX 0.18.5增加了一个CLI依赖性,需要22.12+节点,因此该版本的引擎限制节点20安装失败. 编辑器保留相容性 `^0.18.4` 对等范围;工作空间/演示测试在节点22上使用0.18.5.

主要条目还输出框架不可知性 `mount(el, props)` 工厂 `<alggtta-editor>` 网络组件`defineAlggttaEditorElement()`页:1 `getWikiLinks(doc)` 链接编号 API。 为了保持核心精度,更重的页色组件(`VersionHistory`, (中文(简体) ), `PageMeta`, (中文(简体) ), `TableOfContents`住在这里 `@alggtta/editor/legacy`,以及版本/移民公用事业`createPageVersionFromAITransaction`, (中文(简体) ), `MigrationRegistry`(单位:千美元) `@alggtta/editor/headless`。 。 。 .

### 嵌入到任何地方( 没有 React app)

这个 `mount(el, props)` 工厂和 `<alggtta-editor>` 任意网络组件工作 堆栈。 送来的包裹 `cdn.alggtta.com` 保留 外部反应,所以装入 `react` 编号 : `react-dom` UMD Globals先是编辑. 每个CDN资产是: 表示,所以通过 `?token=` 打开 **两者** 脚本和样式表—— a `<link>` 编号 : `<script>` 标记不能发送授权信头( 无令牌 ~ 401); 无效、已过期或域名错误 ~ 403 :

```html
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<link rel="stylesheet" href="https://cdn.alggtta.com/editor.css?token=YOUR_TOKEN" />
<script src="https://cdn.alggtta.com/editor.umd.js?token=YOUR_TOKEN"></script>
<alggtta-editor token="YOUR_TOKEN" preset="full"></alggtta-editor>
<!-- or imperatively: window.AlggttaEditor.mount('#el', { token, preset: 'full' }) -->
```

> 从npm你可以打电话 `mount` 编号 : `defineAlggttaEditorElement` 直接( 反应) ——不需要UMD Globals.

> 建维基? 编辑们运送原始人`[[` 编号 : `@` 触发器, `getWikiLinks`自动保存。 持久储存——回行链路、全文搜索和 版本 - 由 **私人配套软件包 `@alggtta/wiki-store`**, (中文(简体) ), 应要求向被许可人提供 [https://alggtta.com (中文(中国大陆) )](https://alggtta.com/)) (中文(简体) ).

可选条目可能要求它们的对等依赖性,例如 `@tanstack/react-table@^9.1.2` 用于数据库块和 `mermaid` 为美人鱼图。 数据库子路径使用 TanStack Table v9 的特征解析 API,与 v8 不相容. 进出口UI 载荷 `html2pdf.js` 财务报告和审定财务报表 `mammoth` 仅当使用 PDF 或 DOCX 动作时.

## 可选特性组成

```tsx
import { AlggttaEditor } from '@alggtta/editor'
import { createDatabaseExtensions, databaseSlashCommands } from '@alggtta/editor/database'

<AlggttaEditor
  token={token}
  extensionConfig={{
    customExtensions: createDatabaseExtensions(),
    customSlashCommands: databaseSlashCommands,
  }}
/>
```

导出 UI 也是选入 。 导入从 `/export` 并注入编辑页脚:

```tsx
import { AlggttaEditor } from '@alggtta/editor'
import { ExportDropdown, exportSlashCommands } from '@alggtta/editor/export'

<AlggttaEditor
  token={token}
  extensionConfig={{
    customSlashCommands: exportSlashCommands,
  }}
  renderFooterControls={({ editor, allowedFeatures }) =>
    allowedFeatures.includes('*') || allowedFeatures.includes('export')
      ? <ExportDropdown editor={editor} />
      : null
  }
/>
```

只曝光您实际注册或渲染的特性的可选命令 .

## 插件开发

使用轻量级 `/plugin` 输入捆绑自定义 Tiptap 扩展并 将命令切入挂载时间插件 。 插件命令 ID 和扩展名 命令 id 也不可能与主机声明的 id 相冲突 `customSlashCommands`。 。 。 .

```tsx
import { AlggttaEditor } from '@alggtta/editor'
import { ClockIcon } from '@heroicons/react/24/outline'
import { Extension, definePlugin } from '@alggtta/editor/plugin'
import '@alggtta/editor/styles.css'

const timestampPlugin = definePlugin({
  id: 'com.example.timestamp',
  version: '1.0.0',
  extensions: [Extension.create({ name: 'exampleTimestampBehavior' })],
  slashCommands: [
    {
      id: 'com.example.timestamp.insert',
      title: 'Insert timestamp',
      description: 'Insert the current time',
      icon: ClockIcon,
      command: (editor) => {
        editor.chain().focus().insertContent(new Date().toISOString()).run()
      },
    },
  ],
})

export function PluginEditor() {
  return (
    <AlggttaEditor
      token={import.meta.env.VITE_ALGGTTA_TOKEN}
      extensionConfig={{ plugins: [timestampPlugin] }}
    />
  )
}
```

当编辑器创建时, 插件集是固定的; 重新挂载以更改 计划 外部插件包必须保留 React 和全部 Tiptap/ProseMiror 软件包作为对等器/外部,不得导入 `@tiptap/starter-kit` 在运行时间, 并且必须分别发布他们的CSS. 只安装信任的插件: 它们运行 与主机页面的完整JavaScript权限. 声明网络组件 属性和主机 CDN/UMD 构建不装入任意插件包.

见大众 [插件开发指南](https://alggtta.com/docs#plugin-development) 用于最小插件定义和注册示例,浏览器侧静态 渲染、文档相容性、包装和安全指导.

## 嵌入式框架安全

与 `preset="full"`,则 `embed` 块显示 YouTube, Figma, CodePen 和 X/Twitter 内容 在沙盒 Iframes。 框架 URL 从固定框架的识别提供者链接重建 主机,但这只覆盖一个帧开始的URL, YouTube和Figma帧得到 `allow-same-origin` 旁边 `allow-scripts`在您让嵌入加载前, 主机 应用程序必须:

-   为编辑页服务 `Cross-Origin-Opener-Policy: same-origin`· ;
-   发送 `Content-Security-Policy: frame-ancestors 'none'` (或 `X-Frame-Options: DENY`继续 能够携带用户内容的每个答复;
-   从未服务用户提供的 HTML 或 SVG 从编辑页源头的内入;
-   在 CSP 中列出它想要的框架主机 `frame-src` (单位:千美元)`https://www.youtube.com`, (中文(简体) ), `https://www.figma.com`, (中文(简体) ), `https://codepen.io`, (中文(简体) ), `https://twitframe.com`(三); `default-src 'self'` 独自挡住每个嵌入地.

YouTube 帧携带 `referrerpolicy="strict-origin-when-cross-origin"`因为YouTube 拒绝没有比赛 `Referer`; 覆盖一页 `Referrer-Policy: no-referrer` 这些框,所以 `www.youtube.com` 学习页面来源(而不是其路径或查询). 因为 `allow-same-origin`,帧" `allow` 列表(加速计、自动播放、, 剪贴板-写作、加密介质、陀螺仪、相片) YouTube和Figma;用你自己的盖子 `Permissions-Policy` 需要时页眉( 一个特性) 其许可名单省略了提供者的来源,例如: `gyroscope=()`,不授权给它). 框架文档可以自行导航,也可以打开继承其沙盒的弹出到任意 URL; 前三项要求保留了您来源的这样一页, 无法到达编辑器 页 次.

## 尾风和黛西

邮包船编集CSS at `@alggtta/editor/styles.css`. DaisyUI 内部前缀为 `ue-` 减少与消费应用程序的冲突。 您可以在应用中使用编辑器,无论是否有Tailwind/DaisyUI.

## 从v2迁移

### `onUpdate`

```tsx
// v2
<UniversalEditor onUpdate={(editor) => save(editor.getJSON())} />

// v3
<AlggttaEditor onUpdate={({ json }) => save(json)} />
```

### `UniversalEditor`

`AlggttaEditor` 是建议的组成部分(自v3起)。 前一个 `UniversalEditor` 移徙期间留下的遗存:

```tsx
import { UniversalEditor } from '@alggtta/editor/legacy'
```

### 可选特性

数据库,美人鱼,AI,导出帮助器,GuideFlow块,和调度块不再属于默认核心条目. 导入匹配的子路径并明确通过它的扩展/命令 .

### 可选引用文件计划

导入 `createCitationPlugin` 从 `@alggtta/editor/citations` 并加进 `extensionConfig.plugins` 在将文档装入引用节点之前。 没错 不通过核心或完整的预设安装. `insertCitation({ references, displayText, styleId?, locale? })`, (中文(简体) ), `updateCitation(instanceId, content)` 财务报告和审定财务报表 `deleteCitation(instanceId)` 使用普通编辑器交易和撤销/重写. 每一个命令的参考载 `libraryId`, (中文(简体) ), `itemId` 和可选 `locator`, (中文(简体) ), `label`, (中文(简体) ), `prefix`, (中文(简体) ), `suffix`, (中文(简体) ), `suppressAuthor`本地节点 `schemaVersion: 1` 生成 `instanceId` 幸存 JSON/HTML 重开; 剪贴板粘贴创建新 发生身份证明 拒绝原始的重复ID进口/交易.

`parseCitationData` 验证进口的有效载荷。 验证存储内容之前 初始安装和使用 `setContent(json, { errorOnInvalidContent: true })` 页:1 JSON 替换所以无效的导入无法清除已有的文档 . 引用节点命令存储字面显示文本;它们不获取库或 格式引用自动。 同样的选择 `/citations` 进口 `renderCslDocument` 离线的 CSL 引用和书目渲染 主机提供样式,地点和物品. 它不连接 Word/ Docs 。 无效 引用 HTML 返回到可见的纯文本. 主机必须保存原始文档, 并屏蔽下级保存 引用插件或其节点计划不支持. 完成兼容性 在使用阿特拉斯系统中已公布的准确编辑器版本之前检查。 文件计划 v3 包括带有节点本地有效载荷的引用 v1; 已注册 v2- to- v3 迁移 保留现有内容。 根编辑器显示只读文本预览和 引用 JSON 时自动保存、主机更新和本地Storage 写入 安全上膛 独立的Tiptap主机需要同等的守卫. 后端必须 标出对齐的文档图案; 现有的 Atlas npm 标注不变.

## 许可证

专有地——版权2026 Alggtta. 版权所有。 使用规则如下: 《阿尔格塔商业许可证协定》和有效、有领域限制的许可证 由阿尔格塔发行的代币. 见 [自由主义](https://npmcn.com/package/%40alggtta/editor/LICENSE)。 。 。 .

> 根据《麻省理工学院许可证》公布了直至5.1.1的版本 已经分发的拷贝仍为麻省理工学院;该专有许可证适用 至 6. . . . . .

### 独立特性插件

只安装您需要的特性 `extensionConfig.plugins`数字 : `createSchedulePlugin` 从 `@alggtta/editor/schedule`, (中文(简体) ), `createGuideFlowPlugin` 从 `@alggtta/editor/guideflow`, (中文(简体) ), `createMathPlugin` 从 `@alggtta/editor/math`,则 `createDatabasePlugin`, (中文(简体) ), `createAIPlugin`, (中文(简体) ), `createMermaidPlugin`, (中文(简体) ), `createCommentsPlugin` 工厂在其现有的子路径。 在编译全部时使用核心预设. 附表保留现有 `guideflow` 许可证权利. `createGuideFlowPlugin()` 安装地图、酒店、联系人、分机和工作人员块,因此 `createSchedulePlugin()` 它完全记录了遗产的节点 `guideFlowExtensions` 捆绑: 从 `customExtensions: guideFlowExtensions` 不需要计划或存储 移徙。 打开已有的 GuideFlow 文档时同时安装 。 遗产出口不变.

插件可以提供 React `ui.toolbar`, (中文(简体) ), `ui.sidebar`, (中文(简体) ), `ui.footer` 财务报告和审定财务报表 `ui.overlay` 组件,加载和许可其扩展。 每一贡献在内部 其错误边界: 丢出组件,或 `React.lazy` 块失败 装入,在不卸载编辑器的情况下隐藏并登录。 内重叠 主题编辑器根,没有用户界面贡献 `AlggttaEditor` 不添加插槽包装或 围绕编辑器表面和正文的布局元素. 无头主机可以使用 `PluginSlot` 财务报告和审定财务报表 `useAlggttaEditor().plugins`。见 [插件开发](https://alggtta.com/docs#plugin-development) 用于迁移和UI实例.

### 离线 SSL 核心( 可选) `/citations` 条目)

`mapResearchItemToCsl(id, metadata)` 返回时 `{ item, source, losses }`;当一个字段或创建角色没有忠实的CSL代表时,原有的JSON元数据仍然可用. 离线相容性目录涵盖37个研究项目类型.

`renderCslDocument({ style, locales, locale, items, citations, format })` 创建新的文档范围引用proc引擎,并返回每个背景引用和文献目录条目。 供应独立的 CSL XML 和离线本地化 XML( 请求本地化和 en- US); 没有网络检索或倒置物质 。 引用集群稳定 `id`, (中文(简体) ), `items`,并明确订购正数 `noteIndex` 用于注释样式;项目选项包括定位器、标签、前缀/后缀和pressAuthor. `format` 实值 `text` (违约)或限制安全 `html`。 。 。 .

核心被封为200个项/组,每个组有100个参考文献,每个XML文件有256000个字符,被封为XML嵌入/macros并被封为自有JSON输入. 无效/ 不支持的输入 `CslError` 有机器可读代码。 XML 检查执行结构/安全限制,而不是完整的 CSL 放松 NG schema 验证. 附属样式必须首先由主机解决到其独立的母机. 同步处理器有结构上的工作界限;主机需要硬墙时的最后期限,应当由自己的工人运行.

此模块不会改变持续引用节点,嵌入倒回快照,安装样式,或连接库 API. 这些是单独的一体化任务。 消费者必须保护 [第三方通知](https://npmcn.com/package/%40alggtta/editor/THIRD_PARTY_NOTICES.md) 并揭露 `CSL_COMPONENT_NOTICE` 在其引用的UI中归属。 样式/地点固定作者和出处仍保留在源固定装置中.

`refreshEditorCitations(editor, { style, locales, locale, items, noteIndices })` 决定 按文档顺序排列的每个已存在的 SSL 输出并替换其显示 文本在一个文档交易中。 授权供应,当前元数据为 `{ libraryId, itemId, metadata }` 作行相会. 刷新保留发生身份, 引用顺序,定位符,前缀,后缀和作者压制. 失踪 引用、 无效的元数据/ 样式或超大小显示文本中止整个 刷新点 需要实际脚注编号 `noteIndices` 对音符样式. 刷新有自己的倒数事件,与相邻的打字分开. 它回来了 用于主机审查的书目条目和映射损失;既未插入 书目节点或源元数据持续存在。 没有持续的计划改变或 引进了Atlas兄弟组合链接.

### 可选研究来源参考文献

导入 `createResearchNotesPlugin` 从 `@alggtta/editor/research-notes` 并加进 `extensionConfig.plugins` 装入前 `researchReference` 节点。 此可选条目存储注释或注释源身份与引用分开,并带有独立的引文快照,可见标签和可选的人类位置. 它不进行查找、导航、渲染源的URL, 或从后来的源编辑中自动刷新. `researchReferenceDocumentId` 项目只为主机的 wiki 流设置一个音符的已明确的文档身份;它从不从项目或注释中猜测一个文档.

插入/ 更新/ 删除命令保留更新时的发生身份, 并使用普通的撤销/ 重写 。 剪贴板粘贴创造出新的发生身份 。 严格节点- local v1 解析拒绝不支持的字段/ 版本; HTML 使标签成为已逃出文本 。 主机通过经核准的范围化API来解决库/源身份. 引文为副本,不是活的注释编辑. 可见标签提取与后端文档文本渲染器一致.

全局文档 schema v4 包含此可选词汇并保存被审查的 v3快照. v3到v4的迁移只更改了根版本的印章. 不支持,格式错误或重复的参考文档作为仅显示的预览打开,主机更新,自动保存和本地Storage写入被屏蔽;必须保留原JSON. 命令拒绝只读/已销毁的编辑器 。 协调后端 v4 合同和准确公布的 npm 消费者,然后才能实现持久性. 注解 API,阅读器,活的注解导航和Atlas的采用是单独的集成.

### 静态书目和快件产出

`renderCslQuickCopy` 可从现有选项中找到 `@alggtta/editor/citations` 输入。 线下供应 `style`编号 :`locales`,映射的 CPL `items`, 1 - 100 个明确选定的项目编号 `selection`,以及 `duplicates: 'first' | 'reject'`1\. 第一地点的重复报告 `duplicateIds`;重复源项目ID总是失败。 供应 `mode: 'bibliography'` 与 `bibliographyOrder: 'style' | 'selection'`,或 `mode: 'citation'`。选择顺序保存分组的 CSL 项,将一组放在第一个选定的成员上。 数字标签由所选的引用顺序来指定;选择样式顺序不会给这些标签重新编号.

结果包含配对平原 `text` 和限制 `html`,解决 `selectedIds`,可选书目条目身份 `static: true`。只有选中的项目输入独立的输出。 没有文献目录的样式失败, 而不是接受发明的格式 。 作为背景引用,通过 `context: { citations, citationId }` 包含完整命令文档,包括目标集群;其命令项ID必须等于被调试的选择。 全文本渲染保留了混淆,定位选项和实际的音符索引. 上下文会影响所选择的引用,但从未返回未选择的书目输出.

这是一个快照 API: 它不绑定或编辑文档,不使用剪贴板,写出文件,获取元数据/样式,也不执行主机导航. 主机在编辑后明确再生,选择剪贴板/下载行为,并按既定的渲染边界对HTML进行消毒. 它继承了离线核心的200个项目/文档-集群,XML和处理器-工作限制,并且没有硬墙时钟隔离;组装文本加HTML限制为2个MIB. RTF,链接的文献目录编辑,未被引用/被排除的文档覆盖,导出格式快拷贝仍然是单独的主机功能. 没有引入新的软件包条目或持续的节点计划.

### 离线引用样式管理

可选 `@alggtta/editor/citations` 进口 `CslStyleManager` 和不可改变的风格-图书馆帮助者。 开始 `emptyCslStyleLibrary()`,安装本地 `.csl` 样式 `installCslStyle`,并用 `installCslLocale`。 。 。 . `serializeCslStyleLibrary` 财务报告和审定财务报表 `readCslStyleLibrary` 在不更改原 XML 配置文件的情况下, 绕行边框配置文件 。 未知/ corrupt 配置文件必须保留并显示为只读;从不自动替换为空库.

`CslStyleManager` 由 `value` 财务报告和审定财务报表 `onChange(next, expectedRevision)`. 主机必须坚持进行原子修订比较,并保持其账户/存储范围的关键部分。 使用 `disabled` 当编辑权限被取消时. `onApply` 接收已解析的独立样式和离线本地化; 主机通过现有的文档修订/许可检查加以应用 `refreshEditorCitations`。安装的家长不能被删除,而依赖的样式会使用它们。 一个依赖样式的默认地语适用,除非用户明确选择另一个已安装地语. `en-US` 并且必须明确提供所要求的地方.

限制:50个样式,20个地块,每个XML文件有256000个字符,1个米B文件输入(Fatal UTF-8或BOM标记的UTF-16解码),8个米B序列化库. XML 安全/结构检查不是完整的 CSL 放松NG 兼容性. 这种组件搜索安装了样式并读取了本地文件;通过经过审查的准确npm版本进行在线获取、交叉设备存储和Atlas集成仍然是主机工作。 它不发布软件包,不获取样式/父母/本地URL,也不直接保存文档内容.

### 静态RTF引号扫描(CITE-07)

`@alggtta/editor/citations` 出口 `scanRtfCitations`, (中文(简体) ), `formatRtfCitations`下线 `RtfScanPanel`。提供最多200个授权的CSL项目和已安装的样式/本地快照。 扫描结果为流程所约束的不可变速快照;每次发生时在格式化前需要明确命令的项目ID. 候选人匹配支持 `{Author, YYYY}`, (中文(简体) ), `and`编号 :`&`, (中文(简体) ), `et al.`,以分号分隔的分组引用,可选 `p.`编号 :`pp.` 定位器,以及 `n.d.`. 含糊而无比的引用需要用户选择;事前事项从来不会默默地选择候选人.

输入为2 MiB RTF 1字节字符串,有Windows-1252升/hex出逃并签名Unicode出逃(包括代对);它不是一个UTF-8解码文件. 不支持的代码页, 二进制有效载荷, 已存在的字段/对象/脚注, 组和超大小文本被否决 。 头/脚,相片,隐藏的文字和可忽略的去向不进行扫描保存. 源字符范围被替换而未去掉介面格式组;其他输入字节保持不变. 真实的CSL引擎提供限制RTF格式和静态脚注,用于注释样式. `{Bibliography}` 选择书目位置;否则将附上。 输出范围为4 MiB.

`RtfScanPanel` 本地读取文件并下载新命名的 Blob;它不会上传,覆盖输入,发布,或创建活引用字段. 当账户/图书馆授权更改并设定时,主机必须通过新项目/样式快照 `disabled` 丧失许可。 在读取和取消已完成的输出 URL 之前,目标/许可更改无效 。 执行本地文件写入的主机必须分别执行不同的输入/输出路径 。 完整的RTF方言支持,活字/LibreOffice字段,以及实际的Word/LibreOffice渲染不为这些帮助者所声称.

### 可选文档 DOI 警告

`@alggtta/editor/citations` 出口 `createCitationWarningGate`, (中文(简体) ), `CitationWarningPanel` 财务报告和审定财务报表 `inspectExistingCitationWarnings`后端已授权的当前预测 `deea9b9fdbb641b4bfa22edf7ba044b7cb6ed5d0`,包含匹配的库/项目/源码修订和逻辑文档ID/绑定. 此模块从不获取提供者、 证书或文件 。 将每个文件绑入一个单独的门并更换其状态,只要文件会话、来源或通知绑定更改;未知/未来/结构化的预测区块明显可见。 不要重用跨越文档身份的大门 。 在撤销授权时,将状态替换为 `null` 无法关闭或取消批准,或卸载文件.

配置 `CitationExtension.configure({warningGate: gate, onWarning: decision => ...})` 或者说 `createCitationPlugin({warningGate: gate, onWarning})`. 已知的撤回/关切证据,包括 stale/offline 证据 `insertCitation` 财务报告和审定财务报表 `updateCitation`。主机 UI 明确调用 `gate.resolve(decision, 'proceed' | 'skip', 'each-time' | 'document')`;然后一个单独的用户动作可能会重试当前命令. UI 不自动重放命令 。 一发授权要求相同的不可移动文件对象和精确解析的提议; 干跑 `.can()` 既不需要批准,也不发布决定。 一个全文档的重复选择只在匹配的实际命令上生效,并绑定在同一被克隆的证据快照上. 取代状态会使所有决定无效.

在重新开放时,明确呼叫 `inspectExistingCitationWarnings(editor, gate)` 并显示其预定结果,即使对先前承认的警告也是如此。 没有通知是不完整的信息,从不健康的裁决. `CitationWarningPanel` 是一个可控的演示文稿组件;主机拥有确认状态和当前授权的文档/源生命周期。 普通 JSON/ HTML 导入,剪贴板粘贴, CSL 批次刷新和外部 Office/Docs 适配器不受插入/更新命令门的保护;主机必须检查并强制执行自己的录用界限. 已存在的引用 schema v1, 发生身份, HTML 和撤销行为不变 。 引文节点中没有任何警告数据或确认。 准确的npm出版/采用,Atlas主机安装和完全原创的CITE-05接受仍然分开.

### PDF 注释域提案(READ-02基础)

可选 `@alggtta/editor/citations` 进口 `parsePdfAnnotationRecord`, (中文(简体) ), `preparePdfAnnotationCreate`, (中文(简体) ), `preparePdfAnnotationUpdate`,以及 `pdfAnnotationToResearchReference`这些纯粹的帮助者接受自己的数据记录; 没有PDF、文件系统、网络、剪贴板或编辑器写入副作用. 本概况支持突出、突出和立场说明的建议,包括: 页从1到500,最多256个正正正正正向矩形。 坐标 使用左上方来源 **未旋转** 页面; 读者主机拥有变换. 文本保存为逐字记录(包括Unicode顺序),范围为10 000 UTF-16 每个引文/注释的单位;标记为50;颜色为六位数十六进制 数值。 输入拒绝不支持的未来配置文件、访问器、别名、稀有 数组和无效的Unicode,带有256KiB自有数据字符串/键预算.

```ts
import {
  preparePdfAnnotationCreate, preparePdfAnnotationUpdate,
  pdfAnnotationToResearchReference,
} from '@alggtta/editor/citations'

const source = {
  libraryId, attachmentId, attachmentRevision, attachmentSha256,
  itemId: null, itemRevision: null, // or both confirmed parent values
}
const proposal = preparePdfAnnotationCreate(annotationId, source, {
  type: 'highlight', page: 1,
  rects: [{ x: 0.1, y: 0.2, width: 0.5, height: 0.03 }],
  quoteText: 'Selected text', comment: '', color: '#ffff00', tags: [],
})
// Explicitly authorize and save proposal in the host; only use its confirmed record.
const update = preparePdfAnnotationUpdate(confirmedRecord, source, confirmedRecord.revision, {
  comment: 'Reviewed comment',
})
const node = pdfAnnotationToResearchReference(confirmedRecord, source, occurrenceId, 'Author · p. 1')
// Insert node via the existing research-notes plugin after the host's explicit action.
```

创建使用预期版本 0; 更新需要抓取的注释版本 并且不能改变源身份、父、附件修订或SHA256。 这些 是建议, **未保存的记录**,授权或持久分解. 主机必须验证真实的私有附件/ hash 和当前权限, 执行原子修正 CAS,并返回确认的记录。 旧源装订 失败, 而不是自动移动引用 .

复制返回已有的 `researchReference` 节点形状,保留单独的 引用快照和呼叫器提供的情况ID。 它没有添加文件计划. 几何、附件散列/修正和评论仍保留在主机的注释中 记录; 现有文档源存储注释 ID/Revision 和可选 父项目 ID。 主机导航必须解决并验证该源记录. 未经证实的记录必须保存在主机存储处以便修理,而不是 默地迁徙. 此源更改需要准确发布的 npm 版本 ; 兄弟姐妹的源链接不是释放边界. 读取器持续性、重开/编辑/许可测试、嵌入式PDF进出口、, EPUB 说明、图像/文本/链接说明、本地客户端和阅读模式 缓存/位置链接是分开进行的工作.

## 常见问题

### @alggtta/editor 是什么？

带有 Tiptap 3\.x 和 DaisyUI 5 的 Alggtta 编辑器

### 如何安装 @alggtta/editor？

在项目目录运行 npm install @alggtta/editor，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：yjs（^13\.6\.31）、react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）、@tiptap/pm（3\.31\.3）、y-protocols（^1\.0\.6）、@tiptap/core（3\.31\.3）、@tiptap/react（3\.31\.3）、@tiptap/extension-bubble-menu（3\.31\.3）、@tiptap/extension-floating-menu（3\.31\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alggtta/editor 支持 TypeScript 吗？

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

### @alggtta/editor 支持 ESM 还是 CommonJS？

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

### @alggtta/editor 需要什么版本的 Node\.js？

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

### @alggtta/editor 可以商用吗？

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

### @alggtta/editor 的下载量有多少？

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

### @alggtta/editor 还在维护吗？

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