upstream-twenty/packages/twenty-docs/l/pt/developers/extend/apps/layout/command-menu-items.mdx

---
title: Itens do menu de comandos
description: Exponha componentes de front-end como ações rápidas e entradas do menu de comandos (Cmd+K) com `defineCommandMenuItem`.
icon: terminal
---

Um **item de menu de comando** é a ponte entre o usuário e um [front component](/l/pt/developers/extend/apps/layout/front-components). Ele registra o componente no menu de comandos (Cmd+K) do Twenty e, opcionalmente, como um botão fixado de ação rápida no canto superior direito da página.

```ts src/command-menu-items/open-dashboard.command-menu-item.ts
import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  label: 'Open Dashboard',
  shortLabel: 'Dashboard',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});
```

## Campos de configuração

| Campo                                   | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                       |
| --------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `universalIdentifier`                   | Sim         | ID exclusivo e estável para o comando                                                                                                                                                                                                                                                                           |
| `label`                                 | Sim         | Rótulo completo exibido no menu de comandos (Cmd+K)                                                                                                                                                                                                                                                             |
| `frontComponentUniversalIdentifier`     | Sim         | O `universalIdentifier` do componente de front-end que este comando abre                                                                                                                                                                                                                                        |
| `shortLabel`                            | Não         | Rótulo mais curto exibido no botão fixado de ação rápida                                                                                                                                                                                                                                                        |
| `icon`                                  | Não         | **Obsoleto** — ignorado em favor do ícone da aplicação; a compilação emite um aviso se definido                                                                                                                                                                                                                 |
| `isPinned`                              | Não         | Quando `true`, mostra o comando como um botão de ação rápida no canto superior direito da página                                                                                                                                                                                                                |
| `availabilityType`                      | Não         | Controla onde o comando aparece: `'GLOBAL'` (sempre disponível), `'GLOBAL_OBJECT_CONTEXT'` (apenas em páginas com um contexto de objeto — páginas de índice e de registro), `'RECORD_SELECTION'` (apenas quando registros estão selecionados) ou `'FALLBACK'` (exibido quando nenhum outro comando corresponde) |
| `availabilityObjectUniversalIdentifier` | Não         | Restringe o comando a páginas de um tipo específico de objeto (por exemplo, somente em registros de Company)                                                                                                                                                                                                    |
| `conditionalAvailabilityExpression`     | Não         | Uma expressão booleana que controla dinamicamente a visibilidade (veja abaixo)                                                                                                                                                                                                                                  |

## Comandos sem interface

Um item do menu de comandos emparelhado com um [componente de front-end sem interface](/l/pt/developers/extend/apps/layout/front-components#headless-vs-non-headless) é a forma idiomática de disponibilizar uma ação de um clique — executar código, navegar ou confirmar e executar. A página de Front Components aborda os [SDK Command components](/l/pt/developers/extend/apps/layout/front-components#sdk-command-components) (`Command`, `CommandLink`, `CommandModal`, `CommandOpenSidePanelPage`) que lidam com o padrão de ação e desmontagem.

Um fluxo típico: um componente headless renderiza `<Command execute={...} />` (veja o [exemplo completo](/l/pt/developers/extend/apps/layout/front-components#sdk-command-components)), e o item de menu de comando aponta para ele:

```ts src/command-menu-items/run-action.command-menu-item.ts
import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
  label: 'Run my action',
  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
});
```

## Expressões de disponibilidade condicional

O campo `conditionalAvailabilityExpression` permite controlar quando um comando é visível com base no contexto da página atual. Importe variáveis tipadas e operadores de `twenty-sdk` para construir expressões:

```ts src/command-menu-items/bulk-update.command-menu-item.ts
import {
  defineCommandMenuItem,
  objectPermissions,
  everyEquals,
} from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: '...',
  label: 'Bulk Update',
  availabilityType: 'RECORD_SELECTION',
  frontComponentUniversalIdentifier: '...',
  conditionalAvailabilityExpression: everyEquals(
    objectPermissions,
    'canUpdateObjectRecords',
    true,
  ),
});
```

<Note>
  `RECORD_SELECTION` já implica uma seleção não vazia — use `numberOfSelectedRecords` apenas para contagens específicas (por exemplo, `>= 2`).
</Note>

### Variáveis de contexto

Elas representam o estado atual da página:

| Variável                       | Tipo      | Descrição                                                                   |
| ------------------------------ | --------- | --------------------------------------------------------------------------- |
| `pageType`                     | `string`  | Tipo de página atual (por exemplo, `'RecordIndexPage'`, `'RecordShowPage'`) |
| `isInSidePanel`                | `boolean` | Se o componente é renderizado em um painel lateral                          |
| `numberOfSelectedRecords`      | `number`  | Número de registros atualmente selecionados                                 |
| `isSelectAll`                  | `boolean` | Se "selecionar tudo" está ativo                                             |
| `selectedRecords`              | `array`   | Os objetos de registro selecionados                                         |
| `favoriteRecordIds`            | `array`   | IDs dos registros marcados como favoritos                                   |
| `objectPermissions`            | `object`  | Permissões para o tipo de objeto atual                                      |
| `targetObjectReadPermissions`  | `object`  | Permissões de leitura para o objeto alvo                                    |
| `targetObjectWritePermissions` | `object`  | Permissões de escrita para o objeto alvo                                    |
| `featureFlags`                 | `object`  | Flags de recurso ativas                                                     |
| `objectMetadataItem`           | `object`  | Metadados do tipo de objeto atual                                           |
| `hasAnySoftDeleteFilterOnView` | `boolean` | Se a visualização atual tem um filtro de soft-delete                        |

### Operadores

Combine variáveis em expressões booleanas:

| Operador                            | Descrição                                                              |
| ----------------------------------- | ---------------------------------------------------------------------- |
| `isDefined(value)`                  | `true` se o valor não for null/undefined                               |
| `isNonEmptyString(value)`           | `true` se o valor for uma string não vazia                             |
| `includes(array, value)`            | `true` se o array contiver o valor                                     |
| `includesEvery(array, prop, value)` | `true` se a propriedade de cada item incluir o valor                   |
| `every(array, prop)`                | `true` se a propriedade for truthy em cada item                        |
| `everyDefined(array, prop)`         | `true` se a propriedade estiver definida em cada item                  |
| `everyEquals(array, prop, value)`   | `true` se a propriedade for igual ao valor em cada item                |
| `some(array, prop)`                 | `true` se a propriedade for truthy em pelo menos um item               |
| `someDefined(array, prop)`          | `true` se a propriedade estiver definida em pelo menos um item         |
| `someEquals(array, prop, value)`    | `true` se a propriedade for igual ao valor em pelo menos um item       |
| `someNonEmptyString(array, prop)`   | `true` se a propriedade for uma string não vazia em pelo menos um item |
| `none(array, prop)`                 | `true` se a propriedade for falsy em cada item                         |
| `noneDefined(array, prop)`          | `true` se a propriedade for undefined em cada item                     |
| `noneEquals(array, prop, value)`    | `true` se a propriedade não for igual ao valor em nenhum item          |