Ön uç bileşenleri

Ön uç bileşenler, Twenty’nin UI’si içinde doğrudan görüntülenen React bileşenleridir. Remote DOM kullanan izole bir Web Worker içinde çalışırlar — kodunuz, korumalı (sandbox) ve opak kökenli bir iframe içinde yürütülür; ancak UI, o iframe ile sınırlanmak yerine sayfada yerel olarak işlenir.

Front bileşenleri hâlâ aktif geliştirme aşamasındadır. Kodunuz gerçek bir tarayıcı sayfası yerine kısmi bir DOM üzerinde çalışır, bu nedenle ileri düzey kullanımlar çoğu zaman sessizce başarısız olabilir. Mevcut sınırlamalara bakın.

Ön uç bileşenlerinin kullanılabileceği yerler

Ön uç bileşenler, Twenty içinde üç konumda işlenebilir:

Yan panel — Headless olmayan ön uç bileşenler, sağ taraftaki yan panelde açılır. Bir ön uç bileşeni komut menüsünden tetiklendiğinde varsayılan davranış budur.
Widget’lar (panolar ve kayıt sayfaları) — Ön uç bileşenler, sayfa düzenleri içinde widget olarak gömülebilir. Bir pano veya kayıt sayfası düzeni yapılandırılırken kullanıcılar bir ön uç bileşen widget’ı ekleyebilir.
Uygulama ayarları — defineSettingsFrontComponent() ile tanımlandığında, ön uç bileşeni, varsayılan değişken yapılandırma kullanıcı arayüzü yerine uygulamanın Settings sekmesi içinde bir bölüm olarak görüntülenir.

Tek başına bir ön uç bileşenine kullanıcı arayüzünden erişilemez — onu görünür hâle getirmeniz gerekir. Bunu yapmanın üç yolu vardır:

Onu bir komut menüsü öğesi ile eşleştirin — komut menüsüne (Cmd+K) ve isteğe bağlı olarak sabitlenmiş hızlı işlem olarak kaydeder.
Onu bir sayfa düzeni içinde widget olarak gömün — bir kaydın ayrıntı sayfasına veya panosuna yerleştirir.
Bunu defineSettingsFrontComponent() ile tanımlayın — varsayılan değişken yapılandırma kullanıcı arayüzü yerine uygulamanın Settings sekmesi içinde bir bölüm olarak görüntülenir.

Basit örnek

Bir ön uç bileşenini çalışır halde görmenin en hızlı yolu, onu defineCommandMenuItem ile eşleştirmektir; böylece sayfanın sağ üst köşesinde bir hızlı işlem düğmesi olarak görünür:

src/front-components/hello-world.tsx

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

const HelloWorld = () => {
  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h1>Hello from my app!</h1>
      <p>This component renders inside Twenty.</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
  name: 'hello-world',
  description: 'A simple front component',
  component: HelloWorld,
});

src/command-menu-items/hello-world.command-menu-item.ts

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

export default defineCommandMenuItem({
  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
  shortLabel: 'Hello',
  label: 'Hello World',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

yarn twenty dev ile senkronize ettikten sonra (veya tek seferlik bir yarn twenty apply çalıştırdıktan sonra), hızlı işlem sayfanın sağ üst köşesinde görünür:

Bileşeni satır içi işlemek için üzerine tıklayın.

Yapılandırma alanları

Alan	Zorunlu	Açıklama
`universalIdentifier`	Evet	Bu bileşen için kalıcı benzersiz kimlik
`component`	Evet	Bir React bileşen fonksiyonu
`name`	Hayır	Görünen Ad
`description`	Hayır	Bileşenin ne yaptığına dair açıklama
`isHeadless`	Hayır	Bileşenin görünür bir kullanıcı arayüzü yoksa `true` olarak ayarlayın (aşağıya bakın)

Bir ön uç bileşenini bir sayfaya yerleştirme

Komutların ötesinde, bir ön uç bileşenini bir sayfa düzeninde widget olarak ekleyerek doğrudan bir kayıt sayfasına gömebilirsiniz. Ayrıntılar için Sayfa Düzenleri bölümüne bakın.

Özel ayarlar bileşeni

Uygulamanızın Settings sekmesindeki otomatik oluşturulan değişken yapılandırma kullanıcı arayüzünü kendi bileşeninizle değiştirmek için, defineFrontComponent yerine defineSettingsFrontComponent ile tanımlayın. Ayarlar bileşeni her zaman görünür bir kullanıcı arayüzü oluşturduğundan, kabul edilmeyen isHeadless dışında, aynı yapılandırma alanlarını alır ve ek olarak bileşeni uygulamanın ayarlar arayüzü olarak işaretler. Bileşen, tüm sekmenin yerine geçmek yerine, Settings sekmesi içinde bir bölüm olarak görüntülenir. Twenty’nin sistem tarafından yönetilen bölümleri — otomatik yükseltme, App URL ve bağlantılar — her zaman bunun üstünde görüntülenir ve uygulama tarafından geçersiz kılınamaz.

src/front-components/app-settings.tsx

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

const AppSettings = () => {
  return (
    <div style={{ padding: '20px' }}>
      <h2>My app settings</h2>
      {/* render your own configuration UI here */}
    </div>
  );
};

export default defineSettingsFrontComponent({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'app-settings',
  description: "Custom UI for the app's Settings tab",
  component: AppSettings,
});

Uygulama başına yalnızca bir ayarlar ön uç bileşenine izin verilir; birden fazla tanımlanması derlemenin başarısız olmasına neden olur. Mevcut olduğunda, uygulamanın Settings sekmesi, varsayılan değişken yapılandırma kullanıcı arayüzü yerine bu bileşeni görüntüler.

Headless ve headless olmayan

Ön uç bileşenler, isHeadless seçeneğiyle kontrol edilen iki işleme kipiyle gelir: Headless olmayan (varsayılan) — Bileşen görünür bir kullanıcı arayüzü (UI) oluşturur. Komut menüsünden tetiklendiğinde yan panelde açılır. isHeadless false olduğunda veya belirtilmediğinde bu varsayılan davranıştır. Headless (isHeadless: true) — Bileşen arka planda görünmez şekilde bağlanır. Yan paneli açmaz. Headless bileşenler, mantığı çalıştırıp ardından kendilerini kaldıran eylemler için tasarlanmıştır — örneğin, bir async görevi çalıştırma, bir sayfaya gitme veya bir onay modalı gösterme. Aşağıda açıklanan SDK Command bileşenleriyle doğal olarak eşleşirler.

src/front-components/sync-tracker.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useSelectedRecordIds, enqueueSnackbar } from 'twenty-sdk/front-component';
import { useEffect } from 'react';

const SyncTracker = () => {
  const [recordId] = useSelectedRecordIds();

  useEffect(() => {
    enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
  }, [recordId]);

  return null;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-tracker',
  description: 'Tracks record views silently',
  isHeadless: true,
  component: SyncTracker,
});

Bileşen null döndürdüğü için, Twenty bunun için bir kapsayıcı oluşturmayı atlar — düzende boş alan görünmez. Bileşen yine de tüm hook’lara ve host iletişim API’sine erişime sahiptir.

SDK Command bileşenleri

twenty-sdk paketi, headless ön uç bileşenler için tasarlanmış dört Command yardımcı bileşeni sağlar. Her bileşen bağlandığında bir eylem yürütür, hataları bir snackbar bildirimi göstererek ele alır ve tamamlandığında ön bileşeni otomatik olarak kaldırır. Bunları twenty-sdk/front-component içinden içe aktarın:

Command — execute prop’u aracılığıyla async bir geri çağrıyı çalıştırır.
CommandLink — Bir uygulama yoluna gider. Props: to, params, queryParams, options.
CommandModal — Bir onay modalı açar. Kullanıcı onaylarsa execute geri çağrısını yürütür. Props: title, subtitle, execute, confirmButtonText, confirmButtonAccent.
CommandOpenSidePanelPage — Bir yan panel sayfasını açar. Props, page’e bağlıdır — örneğin ViewRecord, recordId + objectNameSingular alır (ayrıca kaydı belirli bir sekmede açmak için isteğe bağlı bir tab kimliği alır), diğer sayfalar pageTitle + pageIcon alır.

Command kullanarak komut menüsünden bir eylem çalıştıran headless bir ön uç bileşenin tam örneği:

src/front-components/run-action.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

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

Ve yürütmeden önce onay istemek için CommandModal kullanan bir örnek:

src/front-components/delete-draft.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { CommandModal } from 'twenty-sdk/front-component';

const DeleteDraft = () => {
  const execute = async () => {
    // perform the deletion
  };

  return (
    <CommandModal
      title="Delete draft?"
      subtitle="This action cannot be undone."
      execute={execute}
      confirmButtonText="Delete"
      confirmButtonAccent="danger"
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
  name: 'delete-draft',
  description: 'Deletes a draft with confirmation',
  component: DeleteDraft,
  isHeadless: true,
});

Ve geçerli kaydı belirli bir sekmede yan panelde açmak için CommandOpenSidePanelPage kullanan bir örnek. tab, bir sayfa düzeni sekme kimliğidir (varsayılan düzenler company-tab-emails veya company-tab-timeline gibi kimlikler kullanır; özel düzenler sekmenin kendi kimliğini kullanır). Kimlik kaydın düzeninde mevcut değilse, bunun yerine varsayılan sekme açılır:

src/front-components/open-company-emails.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  CommandOpenSidePanelPage,
  SidePanelPages,
  useSelectedRecordIds,
} from 'twenty-sdk/front-component';

const OpenCompanyEmails = () => {
  const selectedRecordIds = useSelectedRecordIds();
  const recordId = selectedRecordIds.length === 1 ? selectedRecordIds[0] : null;

  if (!recordId) {
    return null;
  }

  return (
    <CommandOpenSidePanelPage
      page={SidePanelPages.ViewRecord}
      recordId={recordId}
      objectNameSingular="company"
      tab="company-tab-emails"
      resetNavigationStack={false}
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
  name: 'open-company-emails',
  description: 'Opens the current company on its Emails tab',
  component: OpenCompanyEmails,
  isHeadless: true,
});

Bir mantık işlevini çağırma

Ön bileşenler, tarayıcı tarafında, opak kaynaklı bir iframe içinde yer alan korumalı (sandbox) bir Web Worker içinde çalışırken, mantık işlevleri sunucu tarafında çalışır. İkisi arasında doğrudan, işlem içi bir çağrı yoktur — bunun yerine, bir ön bileşen bir mantık işlevine HTTP üzerinden erişir. httpRouteTriggerSettings ile bildirilen bir mantık işlevi, rota yolunda HTTP üzerinden erişilebilir durumdadır. RestApiClient, /s/ ile başlayan yolları uygulama rotaları olarak ele alır, bunları fonksiyonlarınızın sunulduğu URL’ye çözümler ve TWENTY_APP_ACCESS_TOKEN ile kimlik doğrulaması yapar.

Twenty Cloud üzerinde, HTTP ile tetiklenen mantık işlevleri, çalışma alanı başına ayrılmış özel bir etki alanında https://\<your-workspace-subdomain>.withtwenty.com\<path> adresinde sunulur. Harici çağrıcılar için, tam URL’yi işlevin HTTP trigger ayarlarından veya uygulamanın Settings sekmesinden kopyalayın.

Başsız bir ön bileşen, çağrıyı Command bileşeni aracılığıyla mount sırasında çalıştırabilir ve ardından otomatik olarak unmount olabilir:

src/front-components/sync-prs.tsx

import { RestApiClient } from 'twenty-client-sdk/rest';
import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/front-component';

const SyncPrs = () => {
  const execute = async () => {
    await new RestApiClient().post('/s/github/fetch-prs', {
      owner: 'twentyhq',
      repo: 'twenty',
    });
  };

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

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-prs',
  description: 'Triggers the fetch-prs logic function',
  isHeadless: true,
  component: SyncPrs,
});

RestApiClient’e iletilen yol, başına /s eklenmiş mantık işlevinin httpRouteTriggerSettings.path değeridir. isAuthRequired: true ayarını koruyun; bileşeniniz için Twenty’nin oluşturduğu TWENTY_APP_ACCESS_TOKEN isteği kimlik doğrular:

src/logic-functions/fetch-prs.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import type { RoutePayload } from 'twenty-sdk/logic-function';

const handler = async (event: RoutePayload) => {
  const { owner, repo } = (event.body ?? {}) as { owner: string; repo: string };
  // ...fetch from GitHub and persist records...
  return { ok: true };
};

export default defineLogicFunction({
  universalIdentifier: '...',
  name: 'fetch-prs',
  handler,
  httpRouteTriggerSettings: {
    path: '/github/fetch-prs',
    httpMethod: 'POST',
    isAuthRequired: true,
  },
});

TWENTY_APP_ACCESS_TOKEN otomatik olarak enjekte edilir — bkz. Uygulama değişkenleri. Gizli uygulama değişkenleri asla ön bileşenlere açığa çıkarılmadığından, API anahtarlarını ve diğer hassas mantığı ön bileşende değil, mantık işlevinin içinde tutun.

Twenty REST API’sini çağırma

Uygulama HTTP rotalarını çağırmak veya bir front bileşeninden Twenty kayıtlarını okumak ve yazmak için twenty-client-sdk/rest paketinden RestApiClient kullanın. /s/... yollarını çalışma alanınızdaki işlevlerin temel URL’sine, /rest/... dahil diğer tüm yolları ise TWENTY_API_URL’ye gönderir.

Yöntem	Açıklama
`get(path, options?)`	Bir `GET` isteği gönderir
`post(path, body?, options?)`	Bir `POST` isteği gönderir
`put(path, body?, options?)`	Bir `PUT` isteği gönderir
`patch(path, body?, options?)`	Bir `PATCH` isteği gönderir
`delete(path, options?)`	Bir `DELETE` isteği gönderir
`request(method, path, options?)`	Herhangi bir HTTP yöntemiyle genel istek
`resolveUrl(path, options?)`	Bir istekte bulunmadan (bağlantılar için) bir yolu tam URL’sine çözümler

options, headers, query (sorgu dizesi parametrelerinin kaydı; null benzeri değerler atlanır) ve signal aracılığıyla bir AbortSignal kabul eder. FormData olmayan bir body nesnesi otomatik olarak JSON’a serileştirilir. 401 durumunda, istemci erişim jetonunu bir kez ana makine (host) üzerinden yeniler ve isteği yeniden dener. Temel URL ve jeton varsayılan olarak ortamdan çözümlenir. Gerektiğinde — örneğin testlerde — kurucuya (constructor) geçersiz kılmalar (override) iletin:

const client = new RestApiClient({
  baseUrl: 'https://myworkspace.twenty.com',
  token: 'my-token',
});

Başarısız istekler, status, statusText, url ve ayrıştırılmış body değerlerini açığa çıkaran bir RestApiClientError fırlatır:

import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';

const client = new RestApiClient();

try {
  const people = await client.get('/rest/people', {
    query: { limit: 10 },
  });
} catch (error) {
  if (error instanceof RestApiClientError) {
    console.error(error.status, error.body);
  }
}

Çalışma zamanı bağlamına erişme

Bileşeninizin içinde, geçerli kullanıcıya, kayda ve bileşen örneğine erişmek için SDK hook’larını kullanın:

src/front-components/record-info.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  useUserId,
  useSelectedRecordIds,
  useFrontComponentId,
} from 'twenty-sdk/front-component';

const RecordInfo = () => {
  const userId = useUserId();
  const [recordId] = useSelectedRecordIds();
  const componentId = useFrontComponentId();

  return (
    <div>
      <p>User: {userId}</p>
      <p>Record: {recordId ?? 'No record context'}</p>
      <p>Component: {componentId}</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
  name: 'record-info',
  component: RecordInfo,
});

Kullanılabilir hook’lar:

Hook	Döndürür	Açıklama
`useUserId()`	`string` veya `null`	Geçerli kullanıcının ID’si
`useSelectedRecordIds()`	`string[]`	Tüm seçili kayıt kimlikleri (hiçbiri seçilmediyse boş dizi)
`useRecordId()`	`string` veya `null`	Kullanımdan kaldırıldı. Bunun yerine `useSelectedRecordIds()` kullanın
`useFrontComponentId()`	`string`	Bu bileşen örneğinin ID’si
`useColorScheme()`	`'light'` veya `'dark'`	Ana makine kullanıcı arayüzünün etkin renk şeması (`System` zaten çözümlenmiştir)
`useFrontComponentExecutionContext(selector)`	değişir	Bir seçici işlevle tam yürütme bağlamına erişin

Uygulama değişkenleri

isSecret: false ile defineApplication() içinde tanımlanan uygulama değişkenleri, getApplicationVariable yardımcı işlevi aracılığıyla ön uç bileşenleri içinde kullanılabilir:

src/front-components/greeting.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { getApplicationVariable } from 'twenty-sdk/front-component';

const Greeting = () => {
  const recipientName = getApplicationVariable('DEFAULT_RECIPIENT_NAME') ?? 'World';

  return <p>Hello, {recipientName}!</p>;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'greeting',
  component: Greeting,
});

Gizli değişkenler (isSecret: true) ön uç bileşenlere açıklanmaz. Bunlar yalnızca sunucu tarafında çalışan mantık işlevlerinde kullanılabilir. Bu, API anahtarları gibi hassas değerlerin tarayıcıya gönderilmesini engeller.

getApplicationVariable, değişkenin bildirilen type değerinden bağımsız olarak her zaman bir string (veya undefined) döndürür. String, türe göre tutarlı bir şekilde serileştirilir (boolean değerler "true" / "false", sayılar ondalık dizeler olarak, diziler/nesneler JSON olarak) ve bu, process.env mantık işlevi için kullanılan formatla aynıdır — veriyi kendiniz ayrıştırın (Number(...), JSON.parse(...), === 'true'). Değişken türleri bölümüne bakın. Aşağıdaki sistem değişkenleri her zaman process.env aracılığıyla kullanılabilir:

Değişken	Açıklama
`TWENTY_API_URL`	Twenty çekirdek API’sinin temel URL’si
`TWENTY_APP_ACCESS_TOKEN`	Uygulamanızın rolüyle sınırlanan kısa ömürlü bir belirteç

`TWENTY_FUNCTIONS_URL`

Twenty ayrıca TWENTY_FUNCTIONS_URL değişkenini front bileşenlerine ve mantık işlevlerine enjekte eder: bu, uygulamanızın HTTP ile tetiklenen mantık işlevlerinin sunulduğu temel URL’dir. Bu değişken, bu URL her zaman Twenty sunucusunun kendisi olmadığı için mevcuttur. Twenty Cloud üzerinde, uygulama rotaları, uygulama tarafından yazılmış yanıtların Twenty uygulamasının kaynağı yerine yalıtılmış bir kaynak üzerinde çalışması için, çalışma alanı başına ayrılmış özel bir etki alanında (https://\<your-workspace-subdomain>.withtwenty.com veya yapılandırıldığında uygulamanın birincil genel etki alanında) sunulur. Self-hosted ve yerel örnekler, uygulama rotalarını sunucunun kendisinde /s öneki altında sunar ve değişkeni hiç ayarlamayabilir. Temel URL, çalışma alanına ve örneğe göre değiştiğinden, kodunuz bunu sabit olarak yazamaz — sunucu, çalışma zamanında doğru değeri enjekte eder. Bu değişkeni doğrudan okumanız nadiren gerekir. Rotalarınızı, yolu /s/ önekiyle birlikte vererek RestApiClient üzerinden çağırın; istemci URL’yi sizin için çözümler: /s önekini kaldırır ve TWENTY_FUNCTIONS_URL’yi hedefler, değişken ayarlı değilse \<TWENTY_API_URL>/s adresine geri döner. Mutlak URL’yi bir istek göndermeden elde etmek için, örneğin bir bağlantı için, resolveUrl('/s/\<path>') kullanın. Değişkeni yalnızca bir URL’yi elle oluştururken doğrudan okuyun:

const routeUrl = `${process.env.TWENTY_FUNCTIONS_URL || `${process.env.TWENTY_API_URL}/s`}/documents/generate`;

Host iletişim API’si

Ön uç bileşenleri, twenty-sdk’deki işlevleri kullanarak gezinmeyi, modalları ve bildirimleri tetikleyebilir:

Fonksiyon	Açıklama
`navigate(to, params?, queryParams?, options?)`	Uygulamada bir sayfaya git
`openSidePanelPage(params)`	Bir yan panel aç
`closeSidePanel()`	Yan paneli kapat
`openCommandConfirmationModal(params)`	Bir onay iletişim kutusu göster
`enqueueSnackbar(params)`	Bir toast bildirimi göster
`unmountFrontComponent()`	Bileşeni kaldır (unmount)
`updateProgress(progress)`	Bir ilerleme göstergesini güncelle

Bir eylem tamamlandıktan sonra bir snackbar göstermek ve yan paneli kapatmak için host API’sini kullanan bir örnek:

src/front-components/archive-record.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { enqueueSnackbar, closeSidePanel, useSelectedRecordIds } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const ArchiveRecord = () => {
  const [recordId] = useSelectedRecordIds();

  const handleArchive = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      updateTask: {
        __args: { id: recordId, data: { status: 'ARCHIVED' } },
        id: true,
      },
    });

    await enqueueSnackbar({
      message: 'Record archived',
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Archive this record?</p>
      <button onClick={handleArchive}>Archive</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
  name: 'archive-record',
  description: 'Archives the current record',
  component: ArchiveRecord,
});

Birden çok kayıtla çalışma

Birden çok seçili kaydı yönetmek için useSelectedRecordIds() kullanın. Bu, toplu işlemler için kullanışlıdır:

src/front-components/bulk-export.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useSelectedRecordIds } from 'twenty-sdk/front-component';
import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const BulkExport = () => {
  const selectedRecordIds = useSelectedRecordIds();

  const handleExport = async () => {
    const client = new CoreApiClient();

    for (const recordId of selectedRecordIds) {
      await client.mutation({
        updateTask: {
          __args: { id: recordId, data: { exported: true } },
          id: true,
        },
      });
    }

    await enqueueSnackbar({
      message: `Exported ${selectedRecordIds.length} records`,
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Export {selectedRecordIds.length} selected record(s)?</p>
      <button onClick={handleExport}>Export</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
  name: 'bulk-export',
  description: 'Export selected records',
  component: BulkExport,
});

Bunu, kayıt seçimleriyle sınırlandırılmış bir komut menüsü öğesi ile sunun:

src/command-menu-items/bulk-export.command-menu-item.ts

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

export default defineCommandMenuItem({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
  label: 'Bulk Export',
  availabilityType: 'RECORD_SELECTION',
  frontComponentUniversalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
});

Genel varlıklar

Ön uç bileşenleri, getPublicAssetUrl kullanarak uygulamanın public/ dizinindeki dosyalara erişebilir:

import { defineFrontComponent } from 'twenty-sdk/define';
import { getPublicAssetUrl } from 'twenty-sdk/utils';

const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'logo',
  component: Logo,
});

Ayrıntılar için genel varlıklar bölümüne bakın.

Stil

Ön uç bileşenleri birden fazla biçimlendirme yaklaşımını destekler. Şunları kullanabilirsiniz:

Satır içi stiller — style={{ color: 'red' }}
Twenty UI bileşenleri — Twenty’nin kendi bileşen kitaplığı; aşağıda Twenty UI bileşenlerini kullanma bölümüne bakın
Emotion — @emotion/react ile CSS-in-JS
Styled-components — styled.div kalıpları
Tailwind CSS — yardımcı sınıflar
React ile uyumlu herhangi bir CSS-in-JS kitaplığı

Twenty UI bileşenlerini kullanma

Twenty, bileşen kitaplığını twenty-ui paketi olarak sunar. Ön uç bileşenleri bunu, çalışma alanının açık ve koyu temasıyla otomatik olarak eşleşen düğmeler, etiketler, durum rozetleri, çipler, avatarlar, simgeler, tipografi ve tema belirteçleri için kullanabilir.

Kurulum

Paketi, Twenty örneğinizle birlikte gelen sürüme sabitleyerek uygulamanıza ekleyin:

yarn add twenty-ui@1.0.0-alpha.1

twenty-ui, derleme zamanında ön uç bileşeninize paketlenir, bu nedenle yalnızca uygulamanızın bir bağımlılığı olması gerekir — çalışma zamanında yapılandırmanız gereken hiçbir şey yoktur.

Bileşenleri içe aktarma

Kullandığınız bileşenlerin yalnızca paketinizde yer alması için, paket kökü yerine eşleşen alt yoldan içe aktarın:

Alt yol	Dışa aktardıkları
`twenty-ui/input`	`Button` ve form girdileri
`twenty-ui/data-display`	`Tag`, `Status`, `Chip`, `Avatar` ve daha fazlası
`twenty-ui/feedback`	`Callout`, `Banner`, `Info` ve daha fazlası
`twenty-ui/typography`	`H1Title`, `H2Title`, `H3Title`, `Label` ve daha fazlası
`twenty-ui/icon`	`Icon*` bileşenleri (ör. `IconCheck`)
`twenty-ui/theme-constants`	`ThemeProvider`, `themeCssVariables`

import { defineFrontComponent } from 'twenty-sdk/define';
import { Status, Tag } from 'twenty-ui/data-display';
import { Button } from 'twenty-ui/input';

const StyledWidget = () => {
  return (
    <div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
      <Button title="Click me" onClick={() => alert('Clicked!')} />
      <Tag text="Active" color="green" />
      <Status color="green" text="Online" />
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
  name: 'styled-widget',
  component: StyledWidget,
});

İkonlar

Tek tek simgeleri twenty-ui/icon içinden içe aktarın:

import { IconBox, IconCheck } from 'twenty-ui/icon';

Her adlandırılmış simge ağaç sallama optimizasyonuna tabidir; bu nedenle birkaç tanesini içe aktarmak paket boyutunuza çok az şey ekler. IconsProvider, useIcons ve iconsState kullanmaktan kaçının — bunlar, birkaç MB’lık Tabler simge setinin tamamını içeri çeker.

Temalandırma ve tema belirteçleri

Twenty UI bileşenleri, çalışma alanının açık ve koyu temasıyla otomatik olarak eşleşir — oluşturucu etkin renk şemasını barındırıcıda uygular ve bileşenler renklerini buna göre belirler. Kendi satır içi stillerinizde aynı tasarım belirteçlerini kullanmak için useTheme() kancasını çağırın. Bu kanca, etkin temaya bağlı Twenty tema belirteçlerini (boşluklandırma, renkler, köşe yarıçapları, yazı tipleri) döndürür; bileşeninizde ThemeProvider kurulumuna gerek yoktur:

import { useTheme } from 'twenty-ui/theme-constants';

const Card = () => {
  const theme = useTheme();

  return (
    <div
      style={{
        padding: theme.spacing[4],
        background: theme.background.secondary,
        color: theme.font.color.primary,
      }}
    >
      Themed card
    </div>
  );
};

useTheme() bir kanca olduğundan, belirteçleri bileşen gövdesinin içinde okursunuz; böylece değerler her zaman etkin temayı yansıtır. Aynı belirteç haritası, themeCssVariables sabiti olarak da dışa aktarılır; ancak ön uç bileşenlerinde useTheme() kullanmayı tercih edin — themeCssVariables öğesini dolaylı olarak kullanan modül düzeyinde bir sabit, uygulama manifesti çıkarılırken tanımsız olabilir. Etkin şemaya açıkça dallanmak için, twenty-sdk/front-component içindeki useColorScheme() ile okuyun; bu kanca 'light' veya 'dark' döndürür.

Mevcut sınırlamalar

Front bileşenleri aktif geliştirme aşamasındadır. Render etme, stil verme ve olayları işleme iyi çalışıyor. Render işleminin ötesine geçen her şey (bir öğeyi ölçmek, bir ref üzerinde bir DOM yöntemini çağırmak, ağacınızın dışına portal oluşturmak, tarayıcı depolamasına erişmek) bugün eksik ya da tamamlanmamış durumda ve çoğu sessizce başarısız olur: ne bir istisna fırlatılır ne de TypeScript hatası görülür; çünkü iskeletin türleri tam tarayıcı DOM’una göre tanımlanmıştır. Bunlardan biri sizi engelliyorsa, önceliklendirilmesi için bir issue açın.

Yerleşim ve ölçüm

Henüz hiçbir şey kendisini ölçemiyor.

API	Ne olur
`getBoundingClientRect()`, `getClientRects()`	Fırlatır
`offsetWidth`, `clientWidth`, `scrollWidth`, `offsetTop`, …	Sessizce `undefined`, bu yüzden `width ?? 0` `0` döner ve `width > 600` her zaman false olur
`ResizeObserver`, `IntersectionObserver`	`ReferenceError` (`typeof` kontrolleri çalışır)
`window.matchMedia()`, `window.getComputedStyle()`	Fırlatır
`window.innerWidth`, `innerHeight`, `devicePixelRatio`	Sessizce `undefined`
`new MutationObserver(fn)`	Oluşturulur, ardından `.observe()` fırlatır

Bu nedenle recharts ResponsiveContainer, Floating UI / Popper, liste sanallaştırma ve sürükleyerek yeniden boyutlandırma henüz çalışmıyor. Bunun yerine yerleşimi CSS ile yapın: stil sayfanız gerçek sayfaya erişir, bu nedenle flexbox, grid, aspect-ratio, clamp() ve @container normal şekilde davranır.

requestAnimationFrame, fetch, setTimeout ve queueMicrotask window. öneki olmadan çalışır. Yalnızca window.requestAnimationFrame(...) ve benzerleri fırlatır.

DOM erişimi

Bir ref size bir HTMLElement değil, bir sandbox öğesi verir.

Ne yazarsınız	Ne olur	Bunun yerine şunu kullanın
`ref.current.focus()`, `.click()`, `.select()`, `.setSelectionRange()`, `.scrollIntoView()`, `video.play()`	Fırlatır	Kontrollü bileşenler; değerleri `event.target` üzerinden okuyun
`element.classList.add(...)`	Fırlatır (`classList` `undefined` durumundadır)	`className` dizgisini kendiniz oluşturun
`document.getElementById()`, `getElementsByClassName()`, `createTreeWalker()`	Fırlatır	Çalışan `querySelector()` / `querySelectorAll()`
`document.activeElement`	Her zaman `undefined`	Odağı `onFocus` / `onBlur` ile takip edin
`\<canvas>`	Hiçbir şey render etmez, hata yoktur	SVG kullanın veya ekranda olmayan bir alana çizip bir `<img src={dataUrl}>` ile gösterin
`createPortal(node, document.body)`	`isConnected` başarı bildirmesine rağmen hiçbir şey render etmez	`position: absolute` ile satır içi yerleştirilmiş bindirmeler veya kitaplığa kendi konteyner öğenizi iletin

Portal boşluğu, Radix, Headless UI, MUI ve react-select popover’larının varsayılan olarak hiçbir şey render etmemesinin nedenidir. Çoğu bir container prop kabul eder; onu render ettiğiniz bir öğeye yönlendirin.

Etkinlikler

Mouse, pointer, touch, sürükleme, klavye, odak, input/change/submit, scroll/wheel/contextmenu ve animationend/transitionend ana bilgisayara iletilir, ayrıca birkaç tane de öğe başına vardır: <img> üzerinde load/error, <input>/\<textarea> üzerinde panoya ve bileşime ilişkin olaylar, \<video>/\<audio> üzerinde medya, \<details>/\<dialog> üzerinde toggle. Bunun dışındaki her şey (onAuxClick, onSelect, onInvalid, onReset, onAnimationStart, pointer capture, <img> üzerinde onLoad) uyarı verilmeden kaldırılır. document.addEventListener() ve window.addEventListener() hatasız olarak kaydolur ancak asla tetiklenmez; bu yüzden bir sürükleme, işaretçi başladığı öğeden ayrılır ayrılmaz durur. event.preventDefault() da geçmez; form gönderimi, dragover/drop ve bağlantı tıklamaları zaten sizin için korunmuştur.

Öznitelikler ve stillendirme

Her öğe, kendi özelliklerini host DOM’a iletir (\<a> üzerinde href, <img> üzerinde src/alt, <input> üzerinde value/placeholder/disabled vb.), ayrıca her öğede ortak bir küme vardır: id, className, style, title, tabIndex, role, draggable ve tireli olan tüm aria-* / data-* öznitelikleri (bu yüzden ariaLabel düşürülür). Bunun dışındaki her şey sessizce atılır, bu yüzden özel durumu data-* olarak ifade edin. Bileşen CSS’i, ister import './styles.css' ile, ister CSS-in-JS ile ya da bir \<style> öğesinden gelsin, host sayfanın \<head> kısmına scope’suz olarak enjekte edilir. Bu nedenle sınıf adları Twenty’nin kendi sınıf adlarıyla çakışır (onlara önek ekleyin ve asla çıplak div { ... } seçicileri yazmayın) ve @media, sizin bileşeniniz yerine tarayıcı penceresini hedefler (kendi container-type değerinizle @container kullanın). Satır içi style prop’ları etkilenmez.

Depolama ve ağ

localStorage, sessionStorage, IndexedDB, çerezler, Cache API ve BroadcastChannel’ın tümü kullanılamaz, çünkü bileşen opak bir origin’e sahip bir worker içinde çalışır. Durumu kalıcı hale getirmek için bir mantık fonksiyonu çağırın ve onun anahtar-değer deposunu kullanın. fetch çalışır, bazı sınırlamalarla:

Twenty API’sine ve uygulamanızın rotalarına yapılan çağrılar host tarafından proxy’lenir, bu yüzden RestApiClient kullanmayı tercih edin. Proxy’lenen çağrılarda AbortSignal ve diğer RequestInit seçenekleri kaldırılır ve yalnızca string ve URLSearchParams gövdeleri desteklenir.
Diğer origin’ler sandbox’tan Origin: null ile çıkar, bu yüzden üçüncü taraf bir API yalnızca Access-Control-Allow-Origin: * gönderirse yanıt verir. Bunun yerine onu bir mantık fonksiyonundan çağırın.
fetch('/rest/people') hiçbir zaman Twenty API’siyle eşleştirilmez, çünkü sandbox’un göreli yolu çözecek bir sayfa URL’si yoktur.

Diğer eksikler

Dosya içerikleri. <input type="file"> handler’ınıza yalnızca dosya meta verilerini verir, baytları vermez, bu yüzden FileReader ve yüklemeler henüz mümkün değildir.
Sürükle-bırak yükleri. Sürükleme olayları tetiklenir, ancak event.dataTransfer undefined durumundadır.
Node yerleşikleri. fs, path ve node:crypto build aşamasında başarısız olur; bu nedenle bu işi bir mantık fonksiyonuna taşıyın. Web Crypto, fetch, TextEncoder ve URL kullanılabilir durumdadır.
\<iframe> her zaman allow-same-origin olmadan yeniden sandbox’a alınır, bu nedenle kendi oturumuna güvenen bir yerleştirme, oturum kapalı olarak işlenir. onLoad’u da yoktur.

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

Ön uç bileşenlerinin kullanılabileceği yerler

Basit örnek

Yapılandırma alanları

Bir ön uç bileşenini bir sayfaya yerleştirme

Özel ayarlar bileşeni

Headless ve headless olmayan

SDK Command bileşenleri

Bir mantık işlevini çağırma

Twenty REST API’sini çağırma

Çalışma zamanı bağlamına erişme

Uygulama değişkenleri

`TWENTY_FUNCTIONS_URL`

Host iletişim API’si

Birden çok kayıtla çalışma

Genel varlıklar

Stil

Twenty UI bileşenlerini kullanma

Kurulum

Bileşenleri içe aktarma

İkonlar

Temalandırma ve tema belirteçleri

Mevcut sınırlamalar

Yerleşim ve ölçüm

DOM erişimi

Etkinlikler

Öznitelikler ve stillendirme

Depolama ve ağ

Diğer eksikler

​Ön uç bileşenlerinin kullanılabileceği yerler

​Basit örnek

​Yapılandırma alanları

​Bir ön uç bileşenini bir sayfaya yerleştirme

​Özel ayarlar bileşeni

​Headless ve headless olmayan

​SDK Command bileşenleri

​Bir mantık işlevini çağırma

​Twenty REST API’sini çağırma

​Çalışma zamanı bağlamına erişme

​Uygulama değişkenleri

​TWENTY_FUNCTIONS_URL

​Host iletişim API’si

​Birden çok kayıtla çalışma

​Genel varlıklar

​Stil

​Twenty UI bileşenlerini kullanma

​Kurulum

​Bileşenleri içe aktarma

​İkonlar

​Temalandırma ve tema belirteçleri

​Mevcut sınırlamalar

​Yerleşim ve ölçüm

​DOM erişimi

​Etkinlikler

​Öznitelikler ve stillendirme

​Depolama ve ağ

​Diğer eksikler

Ön uç bileşenlerinin kullanılabileceği yerler

Basit örnek

Yapılandırma alanları

Bir ön uç bileşenini bir sayfaya yerleştirme

Özel ayarlar bileşeni

Headless ve headless olmayan

SDK Command bileşenleri

Bir mantık işlevini çağırma

Twenty REST API’sini çağırma

Çalışma zamanı bağlamına erişme

Uygulama değişkenleri

`TWENTY_FUNCTIONS_URL`

Host iletişim API’si

Birden çok kayıtla çalışma

Genel varlıklar

Stil

Twenty UI bileşenlerini kullanma

Kurulum

Bileşenleri içe aktarma

İkonlar

Temalandırma ve tema belirteçleri

Mevcut sınırlamalar

Yerleşim ve ölçüm

DOM erişimi

Etkinlikler

Öznitelikler ve stillendirme

Depolama ve ağ

Diğer eksikler