From c8c587ba2cb75e32c712d74181b3e2fbe075ae9a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 20:31:17 +0200 Subject: [PATCH] i18n - docs translations (#22865) Created by Github action Review in cubic Co-authored-by: github-actions --- packages/twenty-docs/docs.json | 12 ++ .../extend/apps/data/system-fields.mdx | 104 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 107 ++++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 106 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 107 ++++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 106 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 106 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 101 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 103 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 107 ++++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 107 ++++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 104 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- .../extend/apps/data/system-fields.mdx | 105 +++++++++++++++++ .../developers/extend/apps/layout/views.mdx | 2 +- 25 files changed, 1287 insertions(+), 12 deletions(-) create mode 100644 packages/twenty-docs/l/ar/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/cs/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/de/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/es/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/fr/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/it/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/ja/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/ko/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/pt/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/ro/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx create mode 100644 packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx diff --git a/packages/twenty-docs/docs.json b/packages/twenty-docs/docs.json index 9e1856c115..e7c2805f8f 100644 --- a/packages/twenty-docs/docs.json +++ b/packages/twenty-docs/docs.json @@ -866,6 +866,7 @@ "l/fr/developers/extend/apps/data/overview", "l/fr/developers/extend/apps/data/objects", "l/fr/developers/extend/apps/data/extending-objects", + "l/fr/developers/extend/apps/data/system-fields", "l/fr/developers/extend/apps/data/relations" ] }, @@ -1318,6 +1319,7 @@ "l/ar/developers/extend/apps/data/overview", "l/ar/developers/extend/apps/data/objects", "l/ar/developers/extend/apps/data/extending-objects", + "l/ar/developers/extend/apps/data/system-fields", "l/ar/developers/extend/apps/data/relations" ] }, @@ -1770,6 +1772,7 @@ "l/cs/developers/extend/apps/data/overview", "l/cs/developers/extend/apps/data/objects", "l/cs/developers/extend/apps/data/extending-objects", + "l/cs/developers/extend/apps/data/system-fields", "l/cs/developers/extend/apps/data/relations" ] }, @@ -2222,6 +2225,7 @@ "l/de/developers/extend/apps/data/overview", "l/de/developers/extend/apps/data/objects", "l/de/developers/extend/apps/data/extending-objects", + "l/de/developers/extend/apps/data/system-fields", "l/de/developers/extend/apps/data/relations" ] }, @@ -2674,6 +2678,7 @@ "l/es/developers/extend/apps/data/overview", "l/es/developers/extend/apps/data/objects", "l/es/developers/extend/apps/data/extending-objects", + "l/es/developers/extend/apps/data/system-fields", "l/es/developers/extend/apps/data/relations" ] }, @@ -3126,6 +3131,7 @@ "l/it/developers/extend/apps/data/overview", "l/it/developers/extend/apps/data/objects", "l/it/developers/extend/apps/data/extending-objects", + "l/it/developers/extend/apps/data/system-fields", "l/it/developers/extend/apps/data/relations" ] }, @@ -3578,6 +3584,7 @@ "l/ja/developers/extend/apps/data/overview", "l/ja/developers/extend/apps/data/objects", "l/ja/developers/extend/apps/data/extending-objects", + "l/ja/developers/extend/apps/data/system-fields", "l/ja/developers/extend/apps/data/relations" ] }, @@ -4030,6 +4037,7 @@ "l/ko/developers/extend/apps/data/overview", "l/ko/developers/extend/apps/data/objects", "l/ko/developers/extend/apps/data/extending-objects", + "l/ko/developers/extend/apps/data/system-fields", "l/ko/developers/extend/apps/data/relations" ] }, @@ -4482,6 +4490,7 @@ "l/pt/developers/extend/apps/data/overview", "l/pt/developers/extend/apps/data/objects", "l/pt/developers/extend/apps/data/extending-objects", + "l/pt/developers/extend/apps/data/system-fields", "l/pt/developers/extend/apps/data/relations" ] }, @@ -4934,6 +4943,7 @@ "l/ro/developers/extend/apps/data/overview", "l/ro/developers/extend/apps/data/objects", "l/ro/developers/extend/apps/data/extending-objects", + "l/ro/developers/extend/apps/data/system-fields", "l/ro/developers/extend/apps/data/relations" ] }, @@ -5820,6 +5830,7 @@ "l/tr/developers/extend/apps/data/overview", "l/tr/developers/extend/apps/data/objects", "l/tr/developers/extend/apps/data/extending-objects", + "l/tr/developers/extend/apps/data/system-fields", "l/tr/developers/extend/apps/data/relations" ] }, @@ -6272,6 +6283,7 @@ "l/zh/developers/extend/apps/data/overview", "l/zh/developers/extend/apps/data/objects", "l/zh/developers/extend/apps/data/extending-objects", + "l/zh/developers/extend/apps/data/system-fields", "l/zh/developers/extend/apps/data/relations" ] }, diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..2789819214 --- /dev/null +++ b/packages/twenty-docs/l/ar/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,104 @@ +--- +title: استهداف الحقول النظامية +description: استدعِ الحقول النظامية التي يتم إنشاؤها تلقائيًا مثل `createdAt` أو `updatedAt` من العروض والكائنات الأخرى باستخدام `getFieldUniversalIdentifier`. +icon: gears +--- + +كل كائن في Twenty يأتي مع مجموعة من **الحقول النظامية** التي لا تقوم بتعريفها بنفسك أبدًا. يتم إنشاؤها تلقائيًا بواسطة الخادم عندما يتم توفير الكائن: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +نظرًا لأنك لا تعرّف هذه الحقول باستخدام [`defineField()`](/l/ar/developers/extend/apps/data/extending-objects)، فلا يوجد ثابت `universalIdentifier` لتقوم باستيراده. فكيف تُشير إلى `createdAt` كعمود في [عرض](/l/ar/developers/extend/apps/layout/views)؟ + +## المشكلة + +منذ Twenty 2.19، يتم اشتقاق المعرّف الشامل للحقل النظامي **بشكل حتمي** بواسطة الخادم من ثلاثة مُدخلات: المعرّف الشامل للتطبيق، والمعرّف الشامل للكائن، واسم الحقل. ابتكار معرّف (id) وتضمينه بشكل ثابت لن ينجح: لن يطابق أي شيء على الخادم، وسترفض المزامنة المرجع المعلّق: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## الحل + + + يتوفر `getFieldUniversalIdentifier` في `twenty-sdk` بدءًا من الإصدار 2.21 فصاعدًا. + + +استخدم `getFieldUniversalIdentifier` لاشتقاق نفس القيمة تمامًا التي يستخدمها الخادم. يأخذ المُدخلات الثلاثة ويُرجِع المعرّف الشامل للحقل: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` هو معرّف تطبيقك، وهو نفسه الذي تمرّره إلى [`defineApplication()`](/l/ar/developers/extend/apps/config/application). +* `objectUniversalIdentifier` هو معرّف الكائن الذي ينتمي إليه الحقل. +* `name` هو اسم الحقل النظامي، وهو إحدى القيم المُدرجة أعلاه. + +## مثال: عمود `createdAt` في عرض + +الحالة النموذجية هي إضافة عمود `createdAt` إلى عرض لأحد الكائنات المخصّصة لديك. اشتقّ معرّف الحقل واستدعِه كما تستدعي أي `fieldMetadataUniversalIdentifier` آخر: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +المعرّف المُشتقّ نفسه يعمل في أي مكان يُتوقَّع فيه `fieldMetadataUniversalIdentifier`: حقول العرض، عوامل التصفية، أوامر الفرز، المجموعات، وعناصر واجهة تخطيط الصفحة. + + + اشتقّ المعرّف، ولا تقُم بتضمينه بشكل ثابت. نظرًا لأن الخادم يشتق القيمة من معرّف التطبيق، ومعرّف الكائن، واسم الحقل، فإن استدعاء + `getFieldUniversalIdentifier` يُبقي مرجعك صحيحًا حتى إذا تغيّرت تلك المُدخلات، ويتجنّب الانحراف إذا تطوّر أسلوب الاشتقاق في أي وقت. + + +## الكائنات القياسية في Twenty + +بالنسبة إلى كائن Twenty **قياسي** (Person، Company، Opportunity، …)، لا تحتاج إلى اشتقاق أي شيء: فمعرّفات الحقول النظامية هي ثوابت مُسبقة الحساب يمكنك استيرادها مباشرة. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +الجأ إلى `getFieldUniversalIdentifier` عندما يكون الكائن واحدًا مما يعرّفه تطبيقك باستخدام [`defineObject()`](/l/ar/developers/extend/apps/data/objects)، حيث لا يوجد مثل هذا الثابت. + + + `name` حقل **افتراضي**، وليس حقلًا نظاميًا. يحتفظ بمعرّفه الشامل الثابت الخاص به ولا يتم اشتقاقه عبر + `getFieldUniversalIdentifier`. في الكائنات التي تعرّفها، استدعِ حقل + `name` باستخدام المعرّف الذي منحته له في `defineObject()`. + diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/layout/views.mdx index aa53ce820e..fd9f45cc5b 100644 --- a/packages/twenty-docs/l/ar/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/ar/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` يحدّد الكائن الذي ينطبق عليه هذا العرض. يمكن أن يكون كائنًا مخصصًا قمتَ بتعريفه أو كائن Twenty قياسيًا. * `key: ViewKey.INDEX` يحدد العرض بوصفه عرض القائمة الرئيسي للكائن (ذلك الذي يفتحه عنصر التنقل `OBJECT`). -* يتحكّم `fields` في الأعمدة التي تظهر وترتيبها. يشير كل حقل إلى `fieldMetadataUniversalIdentifier`. +* يتحكّم `fields` في الأعمدة التي تظهر وترتيبها. يشير كل حقل إلى `fieldMetadataUniversalIdentifier`. للإشارة إلى حقل نظام يتم إنشاؤه تلقائيًا مثل `createdAt`، راجع قسم [استهداف حقول النظام](/l/ar/developers/extend/apps/data/system-fields). * يمكنك أيضًا تعريف `filters` و`filterGroups` و`sorts` و`groups` و`fieldGroups` لتكوينات أكثر تقدمًا. * يتحكّم `position` في الترتيب عند وجود عدة عروض لنفس الكائن. diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..ce86e293ec --- /dev/null +++ b/packages/twenty-docs/l/cs/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,107 @@ +--- +title: Cílení na systémová pole +description: Odkazujte na automaticky vytvářená systémová pole, jako jsou createdAt nebo updatedAt, ve zobrazeních a dalších entitách pomocí getFieldUniversalIdentifier. +icon: gears +--- + +Každý objekt v Twenty je dodáván se sadou **systémových polí**, která sami nikdy nedefinujete. Tato pole jsou automaticky vytvářena serverem při zřízení objektu: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Protože tato pole nedefinujete pomocí [`defineField()`](/l/cs/developers/extend/apps/data/extending-objects), neexistuje žádná konstanta `universalIdentifier`, kterou byste mohli importovat. Jak tedy odkážete na `createdAt` jako na sloupec ve [zobrazení](/l/cs/developers/extend/apps/layout/views)? + +## Problém + +Od Twenty 2.19 je univerzální identifikátor systémového pole **deterministicky odvozován** serverem ze tří vstupů: univerzálního identifikátoru aplikace, univerzálního identifikátoru objektu a názvu pole. Vymyslet si id a natvrdo ho zapsat nebude fungovat: neshoduje se s ničím na serveru a synchronizace zamítne osiřelý odkaz: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## Řešení + + + `getFieldUniversalIdentifier` je k dispozici od `twenty-sdk` verze 2.21 a vyšší. + + +Použijte `getFieldUniversalIdentifier` k odvození přesně stejné hodnoty, jakou používá server. Funkce přijímá tři vstupy a vrací univerzální identifikátor pole: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` je identifikátor vaší aplikace, ten, který předáváte do [`defineApplication()`](/l/cs/developers/extend/apps/config/application). +* `objectUniversalIdentifier` je identifikátor objektu, ke kterému pole patří. +* `name` je název systémového pole, jedna z výše uvedených hodnot. + +## Příklad: sloupec createdAt v zobrazení + +Typickým případem je přidání sloupce `createdAt` do zobrazení některého z vašich vlastních objektů. Odvoďte identifikátor pole a odkažte na něj stejně jako na jakýkoli jiný `fieldMetadataUniversalIdentifier`: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +Tentýž odvozený identifikátor funguje všude tam, kde se očekává `fieldMetadataUniversalIdentifier`: pole zobrazení, filtry, řazení, seskupování a widgety rozložení stránky. + + + Identifikátor odvozujte, neukládejte ho natvrdo. Protože server odvozuje hodnotu z + ID aplikace, ID objektu a názvu pole, volání + `getFieldUniversalIdentifier` udržuje odkaz správný i v případě, že se tyto + vstupy změní, a předchází odchylkám, pokud se samotný způsob odvozování někdy změní. + + +## Standardní objekty Twenty + +U **standardního** objektu Twenty (Person, Company, Opportunity, …) nemusíte nic odvozovat: identifikátory systémových polí jsou předpočítané konstanty, které můžete přímo importovat. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Použijte `getFieldUniversalIdentifier` v případě, kdy je objekt definován **vaší aplikací** pomocí [`defineObject()`](/l/cs/developers/extend/apps/data/objects) a žádná taková konstanta neexistuje. + + + `name` je **výchozí** pole, nikoli systémové pole. Má svůj vlastní natvrdo daný + univerzální identifikátor a neodvozuje se pomocí + `getFieldUniversalIdentifier`. U objektů, které definujete, odkazujte na pole + `name` pomocí identifikátoru, který jste mu dali v `defineObject()`. + diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/layout/views.mdx index 0aca4c219d..a0051abf2d 100644 --- a/packages/twenty-docs/l/cs/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/cs/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` určuje, na který objekt se toto zobrazení vztahuje. Může to být vlastní objekt, který jste definovali, nebo standardní objekt Twenty. * `key: ViewKey.INDEX` označuje zobrazení jako hlavní seznamové zobrazení objektu (to, které se otevře po kliknutí na navigační položku `OBJECT`). -* `fields` určuje, které sloupce se zobrazí a v jakém pořadí. Každé pole odkazuje na `fieldMetadataUniversalIdentifier`. +* `fields` určuje, které sloupce se zobrazí a v jakém pořadí. Každé pole odkazuje na `fieldMetadataUniversalIdentifier`. Chcete-li odkazovat na automaticky vytvořené systémové pole, například `createdAt`, podívejte se na [Cílení na systémová pole](/l/cs/developers/extend/apps/data/system-fields). * Pro pokročilé konfigurace můžete také deklarovat `filters`, `filterGroups`, `sorts`, `groups` a `fieldGroups`. * `position` určuje pořadí, pokud pro stejný objekt existuje více zobrazení. diff --git a/packages/twenty-docs/l/de/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/de/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..e2fbd1772d --- /dev/null +++ b/packages/twenty-docs/l/de/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,106 @@ +--- +title: Systemfelder ansprechen +description: Referenzieren Sie automatisch erstellte Systemfelder wie createdAt oder updatedAt aus Ansichten und anderen Entitäten mit getFieldUniversalIdentifier. +icon: gears +--- + +Jedes Objekt in Twenty wird mit einem Satz von **Systemfeldern** ausgeliefert, die Sie nie selbst deklarieren. Sie werden automatisch vom Server erstellt, wenn das Objekt bereitgestellt wird: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Da Sie diese Felder nicht mit [`defineField()`](/l/de/developers/extend/apps/data/extending-objects) deklarieren, gibt es keine `universalIdentifier`-Konstante, die Sie importieren könnten. Wie referenzieren Sie also `createdAt` als Spalte in einer [Ansicht](/l/de/developers/extend/apps/layout/views)? + +## Das Problem + +Seit Twenty 2.19 wird die universelle Kennung eines Systemfelds **deterministisch abgeleitet** vom Server aus drei Eingaben: der universellen Kennung der Applikation, der universellen Kennung des Objekts und dem Feldnamen. Sich eine ID auszudenken und sie hart zu codieren, funktioniert nicht: Sie stimmt mit nichts auf dem Server überein, und die Synchronisierung lehnt die lose Referenz ab: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## Die Lösung + + + `getFieldUniversalIdentifier` ist ab `twenty-sdk` 2.21 verfügbar. + + +Verwenden Sie `getFieldUniversalIdentifier`, um genau denselben Wert aufzulösen, den der Server verwendet. Die Funktion nimmt die drei Eingaben entgegen und gibt die universelle Kennung des Feldes zurück: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` ist die Kennung Ihrer App, diejenige, die Sie an [`defineApplication()`](/l/de/developers/extend/apps/config/application) übergeben. +* `objectUniversalIdentifier` ist die Kennung des Objekts, zu dem das Feld gehört. +* `name` ist der Name des Systemfelds, einer der oben aufgeführten Werte. + +## Beispiel: eine createdAt-Spalte in einer Ansicht + +Der typische Anwendungsfall ist das Hinzufügen einer `createdAt`-Spalte zu einer Ansicht eines Ihrer benutzerdefinierten Objekte. Lösen Sie die Feld-ID auf und referenzieren Sie sie wie jeden anderen `fieldMetadataUniversalIdentifier`: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +Dieselbe aufgelöste ID funktioniert überall dort, wo ein `fieldMetadataUniversalIdentifier` erwartet wird: Ansichtsfelder, Filter, Sortierungen, Gruppierungen und Page-Layout-Widgets. + + + Lösen Sie die ID auf, statt sie hart zu codieren. Da der Server den Wert aus der Applikations-ID, der Objekt-ID und dem Feldnamen ableitet, hält ein Aufruf von + `getFieldUniversalIdentifier` Ihre Referenz korrekt, selbst wenn sich diese + Eingaben ändern, und verhindert Abweichungen, falls sich die Ableitung jemals weiterentwickelt. + + +## Standardobjekte von Twenty + +Für ein **Standard**-Twenty-Objekt (Person, Company, Opportunity, …) müssen Sie nichts ableiten: Die Systemfeld-Kennungen sind vorab berechnete Konstanten, die Sie direkt importieren können. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Greifen Sie zu `getFieldUniversalIdentifier`, wenn es sich um ein Objekt handelt, das **Ihre App** mit [`defineObject()`](/l/de/developers/extend/apps/data/objects) definiert, für das es keine solche Konstante gibt. + + + `name` ist ein **Standard**-Feld, kein Systemfeld. Es behält seine eigene hart codierte + universelle Kennung und wird nicht über + `getFieldUniversalIdentifier` aufgelöst. Für Objekte, die Sie definieren, referenzieren Sie das + `name`-Feld über die Kennung, die Sie ihm in `defineObject()` gegeben haben. + diff --git a/packages/twenty-docs/l/de/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/de/developers/extend/apps/layout/views.mdx index 25ed2f5fb7..89abd93aed 100644 --- a/packages/twenty-docs/l/de/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/de/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` gibt an, auf welches Objekt diese Ansicht angewendet wird. Es kann sich um ein von Ihnen definiertes benutzerdefiniertes Objekt oder ein Standardobjekt von Twenty handeln. * `key: ViewKey.INDEX` markiert die Ansicht als die Hauptlistenansicht des Objekts (diejenige, die von einem `OBJECT`-Navigationselement geöffnet wird). -* `fields` steuert, welche Spalten erscheinen und in welcher Reihenfolge. Jedes Feld referenziert einen `fieldMetadataUniversalIdentifier`. +* `fields` steuert, welche Spalten erscheinen und in welcher Reihenfolge. Jedes Feld referenziert einen `fieldMetadataUniversalIdentifier`. Informationen zum Verweisen auf ein automatisch erstelltes Systemfeld wie `createdAt` finden Sie unter [Systemfelder ansteuern](/l/de/developers/extend/apps/data/system-fields). * Für erweiterte Konfigurationen können Sie außerdem `filters`, `filterGroups`, `sorts`, `groups` und `fieldGroups` deklarieren. * `position` steuert die Reihenfolge, wenn mehrere Ansichten für dasselbe Objekt existieren. diff --git a/packages/twenty-docs/l/es/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/es/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..9b1af9c647 --- /dev/null +++ b/packages/twenty-docs/l/es/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,107 @@ +--- +title: Apuntar a campos de sistema +description: Haz referencia a los campos de sistema creados automáticamente, como createdAt o updatedAt, desde vistas y otras entidades con getFieldUniversalIdentifier. +icon: gears +--- + +Cada objeto en Twenty viene con un conjunto de **campos de sistema** que nunca declaras tú mismo. Los crea automáticamente el servidor cuando se aprovisiona el objeto: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Como no declaras estos campos con [`defineField()`](/l/es/developers/extend/apps/data/extending-objects), no hay ninguna constante `universalIdentifier` que puedas importar. Entonces, ¿cómo haces referencia a `createdAt` como una columna en una [vista](/l/es/developers/extend/apps/layout/views)? + +## Problema + +Desde Twenty 2.19, el identificador universal de un campo de sistema se **deriva de forma determinista** en el servidor a partir de tres entradas: el identificador universal de la aplicación, el identificador universal del objeto y el nombre del campo. Inventar un id y ponerlo de forma fija en el código no funcionará: no coincide con nada en el servidor y la sincronización rechaza la referencia colgante: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## La solución + + + `getFieldUniversalIdentifier` está disponible a partir de `twenty-sdk` 2.21. + + +Usa `getFieldUniversalIdentifier` para resolver exactamente el mismo valor que utiliza el servidor. Toma las tres entradas y devuelve el identificador universal del campo: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` es el identificador de tu aplicación, el que pasas a [`defineApplication()`](/l/es/developers/extend/apps/config/application). +* `objectUniversalIdentifier` es el identificador del objeto al que pertenece el campo. +* `name` es el nombre del campo de sistema, uno de los valores enumerados arriba. + +## Ejemplo: una columna createdAt en una vista + +El caso típico es añadir una columna `createdAt` a una vista de uno de tus objetos personalizados. Resuelve el id del campo y haz referencia a él como a cualquier otro `fieldMetadataUniversalIdentifier`: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +El mismo id resuelto funciona en cualquier lugar donde se espere un `fieldMetadataUniversalIdentifier`: campos de vista, filtros, ordenaciones, agrupaciones y widgets de diseño de página. + + + Resuelve el id, no lo pongas de forma fija en el código. Como el servidor deriva el valor a partir + del id de la aplicación, el id del objeto y el nombre del campo, llamar a + `getFieldUniversalIdentifier` mantiene tu referencia correcta incluso si esas + entradas cambian, y evita desviaciones si la derivación evoluciona en algún momento. + + +## Objetos estándar de Twenty + +Para un objeto **estándar** de Twenty (Persona, Compañía, Oportunidad, …), no necesitas derivar nada: los identificadores de los campos de sistema son constantes precalculadas que puedes importar directamente. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Recurre a `getFieldUniversalIdentifier` cuando el objeto es uno que **tu aplicación** define con [`defineObject()`](/l/es/developers/extend/apps/data/objects), donde no existe tal constante. + + + `name` es un campo **predeterminado**, no un campo de sistema. Conserva su propio identificador universal fijo + y no se resuelve mediante + `getFieldUniversalIdentifier`. En los objetos que defines, haz referencia al campo + `name` mediante el identificador que le diste en `defineObject()`. + diff --git a/packages/twenty-docs/l/es/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/es/developers/extend/apps/layout/views.mdx index cc2033ff1b..345937a109 100644 --- a/packages/twenty-docs/l/es/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/es/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` especifica a qué objeto se aplica esta vista. Puede ser un objeto personalizado que hayas definido o un objeto estándar de Twenty. * `key: ViewKey.INDEX` marca la vista como la vista de lista principal del objeto (la que abre un elemento de navegación `OBJECT`). -* `fields` controla qué columnas aparecen y en qué orden. Cada campo referencia un `fieldMetadataUniversalIdentifier`. +* `fields` controla qué columnas aparecen y en qué orden. Cada campo referencia un `fieldMetadataUniversalIdentifier`. Para hacer referencia a un campo del sistema creado automáticamente, como `createdAt`, consulta [Referencia a campos del sistema](/l/es/developers/extend/apps/data/system-fields). * También puedes definir `filters`, `filterGroups`, `sorts`, `groups` y `fieldGroups` para configuraciones avanzadas. * `position` controla el orden cuando existen múltiples vistas para el mismo objeto. diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..7f6e4863b1 --- /dev/null +++ b/packages/twenty-docs/l/fr/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,106 @@ +--- +title: Ciblage des champs système +description: Faites référence aux champs système auto-créés comme createdAt ou updatedAt à partir des vues et d'autres entités avec getFieldUniversalIdentifier. +icon: gears +--- + +Chaque objet dans Twenty est livré avec un ensemble de **champs système** que vous ne déclarez jamais vous-même. Ils sont créés automatiquement par le serveur lorsque l'objet est provisionné : + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Comme vous ne déclarez pas ces champs avec [`defineField()`](/l/fr/developers/extend/apps/data/extending-objects), il n'existe pas de constante `universalIdentifier` que vous puissiez importer. Alors, comment référencer `createdAt` en tant que colonne dans une [vue](/l/fr/developers/extend/apps/layout/views) ? + +## Le problème + +Depuis Twenty 2.19, l'identifiant universel d'un champ système est **dérivé de manière déterministe** par le serveur à partir de trois entrées : l'identifiant universel de l'application, l'identifiant universel de l'objet et le nom du champ. Inventer un id et le coder en dur ne fonctionnera pas : il ne correspond à rien sur le serveur, et la synchronisation rejette la référence orpheline : + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## La solution + + + `getFieldUniversalIdentifier` est disponible à partir de `twenty-sdk` 2.21. + + +Utilisez `getFieldUniversalIdentifier` pour résoudre exactement la même valeur que celle utilisée par le serveur. Elle prend les trois entrées et renvoie l'identifiant universel du champ : + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` est l'identifiant de votre application, celui que vous transmettez à [`defineApplication()`](/l/fr/developers/extend/apps/config/application). +* `objectUniversalIdentifier` est l'identifiant de l'objet auquel le champ appartient. +* `name` est le nom du champ système, l'une des valeurs listées ci-dessus. + +## Exemple : une colonne createdAt dans une vue + +Le cas typique consiste à ajouter une colonne `createdAt` à une vue de l'un de vos objets personnalisés. Résolvez l'id du champ et référencez-le comme n'importe quel autre `fieldMetadataUniversalIdentifier` : + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +Le même id résolu fonctionne partout où un `fieldMetadataUniversalIdentifier` est attendu : champs de vue, filtres, tris, regroupements et widgets de mise en page. + + + Résolvez l'id, ne le codez pas en dur. Parce que le serveur dérive la valeur à partir de + l'id de l'application, de l'id de l'objet et du nom du champ, appeler + `getFieldUniversalIdentifier` garde votre référence correcte même si ces + entrées changent, et évite les divergences si la dérivation évolue un jour. + + +## Objets standard de Twenty + +Pour un objet Twenty **standard** (Person, Company, Opportunity, …), vous n'avez rien à dériver : les identifiants des champs système sont des constantes pré-calculées que vous pouvez importer directement. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Utilisez `getFieldUniversalIdentifier` lorsque l'objet est l'un de ceux que **votre application** définit avec [`defineObject()`](/l/fr/developers/extend/apps/data/objects), et pour lesquels il n'existe pas une telle constante. + + + `name` est un champ **par défaut**, pas un champ système. Il conserve son propre identifiant universel codé en dur et n'est pas résolu via + `getFieldUniversalIdentifier`. Sur les objets que vous définissez, référencez le champ + `name` avec l'identifiant que vous lui avez donné dans `defineObject()`. + diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/layout/views.mdx index 2ee68472ad..f2a35c06af 100644 --- a/packages/twenty-docs/l/fr/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/fr/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` spécifie à quel objet cette vue s'applique. Il peut s’agir d’un objet personnalisé que vous avez défini ou d’un objet Twenty standard. * `key: ViewKey.INDEX` marque la vue comme la vue de liste principale de l’objet (celle qu’un élément de navigation `OBJECT` ouvre). -* `fields` contrôle les colonnes affichées et leur ordre. Chaque champ référence un `fieldMetadataUniversalIdentifier`. +* `fields` contrôle les colonnes affichées et leur ordre. Chaque champ référence un `fieldMetadataUniversalIdentifier`. Pour faire référence à un champ système créé automatiquement tel que `createdAt`, voir [Ciblage des champs système](/l/fr/developers/extend/apps/data/system-fields). * Vous pouvez également définir `filters`, `filterGroups`, `sorts`, `groups` et `fieldGroups` pour des configurations plus avancées. * `position` contrôle l’ordre lorsqu’il existe plusieurs vues pour le même objet. diff --git a/packages/twenty-docs/l/it/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/it/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..b12f0c1530 --- /dev/null +++ b/packages/twenty-docs/l/it/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,106 @@ +--- +title: Fare riferimento ai campi di sistema +description: Fai riferimento ai campi di sistema creati automaticamente, come createdAt o updatedAt, nelle viste e in altre entità con getFieldUniversalIdentifier. +icon: gears +--- + +Ogni oggetto in Twenty viene distribuito con un insieme di **campi di sistema** che non dichiari mai esplicitamente. Vengono creati automaticamente dal server quando viene effettuato il provisioning dell'oggetto: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Poiché non dichiari questi campi con [`defineField()`](/l/it/developers/extend/apps/data/extending-objects), non esiste alcuna costante `universalIdentifier` da importare. Quindi, come fai a fare riferimento a `createdAt` come colonna in una [vista](/l/it/developers/extend/apps/layout/views)? + +## Il problema + +A partire da Twenty 2.19, l'identificatore universale di un campo di sistema viene derivato in modo deterministico dal server sulla base di tre input: l'identificatore universale dell'applicazione, l'identificatore universale dell'oggetto e il nome del campo. Inventare un id e hardcodarlo non funziona: non corrisponde a nulla sul server e la sincronizzazione rifiuta il riferimento orfano: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## La soluzione + + + `getFieldUniversalIdentifier` è disponibile da `twenty-sdk` 2.21 in poi. + + +Usa `getFieldUniversalIdentifier` per ottenere esattamente lo stesso valore utilizzato dal server. Accetta i tre input e restituisce l'identificatore universale del campo: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` è l'identificatore della tua app, quello che passi a [`defineApplication()`](/l/it/developers/extend/apps/config/application). +* `objectUniversalIdentifier` è l'identificatore dell'oggetto a cui il campo appartiene. +* `name` è il nome del campo di sistema, uno dei valori elencati sopra. + +## Esempio: una colonna createdAt in una vista + +Il caso tipico è aggiungere una colonna `createdAt` a una vista di uno dei tuoi oggetti personalizzati. Risolvi l'id del campo e usalo come qualsiasi altro `fieldMetadataUniversalIdentifier`: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +Lo stesso id risolto funziona ovunque ci si aspetti un `fieldMetadataUniversalIdentifier`: campi di vista, filtri, ordinamenti, raggruppamenti e widget di layout di pagina. + + + Risolvi l'id, non hardcodarlo. Poiché il server deriva il valore + dall'id dell'applicazione, dall'id dell'oggetto e dal nome del campo, chiamare + `getFieldUniversalIdentifier` mantiene corretto il riferimento anche se questi + input cambiano ed evita discrepanze se la modalità di derivazione dovesse mai evolvere. + + +## Oggetti standard di Twenty + +Per un oggetto **standard** di Twenty (Person, Company, Opportunity, …), non hai bisogno di derivare nulla: gli identificatori dei campi di sistema sono costanti pre-calcolate che puoi importare direttamente. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Usa `getFieldUniversalIdentifier` quando l'oggetto è uno che **la tua app** definisce con [`defineObject()`](/l/it/developers/extend/apps/data/objects), per cui non esiste alcuna costante di questo tipo. + + + `name` è un campo **predefinito**, non un campo di sistema. Mantiene un proprio identificatore universale hardcoded e non viene risolto tramite + `getFieldUniversalIdentifier`. Sugli oggetti che definisci tu, fai riferimento al campo + `name` tramite l'identificatore che gli hai assegnato in `defineObject()`. + diff --git a/packages/twenty-docs/l/it/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/it/developers/extend/apps/layout/views.mdx index 7b8327401e..379287b545 100644 --- a/packages/twenty-docs/l/it/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/it/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` specifica a quale oggetto si applica questa vista. Può essere un oggetto personalizzato che hai definito o un oggetto Twenty standard. * `key: ViewKey.INDEX` contrassegna la vista come vista elenco principale dell'oggetto (quella che un elemento di navigazione `OBJECT` apre). -* `fields` controlla quali colonne compaiono e in quale ordine. Ogni campo fa riferimento a un `fieldMetadataUniversalIdentifier`. +* `fields` controlla quali colonne compaiono e in quale ordine. Ogni campo fa riferimento a un `fieldMetadataUniversalIdentifier`. Per fare riferimento a un campo di sistema creato automaticamente come `createdAt`, vedi [Targeting System Fields](/l/it/developers/extend/apps/data/system-fields). * Puoi anche definire `filters`, `filterGroups`, `sorts`, `groups` e `fieldGroups` per configurazioni più avanzate. * `position` controlla l'ordinamento quando esistono più viste per lo stesso oggetto. diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..bf361f3dbf --- /dev/null +++ b/packages/twenty-docs/l/ja/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,101 @@ +--- +title: システムフィールドのターゲット指定 +description: ビューやその他のエンティティから `createdAt` や `updatedAt` のような自動作成されるシステムフィールドを、`getFieldUniversalIdentifier` を使って参照します。 +icon: gears +--- + +Twenty のすべてのオブジェクトには、あなたが自分で宣言する必要のない **システムフィールド** のセットがあらかじめ用意されています。 これらは、オブジェクトがプロビジョニングされるときにサーバーによって自動的に作成されます。 + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +[`defineField()`](/l/ja/developers/extend/apps/data/extending-objects) でこれらのフィールドを宣言しないため、インポートできる `universalIdentifier` 定数は存在しません。 では、[view](/l/ja/developers/extend/apps/layout/views) で `createdAt` をカラムとしてどのように参照すればよいのでしょうか。 + +## 問題 + +Twenty 2.19 以降、システムフィールドのユニバーサル識別子は、アプリケーションのユニバーサル識別子、オブジェクトのユニバーサル識別子、およびフィールド名という 3 つの入力からサーバーによって **決定的に導出** されます。 id を独自に作成してハードコードしても機能しません。サーバー上のどの値とも一致せず、同期時にそのぶら下がった参照は拒否されます。 + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## 解決策 + + + `getFieldUniversalIdentifier` は `twenty-sdk` 2.21 以降で利用可能です。 + + +`getFieldUniversalIdentifier` を使用して、サーバーが使用するものとまったく同じ値を解決します。 この関数は 3 つの入力を受け取り、フィールドのユニバーサル識別子を返します。 + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` はあなたのアプリの識別子であり、[`defineApplication()`](/l/ja/developers/extend/apps/config/application) に渡すものです。 +* `objectUniversalIdentifier` は、そのフィールドが属するオブジェクトの識別子です。 +* `name` はシステムフィールド名であり、上に挙げた値のいずれかです。 + +## 例: ビュー内の createdAt カラム + +典型的なケースは、カスタムオブジェクトの 1 つのビューに `createdAt` カラムを追加することです。 フィールド id を解決し、他の `fieldMetadataUniversalIdentifier` と同様にそれを参照します。 + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +同じように解決された id は、`fieldMetadataUniversalIdentifier` が必要とされるあらゆる場所、すなわちビューのフィールド、フィルター、ソート、グループ、ページレイアウトウィジェットでそのまま使用できます。 + + + id は解決して、ハードコードしないでください。 サーバーはその値をアプリケーション id、オブジェクト id、フィールド名から導出するため、`getFieldUniversalIdentifier` を呼び出すことで、それらの入力が変更された場合でも参照を正しい状態に保ち、導出方法が将来変わった場合のずれも防ぐことができます。 + + +## 標準の Twenty オブジェクト + +**標準** の Twenty オブジェクト（Person、Company、Opportunity など）の場合、何も導出する必要はありません。システムフィールドの識別子はあらかじめ計算された定数として用意されており、直接インポートできます。 + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +[`defineObject()`](/l/ja/developers/extend/apps/data/objects) で **あなたのアプリ** が定義するオブジェクトのように、そのような定数が存在しない場合にこそ、`getFieldUniversalIdentifier` を使用してください。 + + + `name` はシステムフィールドではなく、**デフォルト** フィールドです。 このフィールドは独自のハードコードされたユニバーサル識別子を持ち、`getFieldUniversalIdentifier` で解決されることはありません。 あなたが定義したオブジェクトでは、`name` フィールドは `defineObject()` で与えた識別子で参照してください。 + diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/layout/views.mdx index e5d8347db9..c8b067a415 100644 --- a/packages/twenty-docs/l/ja/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/ja/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` は、このビューを適用するオブジェクトを指定します。 定義したカスタムオブジェクトでも、Twenty の標準オブジェクトでも可能です。 * `key: ViewKey.INDEX` は、そのビューがオブジェクトのメイン一覧ビュー（`OBJECT` ナビゲーション項目を開いたときに表示されるビュー）であることを示します。 -* `fields` は、どの列をどの順序で表示するかを制御します。 各フィールドは `fieldMetadataUniversalIdentifier` を参照します。 +* `fields` は、どの列をどの順序で表示するかを制御します。 各フィールドは `fieldMetadataUniversalIdentifier` を参照します。 `createdAt` などの自動作成システムフィールドの参照方法については、[システムフィールドのターゲット指定](/l/ja/developers/extend/apps/data/system-fields)を参照してください。 * さらに高度な構成のために、`filters`、`filterGroups`、`sorts`、`groups`、`fieldGroups` も定義できます。 * 同じオブジェクトに複数のビューがある場合、`position` が表示順を制御します。 diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..1568a2ce91 --- /dev/null +++ b/packages/twenty-docs/l/ko/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,103 @@ +--- +title: 시스템 필드 대상 지정 +description: 뷰와 다른 엔티티에서 `getFieldUniversalIdentifier`를 사용하여 `createdAt` 또는 `updatedAt` 같은 자동 생성 시스템 필드를 참조하세요. +icon: gears +--- + +Twenty의 모든 객체에는 여러분이 직접 선언하지 않아도 되는 **시스템 필드** 세트가 함께 제공됩니다. 이 필드들은 객체가 프로비저닝될 때 서버에 의해 자동으로 생성됩니다: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +[`defineField()`](/l/ko/developers/extend/apps/data/extending-objects)로 이러한 필드를 선언하지 않기 때문에, 가져올 수 있는 `universalIdentifier` 상수가 없습니다. 그렇다면 [view](/l/ko/developers/extend/apps/layout/views)에서 `createdAt`을 컬럼으로 어떻게 참조할 수 있을까요? + +## 문제 + +Twenty 2.19부터 시스템 필드의 유니버설 식별자는 애플리케이션 유니버설 식별자, 객체 유니버설 식별자, 필드 이름이라는 세 가지 입력값으로부터 서버에서 결정론적으로 도출됩니다. id를 임의로 만들고 하드코딩해도 동작하지 않습니다. 서버에서 어떤 것과도 일치하지 않으며, 동기화에서 이러한 끊어진 참조를 거부합니다: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## 해결책 + + + `getFieldUniversalIdentifier`는 `twenty-sdk` 2.21부터 사용할 수 있습니다. + + +`getFieldUniversalIdentifier`를 사용해 서버가 사용하는 것과 정확히 동일한 값을 해석하세요. 이 함수는 세 가지 입력값을 받아 필드의 유니버설 식별자를 반환합니다: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier`는 [`defineApplication()`](/l/ko/developers/extend/apps/config/application)에 전달하는, 앱의 식별자입니다. +* `objectUniversalIdentifier`는 필드가 속한 객체의 식별자입니다. +* `name`은 시스템 필드 이름이며, 위에 나열된 값들 중 하나입니다. + +## 예시: 뷰의 createdAt 컬럼 + +일반적인 사용 사례는 커스텀 객체 중 하나의 뷰에 `createdAt` 컬럼을 추가하는 것입니다. 필드 id를 해석한 다음, 다른 `fieldMetadataUniversalIdentifier`와 동일한 방식으로 참조하세요: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +이렇게 해석된 동일한 id는 `fieldMetadataUniversalIdentifier`가 필요한 모든 곳에서 사용할 수 있습니다. 예를 들어 view 필드, 필터, 정렬, 그룹, 페이지 레이아웃 위젯 등입니다. + + + id를 해석해서 사용하고, 하드코딩하지 마세요. 서버는 애플리케이션 id, 객체 id, 필드 이름으로부터 값을 도출하기 때문에, + `getFieldUniversalIdentifier`를 호출하면 이 입력값들이 변경되더라도 참조를 올바르게 유지할 수 있고, 도출 방식이 바뀌더라도 드리프트를 방지할 수 있습니다. + + +## 표준 Twenty 객체 + +**표준** Twenty 객체(Person, Company, Opportunity 등)의 경우 어떤 것도 도출할 필요가 없습니다. 시스템 필드 식별자는 미리 계산된 상수이므로 바로 import해서 사용할 수 있습니다. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +[`defineObject()`](/l/ko/developers/extend/apps/data/objects)로 **앱에서 직접 정의한** 객체처럼, 그러한 상수가 존재하지 않는 경우에 `getFieldUniversalIdentifier`를 사용하세요. + + + `name`은 시스템 필드가 아니라 **기본(default)** 필드입니다. 이 필드는 자체 하드코딩된 유니버설 식별자를 유지하며, + `getFieldUniversalIdentifier`를 통해 해석되지 않습니다. 여러분이 정의한 객체에서는 `defineObject()`에서 부여한 식별자를 사용해 `name` 필드를 참조하세요. + diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/layout/views.mdx index a71885ab8f..670caa8e67 100644 --- a/packages/twenty-docs/l/ko/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/ko/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier`는 이 뷰가 적용되는 객체를 지정합니다. 이 객체는 사용자가 정의한 커스텀 객체일 수도 있고, 표준 Twenty 객체일 수도 있습니다. * `key: ViewKey.INDEX`는 뷰를 객체의 기본 목록 보기( `OBJECT` 내비게이션 항목이 여는 보기)로 표시합니다. -* `fields`는 어떤 열을 어떤 순서로 표시할지를 제어합니다. 각 필드는 `fieldMetadataUniversalIdentifier`를 참조합니다. +* `fields`는 어떤 열을 어떤 순서로 표시할지를 제어합니다. 각 필드는 `fieldMetadataUniversalIdentifier`를 참조합니다. 자동 생성된 시스템 필드(예: `createdAt`)를 참조하는 방법은 [시스템 필드 대상으로 지정하기](/l/ko/developers/extend/apps/data/system-fields)를 참조하세요. * 또한 더 고급 구성을 위해 `filters`, `filterGroups`, `sorts`, `groups`, `fieldGroups`를 선언할 수 있습니다. * `position`은 동일한 객체에 여러 뷰가 있을 때의 정렬 순서를 제어합니다. diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..544239bca9 --- /dev/null +++ b/packages/twenty-docs/l/pt/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,107 @@ +--- +title: Referenciando campos de sistema +description: Referencie campos de sistema gerados automaticamente, como createdAt ou updatedAt, a partir de visualizações e de outras entidades com getFieldUniversalIdentifier. +icon: gears +--- + +Todo objeto no Twenty é fornecido com um conjunto de **campos de sistema** que você nunca declara manualmente. Eles são criados automaticamente pelo servidor quando o objeto é provisionado: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Como você não declara esses campos com [`defineField()`](/l/pt/developers/extend/apps/data/extending-objects), não existe nenhuma constante `universalIdentifier` para você importar. Então, como você referencia `createdAt` como uma coluna em uma [visualização](/l/pt/developers/extend/apps/layout/views)? + +## O Problema + +Desde o Twenty 2.19, o identificador universal de um campo de sistema é **derivado deterministicamente** pelo servidor a partir de três entradas: o identificador universal do aplicativo, o identificador universal do objeto e o nome do campo. Inventar um id e deixá-lo hardcoded não funciona: ele não corresponde a nada no servidor, e a sincronização rejeita a referência pendente: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## A Solução + + + `getFieldUniversalIdentifier` está disponível a partir do `twenty-sdk` 2.21. + + +Use `getFieldUniversalIdentifier` para resolver exatamente o mesmo valor que o servidor usa. Ela recebe as três entradas e retorna o identificador universal do campo: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` é o identificador do seu app, aquele que você passa para [`defineApplication()`](/l/pt/developers/extend/apps/config/application). +* `objectUniversalIdentifier` é o identificador do objeto ao qual o campo pertence. +* `name` é o nome do campo de sistema, um dos valores listados acima. + +## Exemplo: uma coluna createdAt em uma visualização + +O caso típico é adicionar uma coluna `createdAt` a uma visualização de um dos seus objetos personalizados. Resolva o id do campo e referencie-o como qualquer outro `fieldMetadataUniversalIdentifier`: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +O mesmo id resolvido funciona em qualquer lugar onde se espera um `fieldMetadataUniversalIdentifier`: campos de visualização, filtros, ordenações, agrupamentos e widgets de layout de página. + + + Resolva o id, não o deixe hardcoded. Como o servidor deriva o valor a partir do + id do aplicativo, do id do objeto e do nome do campo, chamar + `getFieldUniversalIdentifier` mantém a sua referência correta mesmo que essas + entradas mudem, e evita divergências se a derivação evoluir no futuro. + + +## Objetos Padrão do Twenty + +Para um objeto **padrão** do Twenty (Person, Company, Opportunity, …), você não precisa derivar nada: os identificadores de campos de sistema são constantes pré-computadas que você pode importar diretamente. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Use `getFieldUniversalIdentifier` quando o objeto é um que **seu app** define com [`defineObject()`](/l/pt/developers/extend/apps/data/objects), em que não existe tal constante. + + + `name` é um campo **padrão**, não um campo de sistema. Ele mantém seu próprio identificador universal + hardcoded e não é resolvido por meio de + `getFieldUniversalIdentifier`. Em objetos que você define, referencie o campo + `name` pelo identificador que você atribuiu a ele em `defineObject()`. + diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/layout/views.mdx index fda88e621c..65a6fb84d0 100644 --- a/packages/twenty-docs/l/pt/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/pt/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` especifica a qual objeto esta visualização se aplica. Pode ser um objeto personalizado que você definiu ou um objeto padrão do Twenty. * `key: ViewKey.INDEX` marca a visualização como a visualização principal de lista do objeto (aquela que um item de navegação `OBJECT` abre). -* `fields` controla quais colunas aparecem e em que ordem. Cada campo referencia um `fieldMetadataUniversalIdentifier`. +* `fields` controla quais colunas aparecem e em que ordem. Cada campo referencia um `fieldMetadataUniversalIdentifier`. Para fazer referência a um campo de sistema criado automaticamente, como `createdAt`, consulte [Direcionamento de campos do sistema](/l/pt/developers/extend/apps/data/system-fields). * Você também pode declarar `filters`, `filterGroups`, `sorts`, `groups` e `fieldGroups` para configurações avançadas. * `position` controla a ordenação quando existem várias visualizações para o mesmo objeto. diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..b20b17ea1a --- /dev/null +++ b/packages/twenty-docs/l/ro/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,107 @@ +--- +title: Țintirea câmpurilor de sistem +description: Folosind `getFieldUniversalIdentifier`, poți face referire la câmpuri de sistem create automat, precum `createdAt` sau `updatedAt`, din vizualizări și alte entități. +icon: gears +--- + +Fiecare obiect din Twenty este livrat cu un set de **câmpuri de sistem** pe care nu le declari tu însuți. Acestea sunt create automat de server atunci când obiectul este provizionat: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Deoarece nu declari aceste câmpuri cu [`defineField()`](/l/ro/developers/extend/apps/data/extending-objects), nu există niciun `universalIdentifier` constant pe care să-l imporți. Deci cum faci referire la `createdAt` ca o coloană într-o [vizualizare](/l/ro/developers/extend/apps/layout/views)? + +## Problema + +Începând cu Twenty 2.19, identificatorul universal al unui câmp de sistem este **derivat deterministic** de server din trei intrări: identificatorul universal al aplicației, identificatorul universal al obiectului și numele câmpului. Inventarea unui id și hardcodarea lui nu va funcționa: acesta nu se potrivește cu nimic de pe server, iar sincronizarea respinge referința rămasă în aer: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## Soluția + + + `getFieldUniversalIdentifier` este disponibil începând cu `twenty-sdk` 2.21. + + +Folosește `getFieldUniversalIdentifier` pentru a obține exact aceeași valoare pe care o folosește serverul. Aceasta primește cele trei intrări și returnează identificatorul universal al câmpului: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` este identificatorul aplicației tale, cel pe care îl transmiți către [`defineApplication()`](/l/ro/developers/extend/apps/config/application). +* `objectUniversalIdentifier` este identificatorul obiectului căruia îi aparține câmpul. +* `name` este numele câmpului de sistem, una dintre valorile listate mai sus. + +## Exemplu: o coloană createdAt într-o vizualizare + +Cazul tipic este adăugarea unei coloane `createdAt` la o vizualizare a unuia dintre obiectele tale personalizate. Calculează id-ul câmpului și fă referire la el ca la orice alt `fieldMetadataUniversalIdentifier`: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +Același id calculat funcționează oriunde este așteptat un `fieldMetadataUniversalIdentifier`: câmpuri de vizualizare, filtre, sortări, grupări și widget-uri de tip page-layout. + + + Calculează id-ul, nu îl hardcoda. Deoarece serverul derivă valoarea din + id-ul aplicației, id-ul obiectului și numele câmpului, apelarea + `getFieldUniversalIdentifier` menține referința corectă chiar dacă aceste + intrări se schimbă și evită divergența dacă metoda de derivare evoluează vreodată. + + +## Obiecte standard Twenty + +Pentru un obiect Twenty **standard** (Person, Company, Opportunity, …), nu trebuie să derivezi nimic: identificatorii câmpurilor de sistem sunt constante pre-calculate pe care le poți importa direct. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +Apelează la `getFieldUniversalIdentifier` atunci când obiectul este unul pe care **aplicația ta** îl definește cu [`defineObject()`](/l/ro/developers/extend/apps/data/objects), unde nu există o astfel de constantă. + + + `name` este un câmp **implicit**, nu un câmp de sistem. Acesta își păstrează propriul identificator universal + hardcodat și nu este obținut prin + `getFieldUniversalIdentifier`. În obiectele pe care le definești, fă referire la câmpul + `name` prin identificatorul pe care i l-ai dat în `defineObject()`. + diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/layout/views.mdx index ece80bd74c..9a396273e2 100644 --- a/packages/twenty-docs/l/ro/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/ro/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` specifică la ce obiect se aplică această vizualizare. Poate fi un obiect personalizat pe care l-ați definit sau un obiect standard Twenty. * `key: ViewKey.INDEX` marchează vizualizarea ca vizualizarea principală de listă a obiectului (cea pe care o deschide un element de navigare `OBJECT`). -* `fields` controlează ce coloane apar și ordinea acestora. Fiecare câmp face referire la un `fieldMetadataUniversalIdentifier`. +* `fields` controlează ce coloane apar și ordinea acestora. Fiecare câmp face referire la un `fieldMetadataUniversalIdentifier`. Pentru a face referire la un câmp de sistem creat automat, cum ar fi `createdAt`, consultă [Țintirea câmpurilor de sistem](/l/ro/developers/extend/apps/data/system-fields). * Puteți declara, de asemenea, `filters`, `filterGroups`, `sorts`, `groups` și `fieldGroups` pentru configurații avansate. * `position` controlează ordonarea atunci când există mai multe vizualizări pentru același obiect. diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..385deb17ac --- /dev/null +++ b/packages/twenty-docs/l/tr/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,104 @@ +--- +title: Sistem Alanlarını Hedefleme +description: "`createdAt` veya `updatedAt` gibi otomatik oluşturulan sistem alanlarına görünümlerden ve diğer varlıklardan `getFieldUniversalIdentifier` ile referans verin." +icon: gears +--- + +Twenty içindeki her nesne, kendiniz asla tanımlamadığınız bir dizi **sistem alanı** ile birlikte gelir. Bunlar, nesne sağlandığında sunucu tarafından otomatik olarak oluşturulur: + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +Bu alanları [`defineField()`](/l/tr/developers/extend/apps/data/extending-objects) ile tanımlamadığınız için, içe aktarabileceğiniz bir `universalIdentifier` sabiti yoktur. Peki bir [görünümde](/l/tr/developers/extend/apps/layout/views) `createdAt` alanına sütun olarak nasıl referans verirsiniz? + +## Sorun + +Twenty 2.19'dan beri, bir sistem alanının evrensel tanımlayıcısı, sunucu tarafından üç girdiden **deterministik olarak türetilir**: uygulama evrensel tanımlayıcısı, nesne evrensel tanımlayıcısı ve alan adı. Rastgele bir id uydurup onu hardcode etmek işe yaramaz: sunucudaki hiçbir şeyle eşleşmez ve senkronizasyon, askıda kalan referansı reddeder: + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## Çözüm + + + `getFieldUniversalIdentifier`, `twenty-sdk` 2.21 sürümünden itibaren kullanılabilir. + + +Sunucunun kullandığıyla tamamen aynı değeri elde etmek için `getFieldUniversalIdentifier` kullanın. Üç girdiyi alır ve alanın evrensel tanımlayıcısını döndürür: + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier`, uygulamanızın tanımlayıcısıdır; [`defineApplication()`](/l/tr/developers/extend/apps/config/application) çağrısına aktardığınız tanımlayıcı. +* `objectUniversalIdentifier`, alanın ait olduğu nesnenin tanımlayıcısıdır. +* `name`, sistem alan adıdır; yukarıda listelenen değerlerden biridir. + +## Örnek: bir görünümde createdAt sütunu + +Tipik durum, özel nesnelerinizden birinin görünümüne bir `createdAt` sütunu eklemektir. Alan id'sini çözümleyin ve ona, herhangi bir `fieldMetadataUniversalIdentifier` gibi referans verin: + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +Aynı çözümlenen id, bir `fieldMetadataUniversalIdentifier` beklendiği her yerde çalışır: görünüm alanları, filtreler, sıralamalar, gruplar ve sayfa düzeni bileşenleri. + + + Id'yi çözümleyin, hardcode etmeyin. Sunucu değeri uygulama id'si, nesne id'si ve alan adından + türettiği için, `getFieldUniversalIdentifier` çağrısı, bu girdiler değişse bile referansınızı doğru tutar ve türetme zaman içinde gelişirse sapmayı önler. + + +## Standart Twenty nesneleri + +**Standart** bir Twenty nesnesi (Person, Company, Opportunity, …) için hiçbir şey türetmeniz gerekmez: sistem alanı tanımlayıcıları, doğrudan içe aktarabileceğiniz önceden hesaplanmış sabitlerdir. + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +[`defineObject()`](/l/tr/developers/extend/apps/data/objects) ile **uygulamanızın** tanımladığı, böyle bir sabitin olmadığı nesnelerde `getFieldUniversalIdentifier` yöntemine başvurun. + + + `name`, bir sistem alanı değil, bir **varsayılan** alandır. Kendi hardcode edilmiş + evrensel tanımlayıcısını korur ve + `getFieldUniversalIdentifier` ile çözülmez. Tanımladığınız nesnelerde, `name` alanına `defineObject()` içinde ona verdiğiniz tanımlayıcı ile referans verin. + diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/layout/views.mdx index a230a9817f..ec5357fe1f 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier`, bu görünümün hangi nesneye uygulanacağını belirtir. Bu, tanımladığınız özel bir nesne veya standart bir Twenty nesnesi olabilir. * `key: ViewKey.INDEX` görünümü nesnenin ana liste görünümü olarak işaretler (bir `OBJECT` gezinme öğesinin açtığı görünüm). -* `fields`, hangi sütunların görüneceğini ve hangi sırayla görüneceğini kontrol eder. Her alan bir `fieldMetadataUniversalIdentifier` öğesine referans verir. +* `fields`, hangi sütunların görüneceğini ve hangi sırayla görüneceğini kontrol eder. Her alan bir `fieldMetadataUniversalIdentifier` öğesine referans verir. Otomatik oluşturulan `createdAt` gibi bir sistem alanına başvurmak için, bkz. [Sistem Alanlarını Hedefleme](/l/tr/developers/extend/apps/data/system-fields). * Daha gelişmiş yapılandırmalar için `filters`, `filterGroups`, `sorts`, `groups` ve `fieldGroups` da tanımlayabilirsiniz. * `position`, aynı nesne için birden fazla görünüm olduğunda sıralamayı kontrol eder. diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx new file mode 100644 index 0000000000..da4ee13cea --- /dev/null +++ b/packages/twenty-docs/l/zh/developers/extend/apps/data/system-fields.mdx @@ -0,0 +1,105 @@ +--- +title: 定位系统字段 +description: 在视图和其他实体中，使用 getFieldUniversalIdentifier 引用自动创建的系统字段，例如 createdAt 或 updatedAt。 +icon: gears +--- + +Twenty 中的每个对象都带有一组你无需自行声明的**系统字段**。 这些字段在对象初始化时由服务器自动创建： + +`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector` + +由于你不会使用 [`defineField()`](/l/zh/developers/extend/apps/data/extending-objects) 来声明这些字段，因此也没有可供你导入的 `universalIdentifier` 常量。 那么，如何在[视图](/l/zh/developers/extend/apps/layout/views)中将 `createdAt` 作为一列来引用呢？ + +## 问题 + +从 Twenty 2.19 起，系统字段的通用标识符由服务器根据三个输入**确定性派生**：应用通用标识符、对象通用标识符以及字段名称。 自行构造一个 id 并将其硬编码是行不通的：它在服务器上不会匹配任何内容，同步时会拒绝这个悬空引用： + +``` +Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found +``` + +## 解决方案 + + + `getFieldUniversalIdentifier` 从 `twenty-sdk` 2.21 版本开始可用。 + + +使用 `getFieldUniversalIdentifier` 来解析与服务器使用的值完全相同的字段标识符。 它接收这三个输入，并返回字段的通用标识符： + +```ts +import { getFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const createdAtFieldId = getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', +}); +``` + +* `applicationUniversalIdentifier` 是你的应用标识符，也就是你传递给 [`defineApplication()`](/l/zh/developers/extend/apps/config/application) 的那个。 +* `objectUniversalIdentifier` 是该字段所属对象的标识符。 +* `name` 是系统字段名称，为上面列出的值之一。 + +## 示例：视图中的 createdAt 列 + +典型场景是：为你某个自定义对象的视图添加一列 `createdAt`。 解析字段 id，并像引用其他 `fieldMetadataUniversalIdentifier` 一样引用它： + +```ts src/views/example-view.ts +import { + defineView, + getFieldUniversalIdentifier, +} from 'twenty-sdk/define'; + +const APPLICATION_UNIVERSAL_IDENTIFIER = + '0b04e15c-27b2-4741-9046-b32e07469072'; +const MY_OBJECT_UNIVERSAL_IDENTIFIER = + 'c782b61c-70fd-4c88-9cd6-4e61ab8d7591'; + +export default defineView({ + universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0', + name: 'All records', + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + icon: 'IconList', + position: 0, + fields: [ + { + universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104', + fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({ + applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER, + name: 'createdAt', + }), + position: 0, + isVisible: true, + size: 200, + }, + ], +}); +``` + +同一个解析得到的 id 可在任何需要 `fieldMetadataUniversalIdentifier` 的地方使用：视图字段、筛选器、排序、分组以及页面布局挂件。 + + + 解析 id，而不是将其硬编码。 由于服务器是根据应用 id、对象 id 和字段名来派生该值的，调用 + `getFieldUniversalIdentifier` 能在这些输入发生变化时仍保持引用正确，并在派生逻辑演进时避免偏差。 + + +## 标准 Twenty 对象 + +对于**标准** Twenty 对象（Person、Company、Opportunity 等），你不需要进行任何派生：系统字段标识符是预先计算好的常量，你可以直接导入。 + +```ts +import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define'; + +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier +``` + +当对象是由**你的应用**使用 [`defineObject()`](/l/zh/developers/extend/apps/data/objects) 定义、且不存在此类常量时，再使用 `getFieldUniversalIdentifier`。 + + + `name` 是一个**默认**字段，而不是系统字段。 它保留自己的硬编码 + 通用标识符，而不是通过 + `getFieldUniversalIdentifier` 解析。 在你定义的对象上，请使用你在 `defineObject()` 中赋予它的标识符来引用 + `name` 字段。 + diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/layout/views.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/layout/views.mdx index 50e597c421..54e35e945d 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/layout/views.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/layout/views.mdx @@ -34,7 +34,7 @@ export default defineView({ * `objectUniversalIdentifier` 指定此视图适用于哪个对象。 它可以是你定义的自定义对象，也可以是标准的 Twenty 对象。 * `key: ViewKey.INDEX` 将该视图标记为对象的主列表视图（`OBJECT` 导航项打开的那个）。 -* `fields` 控制显示哪些列以及它们的顺序。 每个字段引用一个 `fieldMetadataUniversalIdentifier`。 +* `fields` 控制显示哪些列以及它们的顺序。 每个字段引用一个 `fieldMetadataUniversalIdentifier`。 若要引用自动创建的系统字段（例如 `createdAt`），请参阅[定位系统字段](/l/zh/developers/extend/apps/data/system-fields)。 * 你还可以声明 `filters`、`filterGroups`、`sorts`、`groups` 和 `fieldGroups` 以进行更高级的配置。 * 当同一对象存在多个视图时，`position` 控制其排序。