# @diplodoc/latex-extension 中文文档

规范地址：https://npmcn.com/package/%40diplodoc/latex-extension/

版本：2\.0\.2
npm 元数据更新时间：2026-08-18T09:10:25.966Z
中文译文更新时间：2026-11-12T10:41:57.667Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40diplodoc/latex-extension
原文对照：https://npmcn.com/package/%40diplodoc/latex-extension/?lang=original
项目主页：https://github.com/diplodoc-platform/latex-extension#readme
源码仓库：https://github.com/diplodoc-platform/latex-extension

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

- 包体积（解压后）：4 MB，84 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：katex ^0\.16\.9，react ^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，markdown-it ^13\.0\.0
- 首次发布：2023-12-18T14:11:47.946Z
- 最新版本发布：2026-08-06T14:59:01.631Z
- 近 30 天下载量：22855（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 4 个）

## 中文简介

用于 Diplodoc 平台的扩展, 它使用 Katex 添加了 Latex 语法的支持

## 安装

```sh
npm install @diplodoc/latex-extension
```

也可以使用：`pnpm add @diplodoc/latex-extension`、`yarn add @diplodoc/latex-extension`、`bun add @diplodoc/latex-extension`

## README

**英语** | [русский](https://github.com/diplodoc-platform/latex-extension/blob/master/README.ru.md)

* * *

[![NPM version](https://img.shields.io/npm/v/@diplodoc/latex-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/latex-extension) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_latex-extension&metric=alert_status)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_latex-extension) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_latex-extension&metric=coverage)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_latex-extension) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_latex-extension&metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_latex-extension) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_latex-extension&metric=reliability_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_latex-extension) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_latex-extension&metric=security_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_latex-extension)

# Diplodoc Latex 扩展名

这是用于 Diplodoc 平台的扩展, 它使用 Latex 语法添加支持 [凯特克](https://katex.org/) 图书馆.

扩展部分包括:

-   [编写 Katex 运行时间](https://npmcn.com/package/%40diplodoc/latex-extension/#readme-prepared-katex-runtime)
-   [它变换插件](https://npmcn.com/package/%40diplodoc/latex-extension/#readme-markdownit-transform-plugin)
-   [用于智能控制 Katex 的反应钩和组件](https://npmcn.com/package/%40diplodoc/latex-extension/#readme-react-hook-and-component-for-smart-control-of-katex)

## 快速启动

安装软件包

```bash
npm install --save @diplodoc/latex-extension
```

在变压器上附加插件

```js
import latex from '@diplodoc/latex-extension';
import transform from '@diplodoc/transform';

const {result} = await transform(
  `
### Inline latex

Some text $c = \pm\sqrt{a^2 + b^2}$

### Block latex

$$
c = \pm\sqrt{a^2 + b^2}
$$
`,
  {
    plugins: [latex.transform()],
  },
);
```

将 latex 运行时间添加到您的最后一页

```html
<html>
  <head>
    <link rel="stylesheet" href="_assets/latex-extension.css" />
    <!-- Read more about '_assets/latex-extension.js' in 'MarkdownIt transform plugin' section -->
    <script src="_assets/latex-extension.js" async />
    <script>
      // Read more about 'latexJsonp' in 'Prepared Katex runtime' section
      window.latexJsonp = window.latexJsonp || [];
      window.latexJsonp.push((latex) => {
        window.addEventListener('load', function () {
          latex.run();
        });
      });
    </script>
  </head>
  <body style="background: #000">
    ${result.html}
  </body>
</html>
```

## 编写 Katex 运行时间

Katex - 是渲染tex/latex公式最受欢迎和最快的执行.

Katex的问题在于它的大小很大. 最预期的行为是同步装入.

**编写 Katex 运行时间** 旨在解决这个问题. 我们添加 `latexJsonp` 处理 Katex 装入的全局调用 .

此外,我们通过以下方法限制已曝光的Katex API:

-   **运行( 选项 ): [Katex 选项](https://katex.org/docs/options) 打开 [运行选项](https://npmcn.com/package/%40diplodoc/latex-extension/#readme-run-options)(中文(简体) )** - 启动公式渲染

用法示例:

```js
window.latexJsonp = window.latexJsonp || [];

// This callback will be called when runtime is loaded
window.latexJsonp.push((latex) => {
  latex.run();
});

// You can configure more that one callback
window.latexJsonp.push((latex) => {
  console.log('Render diagrams');
});
```

### 运行选项

-   `querySelector` - 查找要渲染的元素时使用的查询选择器.  
    (默认 : `.yfm-latex`(中文(简体) )  
    
-   `nodes` - 要制造的节点。 如果这是设定的, `querySelector` 将被忽略.  
    
-   `sanitize` - 从最后html中删除危险内容的功能.  
    (默认 : `identity`(中文(简体) )  
    

### 警卫

默认运行时间使用 Katex [安保建议](https://katex.org/docs/security)。 。 。 .  
但还有延长消毒时间的额外选择。 你可以随意使用自己的消毒器:

```js
import dompurify from 'dompurify';
import domready from 'domready';

window.latexJsonp = window.latexJsonp || [];
window.latexJsonp.push((latex) => {
  domready(() =>
    latex.run({
      sanitize: dompurify.sanitize,
    }),
  );
});
```

## 它变换插件

插件用于 [@ diplodoc/ 变形](https://github.com/diplodoc-platform/transform) 软件包.

配置 :

-   `runtime` - 显示结果的运行时脚本名称 `script` 财务报告和审定财务报表 `style` 节.  
    若为 `bundle` 选项已禁用,则可以是普通字符串。 否则应该是字符串记录.  
    **默认**数字 :
    
    ```json
    {
      "script": "_assets/latex-extension.js",
      "style": "_assets/latex-extension.css"
    }
    ```
    
-   `bundle` - 布尔旗以启用/无法复制捆绑的运行时间到目标目录.  
    目标目录所在 `<transformer output option>/<plugin runtime option>`  
    **为客户端使用而禁用**  
    **默认**: 真实  
    
-   `validate` - 布尔旗以启用/失效建筑验证.  
    用于服务器侧预建工具 [校对:soup](https://github.com/diplodoc-platform/cli) **为客户端使用而禁用**  
    **默认**: 真实  
    
-   `classes` - 将添加到Latex公式容器中的其他类别.  
    (例: `my-own-class and-other-class`(中文(简体) )  
    
-   `katexOptions` - 说吧 [凯特克](https://katex.org/docs/options) 渲染选项
    

## 用于智能控制 Katex 的反应钩和组件

用反应来简化 Katex 控制

```tsx
import React from 'react';
import {transform} from '@diplodoc/transform';
import latex from '@diplodoc/latex-extension/plugin';
import {LatexRuntime} from '@diplodoc/latex-extension/react';

const LATEX_RUNTIME = 'extension:latex';

const Doc: React.FC = ({content}) => {
  const result = transform(content, {
    plugins: [
      // Initialize plugin for client/server rendering
      latex.transform({
        // Do not touch file system
        bundle: false,
        // Set custom runtime name for searching in result scripts
        runtime: LATEX_RUNTIME,
      }),
    ],
  });

  // Load katex only if one or more formulas should be rendered
  if (result.script.includes(LATEX_RUNTIME)) {
    import('@diplodoc/latex-extension/runtime');
  }

  if (result.style.includes(LATEX_RUNTIME)) {
    import('@diplodoc/latex-extension/runtime/styles');
  }

  return <div dangerouslySetInnerHTML={{__html: result.html}} />;
};

export const App: React.FC = ({theme}) => {
  return (
    <>
      <Doc
        content={`
            $$
            c = \pm\sqrt{a^2 + b^2}
            $$
        `}
      />
      <KatexRuntime />
    </>
  );
};
```

## 常见问题

### @diplodoc/latex-extension 是什么？

用于 Diplodoc 平台的扩展, 它使用 Katex 添加了 Latex 语法的支持

### 如何安装 @diplodoc/latex-extension？

在项目目录运行 npm install @diplodoc/latex-extension，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：katex（^0\.16\.9）、markdown-it（^13\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @diplodoc/latex-extension 支持 TypeScript 吗？

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

### @diplodoc/latex-extension 支持 ESM 还是 CommonJS？

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

### @diplodoc/latex-extension 可以商用吗？

@diplodoc/latex-extension 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @diplodoc/latex-extension 的下载量有多少？

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

### @diplodoc/latex-extension 还在维护吗？

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