# Comentarios

- Human documentation: [https://docs.univer.ai/es-ES/guides/sheets/features/comments](https://docs.univer.ai/es-ES/guides/sheets/features/comments)

- Agent Markdown: [https://docs.univer.ai/es-ES/guides/sheets/features/comments.md](https://docs.univer.ai/es-ES/guides/sheets/features/comments.md)

- Requested language: `es-ES`

- Content language: `es-ES`

- Documentation version: `1.2.0`

- Source: [sheets/features/comments.es-ES.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/comments.es-ES.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-thread-comment",
      "locale": "@univerjs/preset-sheets-thread-comment/locales/en-US",
      "style": "@univerjs/preset-sheets-thread-comment/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/thread-comment"
    },
    {
      "client": "@univerjs/thread-comment-ui",
      "locale": "@univerjs/thread-comment-ui/locale/en-US",
      "style": "@univerjs/thread-comment-ui/lib/index.css"
    },
    {
      "client": "@univerjs/sheets-thread-comment",
      "facade": "@univerjs/sheets-thread-comment/facade"
    },
    {
      "client": "@univerjs/sheets-thread-comment-ui",
      "locale": "@univerjs/sheets-thread-comment-ui/locale/en-US",
      "style": "@univerjs/sheets-thread-comment-ui/lib/index.css"
    }
  ],
  "server": "optional"
}
```

Los comentarios permiten a los usuarios agregar comentarios y respuestas dentro de los documentos, facilitando la comunicación y la colaboración entre los miembros del equipo.

## Modo predeterminado

### Instalación

#### npm

```bash
npm install @univerjs/preset-sheets-thread-comment
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-thread-comment
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-thread-comment
```

#### bun

```bash
bun add @univerjs/preset-sheets-thread-comment
```

### Uso

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsThreadCommentPreset } from '@univerjs/preset-sheets-thread-comment' // [!code ++]
import UniverPresetSheetsThreadCommentEnUS from '@univerjs/preset-sheets-thread-comment/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-thread-comment/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsThreadCommentEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsThreadCommentPreset(), // [!code ++]
  ],
})
```

## Modo de complemento

### Instalación

#### npm

```bash
npm install @univerjs/thread-comment @univerjs/thread-comment-ui @univerjs/sheets-thread-comment @univerjs/sheets-thread-comment-ui
```

#### pnpm

```bash
pnpm add @univerjs/thread-comment @univerjs/thread-comment-ui @univerjs/sheets-thread-comment @univerjs/sheets-thread-comment-ui
```

#### yarn

```bash
yarn add @univerjs/thread-comment @univerjs/thread-comment-ui @univerjs/sheets-thread-comment @univerjs/sheets-thread-comment-ui
```

#### bun

```bash
bun add @univerjs/thread-comment @univerjs/thread-comment-ui @univerjs/sheets-thread-comment @univerjs/sheets-thread-comment-ui
```

### Uso

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsThreadCommentPlugin } from '@univerjs/sheets-thread-comment' // [!code ++]
import { UniverSheetsThreadCommentUIPlugin } from '@univerjs/sheets-thread-comment-ui' // [!code ++]
import SheetsThreadCommentUIEnUS from '@univerjs/sheets-thread-comment-ui/locale/en-US' // [!code ++]
import { UniverThreadCommentPlugin } from '@univerjs/thread-comment' // [!code ++]
import { UniverThreadCommentUIPlugin } from '@univerjs/thread-comment-ui' // [!code ++]
import ThreadCommentUIEnUS from '@univerjs/thread-comment-ui/locale/en-US' // [!code ++]

import '@univerjs/sheets-thread-comment-ui/lib/index.css'
import '@univerjs/thread-comment-ui/lib/index.css' // [!code ++]

import '@univerjs/sheets-thread-comment/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      ThreadCommentUIEnUS, // [!code ++]
      SheetsThreadCommentUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverThreadCommentPlugin) // [!code ++]
univer.registerPlugin(UniverThreadCommentUIPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsThreadCommentPlugin) // [!code ++]
univer.registerPlugin(UniverSheetsThreadCommentUIPlugin) // [!code ++]
```

#### Uso con la función de colaboración

Si está utilizando la función [Colaboración](https://docs.univer.ai/es-ES/guides/sheets/features/collaboration.md), configúrela de la siguiente manera:

#### npm

```bash
npm install @univerjs-pro/thread-comment-datasource
```

#### pnpm

```bash
pnpm add @univerjs-pro/thread-comment-datasource
```

#### yarn

```bash
yarn add @univerjs-pro/thread-comment-datasource
```

#### bun

```bash
bun add @univerjs-pro/thread-comment-datasource
```

```typescript
import { UniverThreadCommentDataSourcePlugin } from '@univerjs-pro/thread-comment-datasource' // [!code ++]

univer.registerPlugin(UniverThreadCommentDataSourcePlugin) // [!code ++]
```

## Compatibilidad móvil

Configure primero el [editor móvil](https://docs.univer.ai/es-ES/guides/sheets/getting-started/installation.md#mobile-support). En la inicialización en modo plugin de esta página, sustituya los registros de escritorio siguientes por las exportaciones móviles de los mismos paquetes **antes de abrir un documento**. Conserve modelos, estilos, traducciones e importaciones Facade; no registre ambas variantes.

| Paquete                              | Registro de escritorio              | Registro móvil                            |
| ------------------------------------ | ----------------------------------- | ----------------------------------------- |
| `@univerjs/sheets-thread-comment-ui` | `UniverSheetsThreadCommentUIPlugin` | `UniverSheetsThreadCommentMobileUIPlugin` |
| `@univerjs/thread-comment-ui`        | `UniverThreadCommentUIPlugin`       | `UniverThreadCommentMobileUIPlugin`       |

## API de Facade

Las definiciones completas del tipo de API de Facade se pueden encontrar en [FacadeAPI](https://docs.univer.ai/es-ES/reference/facade/thread-comment.md).

### Importar

> [!INFO: Plugin mode note]
> Solo el modo de complemento requiere importar manualmente el Paquete de fachada. El modo Preestablecido ya incluye el paquete Fachada correspondiente, por lo que no se necesita ninguna importación adicional.

```typescript
import '@univerjs/sheets-thread-comment/facade'
```

### Crear comentario de celda

Puedes crear un nuevo generador de comentarios usando `univerAPI.newTheadComment()`, que devuelve una instancia de `FTheadCommentBuilder`. Puede encadenar métodos para establecer varias propiedades del comentario.

Los siguientes son algunos métodos miembros de [`FTheadCommentBuilder`](https://docs.univer.ai/es-ES/reference/facade/thead-comment-builder.md):

| Método      | Descripción                                    |
| ----------- | ---------------------------------------------- |
| setContent  | Establecer el contenido del comentario         |
| setPersonId | Establecer el ID de persona para el comentario |
| setDateTime | Establecer la fecha y hora del comentario      |
| setId       | Establecer el ID del comentario                |
| setThreadId | Establecer el ID del hilo del comentario       |

```typescript
// Create a new comment
const richText = univerAPI.newRichText().insertText('hello univer')
const commentBuilder = univerAPI.newTheadComment()
  .setContent(richText)

console.log(commentBuilder.content.toPlainText())

// Add the comment to cell A1
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const cell = fWorksheet.getRange('A1')
const result = await cell.addCommentAsync(commentBuilder)
```

### Obtener comentarios de celda

Puede recuperar comentarios utilizando los siguientes métodos, que devuelven una instancia de `FThreadComment`. Luego puede realizar operaciones como actualizar, eliminar o resolver el comentario.

* `FWorkbook.getComments()`: obtener todos los comentarios en el libro de trabajo
* `FfWorksheet.getComments()`: obtener todos los comentarios en la hoja de trabajo
* `FRange.getComment()`: obtener el comentario de la celda superior izquierda en el rango
* `FRange.getComments()`: Obtener todos los comentarios en el rango

Los siguientes son algunos métodos de miembros de [`FThreadComment`](https://docs.univer.ai/es-ES/reference/facade/thread-comment.md):

| Método         | Descripción                                              |
| -------------- | -------------------------------------------------------- |
| getIsRoot      | Si el comentario es un comentario raíz                   |
| getCommentData | Obtener el comentario datos                              |
| getReplies     | Obtener la lista de respuestas al comentario             |
| getRange       | Obtener el rango del comentario                          |
| getRichText    | Obtener el contenido de texto enriquecido del comentario |
| deleteAsync    | Eliminar el comentario y sus respuestas                  |
| updateAsync    | Actualizar el contenido del comentario                   |
| resolveAsync   | Resolver el comentario                                   |
| replyAsync     | Responder al comentario                                  |

```typescript
// Get all comments in the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.getComments()

// Get all comments in the active worksheet
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet.getComments()

const fRange = fWorksheet.getRange('A1:B2')
// Get the comment of cell A1
fRange.getComment()

// Get all comments in the range A1:B2
fRange.getComments()
```

### Borrar comentarios de celda

* `FWorkbook.clearComments()`: borrar todos los comentarios en el libro
* `FWorksheet.clearComments()`: borrar todos los comentarios en el hoja de trabajo
* `FRange.clearCommentAsync()`: borrar el comentario de la celda superior izquierda en el rango
* `FRange.clearCommentsAsync()`: borrar todos los comentarios en el rango

```typescript
// Clear all comments in the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
await fWorkbook.clearComments()

// Clear all comments in the active worksheet
const fWorksheet = fWorkbook.getActiveSheet()
await fWorksheet.clearComments()

const fRange = fWorksheet.getRange('A1:B2')

// Clear the comment of cell A1
await fRange.clearCommentAsync()

// Clear all comments in the range A1:B2
await fRange.clearCommentsAsync()
```

### Obtener lista de respuestas a comentarios

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Get all comments in the worksheet
const comments = fWorksheet.getComments()
comments.forEach((comment) => {
  // If the comment is a root comment, get its replies
  if (comment.getIsRoot()) {
    const replies = comment.getReplies()
    replies.forEach((reply) => {
      console.log(reply.getCommentData())
    })
  }
})
```

### Actualizar/eliminar/resolver/responder a comentarios

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Create a new comment and add it to cell A1
const richText = univerAPI.newRichText().insertText('hello univer')
const commentBuilder = univerAPI.newTheadComment()
  .setContent(richText)
  .setId('mock-comment-id')
const cell = fWorksheet.getRange('A1')
await cell.addCommentAsync(commentBuilder)

// Update the comment and reply after 3 seconds
setTimeout(async () => {
  // Get the comment by ID and update its content
  const comment = fWorksheet.getCommentById('mock-comment-id')
  const newRichText = univerAPI.newRichText().insertText('Hello Univer AI')
  await comment.updateAsync(newRichText)

  // Create a new reply comment and set its content
  const replyText = univerAPI.newRichText().insertText('Hello Univer AI! GO! GO! GO!')
  const reply = univerAPI.newTheadComment().setContent(replyText)
  await comment.replyAsync(reply)
}, 3000)

// Resolve the comment and delete it after 6 seconds
setTimeout(async () => {
  const comment = fWorksheet.getCommentById('mock-comment-id')
  await comment.resolveAsync()
  await comment.deleteAsync()
}, 6000)
```

### Escuchas de eventos

Las definiciones completas de tipos de eventos se pueden encontrar en [Eventos](https://docs.univer.ai/es-ES/reference/facade/events.md).

El módulo de comentarios proporciona una serie de eventos para escuchar adiciones, actualizaciones, eliminaciones y cambios de estado de resolución de comentarios. Todos los eventos se pueden escuchar usando `univerAPI.addEvent()`.

#### Eventos de adición de comentarios

`univerAPI.Event.CommentAdded`: Se activa después de agregar un comentario

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommentAdded, (params) => {
  const { comment, workbook, worksheet, row, col } = params
})

// Remove the event listener, use `disposable.dispose()`
```

`univerAPI.Event.BeforeCommentAdd`: Se activa antes de agregar un comentario

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentAdd, (params) => {
  const { comment, workbook, worksheet, row, col } = params

  // Cancel the comment addition operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`
```

#### Eventos de actualización de comentarios

`univerAPI.Event.CommentUpdated`: Se activa después de que se actualiza un comentario

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommentUpdated, (params) => {
  const { comment, workbook, worksheet, row, col } = params
})

// Remove the event listener, use `disposable.dispose()`
```

`univerAPI.Event.BeforeCommentUpdate`: Se activa antes de que se agregue un comentario actualizado

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentUpdate, (params) => {
  const { comment, workbook, worksheet, row, col, newContent } = params

  // Cancel the comment update operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`
```

#### Eventos de eliminación de comentarios

`univerAPI.Event.CommentDeleted`: se activa después de que se elimina un comentario

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommentDeleted, (params) => {
  const { commentId, workbook, worksheet } = params
})

// Remove the event listener, use `disposable.dispose()`
```

`univerAPI.Event.BeforeCommentDelete`: se activa antes de que se elimine un comentario

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentDelete, (params) => {
  const { comment, workbook, worksheet, row, col } = params

  // Cancel the comment deletion operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`
```

#### Eventos de estado de resolución de comentarios

`univerAPI.Event.CommentResolved`: se activa después del estado de resolución de un comentario cambios

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommentResolved, (params) => {
  const { comment, row, col, resolved, workbook, worksheet } = params
})

// Remove the event listener, use `disposable.dispose()`
```

`univerAPI.Event.BeforeCommentResolve`: desencadenado antes de que cambie el estado de resolución de un comentario

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommentResolve, (params) => {
  const { comment, row, col, resolved, workbook, worksheet } = params

  // Cancel the comment resolution operation
  params.cancel = true
})

// Remove the event listener, use `disposable.dispose()`
```

Todos los eventos contienen los siguientes parámetros comunes:

* `workbook`: instancia del libro de trabajo actual
* `worksheet`: instancia de la hoja de trabajo actual
* `row`: índice de fila del comentario
* `col`: Índice de columna del comentario
* `comment`: Objeto de comentario (solo `commentId` se incluye en los eventos de eliminación)

Parámetros especiales:

* El evento `BeforeCommentUpdate` incluye `newContent`: Nuevo contenido del comentario (Tipo RichTextValue)
* Los eventos `CommentResolved` y `BeforeCommentResolve` incluyen `resolved`: estado de resolución del comentario

Todas las funciones de devolución de llamada de eventos con prefijo `Before` pueden devolver `params.cancel = true` para evitar el correspondiente operación.

## Operaciones comunes

Importa la Facade común y la del producto. Los métodos del producto crean anclas estables; la API común gestiona respuestas, cambios, resolución y eliminación. `getComments()` lee el estado local. `listCommentsAsync()` sincroniza los hilos ya conocidos mediante la fuente configurada; no descubre todos los hilos del servidor.

```ts
import '@univerjs/thread-comment/facade'

const [thread] = univerAPI.getComments({ resolved: false })
if (thread) {
  await univerAPI.replyCommentAsync({
    unitId: thread.unitId,
    subUnitId: thread.subUnitId,
    threadId: thread.threadId,
    content: 'Reviewed.',
  })
}
```

## Conversaciones compartidas

Integra Comment Service y Endpoint con [Server SDK](https://docs.univer.ai/es-ES/server/collaboration/extensions.md) y registra `UniverThreadCommentDataSourcePlugin` de `@univerjs-pro/thread-comment-datasource` tras configurar la colaboración y la licencia. La fuente incluida usa `/universer-api/comment/unit/{unitId}/...` y `/universer-api/user/list`: expón esas rutas en la aplicación. El servidor debe autorizar la lectura y escritura de comentarios de forma independiente de la edición del documento.