명령 메뉴 항목 - Twenty Documentation

명령 메뉴 항목은 사용자와 프런트 컴포넌트 사이를 연결하는 다리입니다. 이 항목은 Twenty의 명령 메뉴(Cmd+K)에 구성 요소를 등록하고, 선택적으로 페이지 오른쪽 상단 모서리에 고정된 빠른 작업 버튼으로도 등록합니다.

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',
  icon: 'IconLayoutDashboard',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

구성 필드

필드	필수	설명
`universalIdentifier`	예	명령의 안정적인 고유 ID
`label`	예	명령 메뉴(Cmd+K)에 표시되는 전체 레이블
`frontComponentUniversalIdentifier`	예	이 명령으로 열리는 프런트 컴포넌트의 `universalIdentifier`
`shortLabel`	아니요	고정된 빠른 작업 버튼에 표시되는 더 짧은 레이블
`icon`	아니요	레이블 옆에 표시되는 아이콘 이름(예: `'IconBolt'`, `'IconSend'`)
`isPinned`	아니요	`true`이면 페이지 우측 상단에 빠른 작업 버튼으로 명령을 표시합니다
`availabilityType`	아니요	명령이 표시되는 위치를 제어합니다: ‘GLOBAL’(항상 사용 가능), ‘RECORD_SELECTION’(레코드가 선택된 경우에만), ‘FALLBACK’(다른 명령이 일치하지 않을 때 표시)
`availabilityObjectUniversalIdentifier`	아니요	명령을 특정 객체 타입의 페이지로 제한합니다(예: Company 레코드에서만)
`conditionalAvailabilityExpression`	아니요	표시 여부를 동적으로 제어하는 불리언 표현식(아래 참조)

헤드리스 명령

헤드리스 프런트 컴포넌트와 짝을 이룬 명령 메뉴 항목은 원클릭 작업—코드 실행, 이동, 확인 후 실행—을 제공하는 가장 전형적인 방식입니다. 프런트 컴포넌트 페이지에서는 동작 후 언마운트 패턴을 처리하는 SDK Command 구성 요소 (Command, CommandLink, CommandModal, CommandOpenSidePanelPage)를 다룹니다. 일반적인 흐름:

src/front-components/run-action.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/command';
import { CoreApiClient } from 'twenty-sdk/clients';

const RunAction = () => {
  const execute = async () => {
    const client = new CoreApiClient();
    await client.mutation({
      createTask: {
        __args: { data: { title: 'Created by my app' } },
        id: true,
      },
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
  name: 'run-action',
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
});

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',
  icon: 'IconPlayerPlay',
  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
});

조건부 가용성 표현식

conditionalAvailabilityExpression 필드를 사용하면 현재 페이지 컨텍스트에 따라 명령의 표시 시점을 제어할 수 있습니다. 표현식을 만들기 위해 twenty-sdk에서 타입이 지정된 변수와 연산자를 임포트하세요:

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,
  ),
});

RECORD_SELECTION은 이미 비어 있지 않은 선택을 의미하므로, 특정 개수를 나타낼 때만(예: >= 2) numberOfSelectedRecords를 사용하세요.

컨텍스트 변수

이는 현재 페이지의 상태를 나타냅니다:

변수	유형	설명
`pageType`	`string`	현재 페이지 타입(예: ‘RecordIndexPage’, ‘RecordShowPage’)
`isInSidePanel`	`boolean`	컴포넌트가 사이드 패널에서 렌더링되는지 여부
`numberOfSelectedRecords`	`number`	현재 선택된 레코드 수
`isSelectAll`	`boolean`	”전체 선택”이 활성화되었는지 여부
`selectedRecords`	`array`	선택된 레코드 객체
`favoriteRecordIds`	`array`	즐겨찾기된 레코드의 ID들
`objectPermissions`	`object`	현재 객체 타입에 대한 권한
`targetObjectReadPermissions`	`object`	대상 객체에 대한 읽기 권한
`targetObjectWritePermissions`	`object`	대상 객체에 대한 쓰기 권한
`featureFlags`	`object`	활성화된 기능 플래그
`objectMetadataItem`	`object`	현재 객체 타입의 메타데이터
`hasAnySoftDeleteFilterOnView`	`boolean`	현재 뷰에 소프트 삭제 필터가 있는지 여부

연산자

변수를 결합해 불리언 표현식을 만듭니다:

연산자	설명
`isDefined(value)`	값이 null/undefined가 아니면 `true`
`isNonEmptyString(value)`	값이 비어 있지 않은 문자열이면 `true`
`includes(array, value)`	배열에 해당 값이 포함되어 있으면 `true`
`includesEvery(array, prop, value)`	모든 항목의 속성에 해당 값이 포함되어 있으면 `true`
`every(array, prop)`	모든 항목에서 해당 속성이 truthy이면 `true`
`everyDefined(array, prop)`	모든 항목에서 해당 속성이 정의되어 있으면 `true`
`everyEquals(array, prop, value)`	모든 항목에서 해당 속성이 그 값과 같으면 `true`
`some(array, prop)`	적어도 한 항목에서 해당 속성이 truthy이면 `true`
`someDefined(array, prop)`	적어도 한 항목에서 해당 속성이 정의되어 있으면 `true`
`someEquals(array, prop, value)`	적어도 한 항목에서 해당 속성이 그 값과 같으면 `true`
`someNonEmptyString(array, prop)`	적어도 한 항목에서 해당 속성이 비어 있지 않은 문자열이면 `true`
`none(array, prop)`	모든 항목에서 해당 속성이 falsy이면 `true`
`noneDefined(array, prop)`	모든 항목에서 해당 속성이 정의되지 않았으면 `true`
`noneEquals(array, prop, value)`	어떤 항목에서도 해당 속성이 그 값과 같지 않으면 `true`

​구성 필드

​헤드리스 명령

​조건부 가용성 표현식

​컨텍스트 변수

​연산자

구성 필드

헤드리스 명령

조건부 가용성 표현식

컨텍스트 변수

연산자