# API générale

- Human documentation: [https://docs.univer.ai/fr-FR/guides/docs/features/core/general-api](https://docs.univer.ai/fr-FR/guides/docs/features/core/general-api)

- Agent Markdown: [https://docs.univer.ai/fr-FR/guides/docs/features/core/general-api.md](https://docs.univer.ai/fr-FR/guides/docs/features/core/general-api.md)

- Requested language: `fr-FR`

- Content language: `fr-FR`

- Documentation version: `1.2.0`

- Source: [docs/features/core/general-api.fr-FR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/core/general-api.fr-FR.mdx)

---

L’API Facade disponible dans Univer dépend du type d’unité actif et des plugins enregistrés. Cette page présente les API communes à une application Univer Docs.

## Importation

```typescript
import { FUniver } from '@univerjs/core/facade'

const univerAPI = FUniver.newAPI(univer)
```

## Commandes

La plupart des opérations Univer sont enregistrées dans le système de commandes. Ce chemin d’exécution unifié permet notamment l’annulation, le rétablissement et la collaboration.

> [!NOTE]
> Pour plus de détails sur la conception, consultez le [système de commandes Univer](/blog/univer#command-system).

### Écoute des commandes

Utilisez `Event.BeforeCommandExecute` pour exécuter une logique avant une commande et `Event.CommandExecuted` pour l’exécuter une fois la commande terminée.

```typescript
const beforeDisposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, ({ id, params }) => {
  console.log('Avant la commande :', id, params)
})

const afterDisposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, params }) => {
  console.log('Commande exécutée :', id, params)
})
```

Pour empêcher l’exécution d’une commande, définissez `event.cancel` sur `true` dans un écouteur `BeforeCommandExecute`.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {
  if (event.id === 'doc.command.set-name') {
    event.cancel = true
  }
})
```

Les écouteurs renvoient un objet `IDisposable`. Supprimez-les lorsqu’ils ne sont plus nécessaires.

```typescript
beforeDisposable.dispose()
afterDisposable.dispose()
disposable.dispose()
```

### Exécution de commandes

Si vous connaissez l’identifiant et les paramètres d’une commande, exécutez-la avec `FUniver.executeCommand`. Par exemple, cette commande Docs renomme le document actif :

```typescript
const document = univerAPI.getActiveDocument()

if (document) {
  await univerAPI.executeCommand('doc.command.set-name', {
    unitId: document.getId(),
    name: 'Notes du projet',
  })
}
```

## API des événements

Les événements exposés par `univerAPI.Event` proviennent du noyau Univer et des plugins enregistrés dans l’application. Le noyau fournit les événements de commande et du cycle de vie des documents ; les plugins Docs peuvent enrichir cette surface. Avant d’utiliser un événement, vérifiez qu’il appartient à un plugin enregistré.

Consultez la [référence des événements Facade](https://docs.univer.ai/fr-FR/reference/facade/events.md) pour connaître les noms et les types de paramètres disponibles dans la version actuelle.

Utilisez `addEvent` pour vous abonner, puis supprimez l’objet renvoyé pour vous désabonner :

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id }) => {
  if (id === 'doc.command.set-name') {
    console.log('Le nom du document a changé')
  }
})

// Supprimez l’écouteur lorsqu’il n’est plus nécessaire
disposable.dispose()
```

## Annulation et rétablissement

```typescript
await univerAPI.undo()
await univerAPI.redo()
```

## Presse-papiers système

Après l’enregistrement du plugin d’interface Docs, `copy` et `paste` agissent sur la sélection et la position du curseur actuelles dans le document.

```typescript
await univerAPI.copy()
await univerAPI.paste()
```

> [!NOTE]
> Le copier-coller repose sur l’API native du presse-papiers du navigateur. Il peut échouer si la page n’a pas le focus,
> si l’appel ne provient pas d’une action de l’utilisateur ou si l’autorisation d’accès au presse-papiers est indisponible.
> Consultez la [documentation MDN](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API).

## Interface utilisateur

Consultez [Composants de l’interface Docs](https://docs.univer.ai/fr-FR/guides/docs/ui/components.md) pour étendre les menus, la barre d’outils et les autres zones de l’interface Docs.

## WebSocket

Les installations avec prédéfinis exposent `univerAPI.createSocket(url)`. En mode plugin, installez `@univerjs/network`, enregistrez `UniverNetworkPlugin`, puis importez son extension Facade.

```typescript
import { UniverNetworkPlugin } from '@univerjs/network'
import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)
```

Vous pouvez ensuite vous abonner aux événements du socket, envoyer des messages et fermer la connexion :

```typescript
const socket = univerAPI.createSocket('wss://example.com/docs')

socket.open$.subscribe(() => {
  socket.send('hello')
})

socket.message$.subscribe((message) => {
  console.log('Message WebSocket :', message.data)
})

socket.error$.subscribe((error) => {
  console.error('Erreur WebSocket :', error)
})

socket.close()
```

## API des énumérations

Facade expose des énumérations communes par l’intermédiaire de `univerAPI.Enum` :

```typescript
console.log(univerAPI.Enum.UniverInstanceType.UNIVER_DOC)
console.log(univerAPI.Enum.LifecycleStages.Rendered)
```

## API des méthodes utilitaires

Facade expose les utilitaires partagés par l’intermédiaire de `univerAPI.Util` :

```typescript
console.log(univerAPI.Util.tools.isString('Univer Docs')) // true
```