보기 - Twenty Documentation

보기는 객체 레코드가 어떻게 표시될지에 대한 저장된 구성입니다. 어떤 필드가 표시되는지, 그 순서, 표시 여부, 적용된 필터나 그룹 등을 정의합니다. defineView()를 사용해 앱에 미리 구성된 보기를 포함할 수 있습니다. 일반적으로 생성하는 각 커스텀 객체마다 기본 목록 보기를 제공합니다.

src/views/example-view.ts

import { defineView, ViewKey } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';

export default defineView({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'All example items',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  key: ViewKey.INDEX,
  position: 0,
  fields: [
    {
      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});

핵심 요점

objectUniversalIdentifier는 이 뷰가 적용되는 객체를 지정합니다. 이 객체는 사용자가 정의한 커스텀 객체일 수도 있고, 표준 Twenty 객체일 수도 있습니다.
key: ViewKey.INDEX는 뷰를 객체의 기본 목록 보기( OBJECT 내비게이션 항목이 여는 보기)로 표시합니다.
fields는 어떤 열을 어떤 순서로 표시할지를 제어합니다. 각 필드는 fieldMetadataUniversalIdentifier를 참조합니다. 자동 생성된 시스템 필드(예: createdAt)를 참조하는 방법은 시스템 필드 대상으로 지정하기를 참조하세요.
또한 더 고급 구성을 위해 filters, filterGroups, sorts, groups, fieldGroups를 선언할 수 있습니다.
position은 동일한 객체에 여러 뷰가 있을 때의 정렬 순서를 제어합니다.

선택적 속성

속성	값	설명
`type`	`ViewType.TABLE`(기본값), `ViewType.KANBAN`, `ViewType.CALENDAR`	레코드가 어떻게 배치되는지에 대한 설정입니다. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET`, 및 `CALENDAR_WIDGET`도 존재하지만, 페이지 레이아웃 위젯에서 내부적으로 사용됩니다.)
`visibility`	`ViewVisibility.WORKSPACE`(기본값), `ViewVisibility.UNLISTED`	워크스페이스 전체에 대해 뷰가 목록에 표시되는지, 선택기에서 숨겨지는지 여부입니다.
`openRecordIn`	`ViewOpenRecordIn.SIDE_PANEL`(기본값), `ViewOpenRecordIn.RECORD_PAGE`	레코드를 클릭했을 때 어디에서 열리는지에 대한 설정입니다.
`정렬`	`{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]`	기본 정렬 순서입니다.
`isCompact`	`boolean`	행을 압축 형태로 표시합니다.
`mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups`	—	레코드를 필드별로 그룹화합니다(예: 칸반 열).
`kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth`	`AggregateOperations.*`	칸반 열의 집계 및 크기 설정입니다.
`calendarLayout`, `calendarFieldMetadataUniversalIdentifier`, `calendarEndFieldMetadataUniversalIdentifier`	`ViewCalendarLayout.DAY` / `WEEK` / `MONTH`	캘린더 뷰: 레이아웃, 레코드의 위치를 결정하는 날짜 필드, 그리고 선택적인 종료 날짜 필드입니다.

위의 모든 enum은 twenty-sdk/define에서 내보내집니다.

필터

뷰는 미리 적용된 필터와 함께 제공될 수 있습니다. 각 필터에는 세 가지 요소가 있습니다: 필터링할 필드, 연산자(어떻게 비교할지), 그리고 값(무엇과 비교할지). 세 가지가 모두 맞아야 하며, 필드 유형에 적용되지 않는 연산자를 사용하면 동기화 시 거부됩니다.

import { ViewFilterOperand } from 'twenty-sdk/define';

filters: [
  {
    universalIdentifier: '...',
    fieldMetadataUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
    operand: ViewFilterOperand.IS,
    value: ['ACTIVE'],
  },
],

필드 유형별 지원되는 연산자

필드 유형	지원되는 피연산자
`TEXT`, `EMAILS`, `FULL_NAME`, `ADDRESS`, `LINKS`, `PHONES`, `RAW_JSON`, `FILES`, `ACTOR`, `ARRAY`	`CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`
`ACTOR.source`, `ACTOR.workspaceMemberId`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`SELECT`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`MULTI_SELECT`	`CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`
`RELATION`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`NUMBER`	`IS`, `IS_NOT`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_EMPTY`, `IS_NOT_EMPTY`
`RATING`	`IS`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_EMPTY`, `IS_NOT_EMPTY`
`CURRENCY`, `CURRENCY.amountMicros`	`GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`CURRENCY.currencyCode`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`DATE`, `DATE_TIME`	`IS`, `IS_RELATIVE`, `IS_IN_PAST`, `IS_IN_FUTURE`, `IS_TODAY`, `IS_BEFORE`, `IS_AFTER`, `IS_EMPTY`, `IS_NOT_EMPTY`
`BOOLEAN`	`IS`
`UUID`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`TS_VECTOR`	`VECTOR_SEARCH`

유사한 이름을 가진 필드 타입이라도 전혀 다른 피연산자를 사용할 수 있습니다. 대표적인 예로 SELECT와 MULTI_SELECT가 있습니다.

피연산자별 값 구조

value 필드는 항상 JSON으로 직렬화할 수 있는 값이지만, 기대되는 구조는 피연산자에 따라 달라집니다:

피연산자 그룹	값 구조	예시
`SELECT`에서의 `IS`, `IS_NOT`	옵션 키(문자열) 배열	`['ACTIVE', 'PENDING']`
`MULTI_SELECT`에서의 `CONTAINS`, `DOES_NOT_CONTAIN`	옵션 키(문자열) 배열	`['TAG_A']`
`RELATION`에서의 `IS`, `IS_NOT`	레코드 ID(uuid) 배열	`['c5a1...']`
텍스트 계열 필드에서의 `CONTAINS`, `DOES_NOT_CONTAIN`	문자열	`'acme'`
`NUMBER`에서의 `IS`, `IS_NOT`	문자열(값)	`'5'`
`RATING` / `UUID`에서의 `IS`	문자열(값)	`'5'`
`GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`	문자열(경계값)	`'10'`
`DATE` / `DATE_TIME`에서의 `IS`, `IS_BEFORE`, `IS_AFTER`	ISO 8601 문자열	`'2025-01-01T00:00:00Z'`
`IS_EMPTY`, `IS_NOT_EMPTY`	빈 문자열	`''`
`BOOLEAN`에서의 `IS`	`'true'` 또는 `'false'`	`'true'`

보기가 UI에 표시되는 방식

보기만으로는 사이드바에서 직접 접근할 수 없습니다. 사이드바에 표시하려면, 해당 보기의 universalIdentifier를 가리키는 VIEW 타입의 탐색 메뉴 항목과 연결해야 합니다. 이것이 표준적인 패턴입니다. 일반적으로 각 커스텀 객체는 기본 보기와, 그 보기를 여는 사이드바 항목을 함께 제공합니다.

개요

앱

API

셀프 호스팅

기여

보기

핵심 요점

선택적 속성

필터

필드 유형별 지원되는 연산자

피연산자별 값 구조

보기가 UI에 표시되는 방식

​핵심 요점

​선택적 속성

​필터

​필드 유형별 지원되는 연산자

​피연산자별 값 구조

​보기가 UI에 표시되는 방식

핵심 요점

선택적 속성

필터

필드 유형별 지원되는 연산자

피연산자별 값 구조

보기가 UI에 표시되는 방식