# @friendofsvelte/tipex 中文文档

规范地址：https://npmcn.com/package/%40friendofsvelte/tipex/

版本：0\.3\.1
npm 元数据更新时间：2026-09-23T04:03:57.274Z
中文译文更新时间：2026-11-15T14:14:52.369Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40friendofsvelte/tipex
原文对照：https://npmcn.com/package/%40friendofsvelte/tipex/?lang=original
项目主页：https://tipex.pages.dev/
源码仓库：https://github.com/friendofsvelte/tipex

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

- 包体积（解压后）：111 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：svelte ^5\.0\.0，@tiptap/pm ^3\.31\.0，@tiptap/core ^3\.31\.0，@tiptap/extensions ^3\.31\.0，@tiptap/starter-kit ^3\.31\.0，@tiptap/extension-list ^3\.31\.0，@tiptap/extension-image ^3\.31\.0，@tiptap/extension-code-block ^3\.31\.0，@tiptap/extension-floating-menu ^3\.31\.0，@tiptap/extension-code-block-lowlight ^3\.31\.0
- 首次发布：2023-09-01T09:30:29.453Z
- 最新版本发布：2026-09-23T04:03:57.035Z
- 近 30 天下载量：31039（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 5 个）

## 中文简介

Tipex是专门为斯维尔特设计的高级丰富的文本编辑器,经过精心设计,采用了强有力的框架 [提示](https://tiptap.dev/) 财务报告和审定财务报表 [亲子](https://prosemirror.net/)它使开发者能够不懈地制作丰富的文本编辑器,

## 安装

```sh
npm install @friendofsvelte/tipex
```

也可以使用：`pnpm add @friendofsvelte/tipex`、`yarn add @friendofsvelte/tipex`、`bun add @friendofsvelte/tipex`

## README

# 提示

Tipex是专门为斯维尔特设计的高级丰富文本编辑器, 精心设计与强健的 框架 [提示](https://tiptap.dev/) 财务报告和审定财务报表 [亲子](https://prosemirror.net/)它赋予开发者权力 毫不费力地编织出丰富的文本编辑器,使他们摆脱基础技术、风格管理的复杂性, 和相关的复杂情况.

> Svelte 5 和 runes 模式启动

## 关键特性

-   🚀 **Svelte 5 准备**: 以斯维尔特5的最新特征所建,包括runes,片段和现代反应
-   🎨 **智能控制系统**: 自动检测是否根据 `controlComponent` 道具
-   🔌 **可扩展的建筑**: 通过 Tiptap 的扩展系统完全可扩展, 包含默认扩展
-   📱 **移动响应**: 优化桌面和移动两种易触交互
-   🎯 **上下文软件浮动菜单**: 文本选择中出现的智能浮动工具栏
-   🔗 **高级链接管理**: 内置链接编辑与剪贴板集成和视觉反馈
-   ✅ **任务列表**: 交互式复选框和任务管理的原生支持
-   🎭 **现代主题**: 使用 OKLCH 颜色和 CSS 自定义属性使用 Tailwind CSS v4 构建
-   ⚡ **业绩优化**:收发机Svelte的回放和高效的DOM更新
-   💼 **完整类型脚本支持**: 具有综合类型定义的完整类型安全性
-   🎨 **重点管理**: 有视觉反馈和无障碍支持的智能焦点检测

## 安装

安装软件包从 [国家预防机制](https://www.npmjs.com/package/@friendofsvelte/tipex)数字 :

```bash
npm install "@friendofsvelte/tipex"
```

Tiptap v3 是一个对等依赖. npm 7+和 pnpm 自动安装; 否则同时安装 :

```bash
npm install @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extensions @tiptap/extension-list @tiptap/extension-image @tiptap/extension-code-block @tiptap/extension-code-block-lowlight @tiptap/extension-floating-menu
```

检查出来 [Tipex 编辑器变量](https://github.com/Bishwas-py/tipex-editor-variants) 联 合 国 [现场预览](https://tipex-editor-variants.pages.dev/) 用于实例显示您可以用 Tipex Svelte 文本编辑器构建的内容,包括多个主题和配置.

## 基本用途

导入组件和样式, 然后在您的 Svelte 组件中使用 :

```svelte
<script lang="ts">
    import { Tipex } from '@friendofsvelte/tipex';
    import '@friendofsvelte/tipex/styles/index.css';

    let body = `<h1>My Project Notes</h1>
    <p>I've been working on this <strong>new feature</strong> for the past few days. 
    It's been quite <em>challenging</em> but I think I'm making good progress.</p>
    
    <h2>Things I need to do</h2>
    <ul data-type="taskList">
        <li data-type="taskItem" data-checked="true">Set up the development environment</li>
        <li data-type="taskItem" data-checked="false">Write the core functionality</li>
        <li data-type="taskItem" data-checked="false">Add error handling</li>
    </ul>
    
    <p>Check out the <a href="https://tiptap.dev/">TipTap documentation</a> for more features!</p>`;
</script>

<Tipex
    {body}
    floating
    focal
    style="margin-top: 1rem; margin-bottom: 0;"
    class="h-[70vh] border border-neutral-200/80"
/>
```

## 核心概念

### 控制系统

Tipex 具有简单而灵活的控制系统:

1.  **默认控件** (否时自动) `controlComponent` 提供:
    
    -   带有必要编辑工具的预建格式工具栏
    -   内建的公用按钮(复制、链接管理)
    -   适合快速执行
2.  **自定义控制** (当 `controlComponent` 提供片段:
    
    -   完全控制编辑器接口
    -   完全定制自由
    -   可以扩展默认控制或创建全新的接口
    -   专门使用案件的理想
3.  **无控件** (当 `controlComponent={null}` 明确设置如下:
    
    -   完全隐藏所有控制元素
    -   提供干净、最小的编辑器接口
    -   适合只读或嵌入式方案

这种简单的做法在保持使用方便的同时提供了最大的灵活性.

### 扩展系统

Tipex为增强功能而利用了Tiptap的扩展系统. 这个 `extensions` prop完全取代了默认的扩展(包括StarterKit). 扩展默认值, 展开 `defaultExtensions` 并添加自己的:

```svelte
<script lang="ts">
    import { Tipex, defaultExtensions } from '@friendofsvelte/tipex';
    import { TextAlign } from '@tiptap/extension-text-align';
    import { Highlight } from '@tiptap/extension-highlight';

    // Extend default extensions
    const customExtensions = [
        ...defaultExtensions,
        TextAlign.configure({
            types: ['heading', 'paragraph'],
            alignments: ['left', 'center', 'right', 'justify']
        }),
        Highlight.configure({
            multicolor: true
        })
    ];

    let body = '';
</script>

<Tipex {body} extensions={customExtensions} />
```

如果你通过了完全的习惯 `extensions` 数组,没有保存任何默认值 —— 提供编辑器所需的一切(文档、段落和文本节点,例如通过您自己的节点) `StarterKit`) (中文(简体) ).

### 浮动菜单

浮动菜单提供了文本选择时出现的对上下文有敏感认识的格式选项:

```svelte
<Tipex floating /> <!-- Enables the floating menu -->
```

### 重点管理

Tipex 包含有视觉反馈的智能焦点检测:

```svelte
<Tipex focal />
<!-- Default: shows focus ring -->
<Tipex !focal />
<!-- Disables focus ring -->
```

## 带有 Tailwind CSS v4 的现代主题

Tipex 以 **尾风 CSS v4** 并使用现代的 OKLCH 颜色来提高颜色的准确性和一致性。 主题系统使用 CSS 自定义属性, 您可以覆盖 :

```css
@import '@friendofsvelte/tipex/styles/index.css';

@theme {
    /* Override Tipex colors */
    --color-tipex-primary-500: oklch(0.65 0.11 285); /* Custom purple */
    --color-tipex-success-500: oklch(0.647 0.208 142.425); /* Custom green */

    /* Custom spacing */
    --spacing-tipex-md: 1.25rem;
    --spacing-tipex-lg: 2rem;
}
```

### 可用的 CSS 自定义属性

-   **颜色**数字 : `--color-tipex-{50-950}`, (中文(简体) ), `--color-tipex-primary-{50-950}`, (中文(简体) ), `--color-tipex-success-{50-950}`
-   **间距**数字 : `--spacing-tipex-{xs,sm,md,lg,xl,2xl}`
-   **大小**数字 : `--size-tipex-{1-12}`
-   **类型**数字 : `--text-tipex-{xs,sm,base,lg,xl,2xl}`
-   **边框半径**数字 : `--radius-tipex-{sm,md}`
-   **Z 指数**数字 : `--z-tipex-{floating,controls}`

## 高级使用

### 自定义头和脚节

使用 Svelte 5 片断在编辑器上或下方添加自定义组件 :

```svelte
<script lang="ts">
    import { Tipex } from '@friendofsvelte/tipex';

    let body = '';
</script>

<Tipex {body}>
    {#snippet head(editor)}
        <CustomHeader {editor} />
    {/snippet}

    {#snippet foot(editor)}
        <CustomFooter {editor} />
    {/snippet}
</Tipex>
```

### 扩展默认控件

在保留默认工具栏的同时添加自定义工具栏 :

```svelte
<script lang="ts">
    import { Tipex, Controls } from '@friendofsvelte/tipex';

    let body = '';
</script>

<Tipex {body}>
    {#snippet controlComponent(tipex)}
        <Controls {tipex}>
            <!-- Built-in utilities: copy HTML and link editing with clipboard integration -->
            <!-- Add custom utilities here -->
            <button class="tipex-edit-button tipex-button-rigid" aria-label="Export PDF">
                📄 Export
            </button>
        </Controls>
    {/snippet}
</Tipex>
```

### 自定义控制组件

创建一个完全自定义的控制界面 :

```svelte
<script lang="ts">
    import { Tipex } from '@friendofsvelte/tipex';

    let body = '';
</script>

<Tipex {body}>
    {#snippet controlComponent(tipex)}
        <div class="my-custom-controls">
            <button onclick={() => tipex.commands.toggleBold()}>
                <strong>B</strong>
            </button>
            <button onclick={() => tipex.commands.toggleItalic()}>
                <em>I</em>
            </button>
            <button onclick={() => tipex.commands.toggleTaskList()}> ✅ Tasks </button>
        </div>
    {/snippet}
</Tipex>
```

### 无控件( 最小编辑器)

隐藏干净、最小编辑界面的所有控件 :

```svelte
<script lang="ts">
    import { Tipex } from '@friendofsvelte/tipex';

    let body = '';
</script>

<!-- Editor with no controls - perfect for embedded or read-only scenarios -->
<Tipex {body} controlComponent={null} />
```

### 输入密钥行为( 单行对双行间距)

按键 `Enter` 启动一新段落( e)`<p>`),同时 `Shift+Enter` 插入硬换行符(`<br>`)在本段中。 这是标准ProseMirror/Tiptap行为,与大多数丰富的文本编辑器如何工作相匹配.

新建段落可以看起来"双空",因为Tipex的默认样式给每个段落一个下边边:规则 `.tipex-editor-section .ProseMirror p` 应用 `margin-bottom: var(--spacing-tipex-md)` (默认为1rem). 根据你的愿望,有两种方法可以改变这一点:

**备选案文A:保留段落,去除视觉空白(CSS)**

覆盖您样式表中的段落边距 :

```css
@import '@friendofsvelte/tipex/styles/index.css';

.tipex-editor .ProseMirror p {
    margin-bottom: 0;
}
```

此保存默认值 `Enter` = 新的段落语义(结构化内容更好),只去除段落之间的间隔.

**备选案文B:制造 `Enter` 插入硬折叠段,而不是新段落**

添加一个重映射的小扩展名 `Enter` 至硬断:

```svelte
<script lang="ts">
    import { Tipex, defaultExtensions } from '@friendofsvelte/tipex';
    import { Extension } from '@tiptap/core';

    const HardBreakOnEnter = Extension.create({
        name: 'hardBreakOnEnter',
        addKeyboardShortcuts() {
            return {
                Enter: () => this.editor.commands.setHardBreak()
            };
        }
    });

    let body = '';
</script>

<Tipex {body} extensions={[...defaultExtensions, HardBreakOnEnter]} />
```

使用此扩展名, 输入 `a`按钮 `Enter`输入 `b` 生产 `<p>a<br>b</p>` 而不是两段。 请注意,这改变了文档结构:所有内容都保留在一个段落中,因此,如果您仍然想要语义段落,则选择备选案文A.

## 软件配置( P)

根据实际数 `TipexProps` 界面,这里是所有可用的属性 :

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `body` | `string` | `''` | 编辑器的初始 HTML 内容 |
| `tipex` | `TipexEditor` (可编码) | `undefined` | 编辑器实例 - 绑定访问编辑器方法 |
| `extensions` | `AnyExtension[]` (可编码) | `defaultExtensions` | 要使用的 Tiptap 扩展组 |
| `floating` | `boolean` | `false` | 在文本选择中启用浮动菜单 |
| `focal` | `boolean` | `true` | 启用焦点环样式 |
| `focused` | `boolean` (可编码) | `false` | 当前编辑器是否焦点 |
| `autofocus` | `boolean` | `true` | 在挂载上自动聚焦编辑器 |
| `class` | `string` | `''` | 编辑器容器的额外CSS课程 |
| `style` | `string` | `''` | 编辑器容器的内嵌样式 |
| `ctxId` | `string` | `'_tipex'` | 编辑器实例的背景标识 |
| `head` | `Snippet<[TipexEditor]>` | `undefined` | 编辑器上的内容 |
| `foot` | `Snippet<[TipexEditor]>` | `undefined` | 编辑器下面的内容 |
| `controlComponent` | `Snippet<[TipexEditor]> | null` | `undefined` | 自定义控制组件(取代默认控制). 设定为 `null` 隐藏所有控件. |
| `oncreate` | `(props: EditorEvents['create']) => void` | `() => {}` | 创建编辑器时召回 |
| `ondestroy` | `(props: EditorEvents['destroy']) => void` | `() => {}` | 编辑器被销毁时召回 |
| `onupdate` | `(props: EditorEvents['update']) => void` | `() => {}` | 编辑内容更新时召回 |

### 布尔道具与内存

您可以使用 `!` 前缀 :

```svelte
<Tipex !focal !floating /> <!-- Disables focus ring and floating menu -->
```

## 获取编辑器内容

使用 Svelte 5 操作访问编辑器实例及其内容 :

```svelte
<script lang="ts">
    import { Tipex } from '@friendofsvelte/tipex';
    import type { Editor } from '@tiptap/core';

    let body = '';
    let editor: Editor | undefined = $state();

    // Reactive HTML content
    const htmlContent = $derived(editor?.getHTML() ?? '');

    // Reactive text content (no HTML tags)
    const textContent = $derived(editor?.getText() ?? '');

    // Reactive word count
    const wordCount = $derived(
        editor
            ?.getText()
            .split(/\s+/)
            .filter((word) => word.length > 0).length ?? 0
    );
</script>

<Tipex {body} bind:tipex={editor} />

<div class="editor-stats">
    <p>Words: {wordCount}</p>
    <p>Characters: {textContent.length}</p>
</div>

<details>
    <summary>HTML Output</summary>
    <pre>{htmlContent}</pre>
</details>
```

## 文档

全面文件,访问 [tipex.pages.dev (英语)](https://tipex.pages.dev/)。 。 。 .

## 关于斯维尔特的朋友

![Friend Of Svelte Logo](https://avatars.githubusercontent.com/u/143795012?s=200&v=4)

[斯维尔特的朋友](https://github.com/friendofsvelte) 是一个社区驱动的项目,帮助斯维尔特开发者找到和 开发惊人的斯维尔特资源。 我们的任务是为残疾人创造高质量、可维持和可获取的工具 斯维尔特生态系统.

### 加入社区

-   {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我们建立我们的仓库
-   \* 向项目捐款
-   分享你的想法
-   \* 人人开放会员资格

如果你喜欢这个项目,你可以通过为这个项目捐款而成为朋友之一. 成员开放 每个人.

## 许可证

MIT许可. 版权 (c) 2023-2024 Friend of Svelte.

## 常见问题

### @friendofsvelte/tipex 是什么？

Tipex是专门为斯维尔特设计的高级丰富的文本编辑器,经过精心设计,采用了强有力的框架 提示 财务报告和审定财务报表 亲子它使开发者能够不懈地制作丰富的文本编辑器,

### 如何安装 @friendofsvelte/tipex？

在项目目录运行 npm install @friendofsvelte/tipex，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.0\.0）、@tiptap/pm（^3\.31\.0）、@tiptap/core（^3\.31\.0）、@tiptap/extensions（^3\.31\.0）、@tiptap/starter-kit（^3\.31\.0）、@tiptap/extension-list（^3\.31\.0）、@tiptap/extension-image（^3\.31\.0）、@tiptap/extension-code-block（^3\.31\.0）、@tiptap/extension-floating-menu（^3\.31\.0）、@tiptap/extension-code-block-lowlight（^3\.31\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @friendofsvelte/tipex 支持 TypeScript 吗？

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

### @friendofsvelte/tipex 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @friendofsvelte/tipex 可以商用吗？

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

### @friendofsvelte/tipex 的下载量有多少？

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

### @friendofsvelte/tipex 还在维护吗？

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