---
title: 보기
description: 앱의 객체에 대해 열 순서, 필터, 그룹이 미리 구성된 저장된 보기를 제공하세요.
icon: list
---

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

```ts 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`를 참조합니다.
* 또한 더 고급 구성을 위해 `filters`, `filterGroups`, `sorts`, `groups`, `fieldGroups`를 선언할 수 있습니다.
* `position`은 동일한 객체에 여러 뷰가 있을 때의 정렬 순서를 제어합니다.

## 선택적 속성

| 속성                                                                                                          | 값                                                                                  | 설명                                                                                              |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `type`                                                                                                      | `ViewType.TABLE`(기본값), `ViewType.KANBAN`, `ViewType.CALENDAR`                      | 레코드가 어떻게 배치되는지에 대한 설정입니다. (`FIELDS_WIDGET` / `TABLE_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`                                                | `ViewCalendarLayout.DAY` / `WEEK` / `MONTH`                                        | 캘린더 뷰: 레이아웃 및 레코드의 위치를 결정하는 날짜 필드입니다.                                                           |

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

## 필터

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

```ts
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` 타입의 [탐색 메뉴 항목](/l/ko/developers/extend/apps/layout/navigation-menu-items)과 연결해야 합니다. 이것이 표준적인 패턴입니다. 일반적으로 각 커스텀 객체는 기본 보기와, 그 보기를 여는 사이드바 항목을 함께 제공합니다.
