From 8707ebb7ac1b8f35d602ee7a8ead038b7a06f652 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 17:23:57 +0200 Subject: [PATCH] i18n - docs translations (#23515) Created by Github action Co-authored-by: github-actions --- .../extend/apps/data/system-fields.mdx | 74 ++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 76 +++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 71 ++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 79 ++++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 75 +++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 9 ++- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 76 +++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 71 ++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 9 ++- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 71 ++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 77 +++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 78 +++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 72 ++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- .../extend/apps/data/system-fields.mdx | 71 ++++++++++++++--- .../developers/extend/apps/layout/views.mdx | 11 +-- .../document-generator/building-the-ui.mdx | 5 +- 36 files changed, 865 insertions(+), 214 deletions(-) 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 index dd1c0aba62..ec3615fce2 100644 --- 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 @@ -1,16 +1,22 @@ --- -title: استهداف الحقول النظامية -description: استدعِ الحقول النظامية التي يتم إنشاؤها تلقائيًا مثل `createdAt` أو `updatedAt` من العروض والكائنات الأخرى باستخدام `getFieldUniversalIdentifier`. +title: استهداف البيانات الوصفية النظامية +description: حلّ المعرّفات العالمية الحتمية للبيانات الوصفية التي يوفّرها Twenty تلقائيًا على كل كائن، بحيث يمكن لتطبيقك الرجوع إليها من دون ترميز ثابت. icon: gears --- -كل كائن في Twenty يأتي مع مجموعة من **الحقول النظامية** التي لا تقوم بتعريفها بنفسك أبدًا. يتم إنشاؤها تلقائيًا بواسطة الخادم عندما يتم توفير الكائن: +كل كائن في Twenty يأتي مع **بيانات وصفية نظامية** لا تقوم أنت بتعريفها، مثل مجموعة من الحقول وعرض القائمة الرئيسي مع أعمدته. يقوم الخادم بإنشاء كل ذلك عند توفير الكائن، وتنمو هذه المجموعة مع نمو Twenty. + +نظرًا لأنك لا تعرّفها، فلا يوجد ثابت `universalIdentifier` لتقوم باستيراده. بدلًا من ذلك، يقوم الخادم **باستخلاص** كل معرّف بشكل حتمي، ويعرض `twenty-sdk` نفس طريقة الاستخلاص بحيث يمكن لملف البيان (manifest) لديك حلّ القيمة الدقيقة التي يستخدمها الخادم. + +## حقول النظام + +الحقول البسيطة (scalar) الموجودة على كل كائن، والتي لا تعرّف أيًا منها باستخدام [`defineField()`](/l/ar/developers/extend/apps/data/extending-objects): `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)؟ +فكيف تُشير إلى `createdAt` كعمود في [عرض](/l/ar/developers/extend/apps/layout/views)؟ -## المشكلة +### المشكلة منذ Twenty 2.19، يتم اشتقاق المعرّف الشامل للحقل النظامي **بشكل حتمي** بواسطة الخادم من ثلاثة مُدخلات: المعرّف الشامل للتطبيق، والمعرّف الشامل للكائن، واسم الحقل. ابتكار معرّف (id) وتضمينه بشكل ثابت لن ينجح: لن يطابق أي شيء على الخادم، وسترفض المزامنة المرجع المعلّق: @@ -18,7 +24,7 @@ icon: gears Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## الحل +### الحل يتوفر `getFieldUniversalIdentifier` في `twenty-sdk` بدءًا من الإصدار 2.21 فصاعدًا. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `objectUniversalIdentifier` هو معرّف الكائن الذي ينتمي إليه الحقل. * `name` هو اسم الحقل النظامي، وهو إحدى القيم المُدرجة أعلاه. -## مثال: عمود `createdAt` في عرض +### مثال: عمود `createdAt` في عرض الحالة النموذجية هي إضافة عمود `createdAt` إلى عرض لأحد الكائنات المخصّصة لديك. اشتقّ معرّف الحقل واستدعِه كما تستدعي أي `fieldMetadataUniversalIdentifier` آخر: @@ -84,7 +90,7 @@ export default defineView({ `getFieldUniversalIdentifier` يُبقي مرجعك صحيحًا حتى إذا تغيّرت تلك المُدخلات، ويتجنّب الانحراف إذا تطوّر أسلوب الاشتقاق في أي وقت. -## حقول العلاقات الخاصة بالنظام +### حقول العلاقات الخاصة بالنظام `getSystemRelationFieldUniversalIdentifier` متوفر في `twenty-sdk` @@ -130,18 +136,66 @@ const attachmentTargetRocketFieldId = كما هو الحال مع حقول النظام القياسية (scalar)، يعمل المعرّف الناتج في أي موضع يُتوقَّع فيه `fieldMetadataUniversalIdentifier`. +## العروض النظامية + + + إن `getSystemViewUniversalIdentifier` و`getSystemViewFieldUniversalIdentifier` + متوفران في `twenty-sdk` بدءًا من الإصدار 2.26، ويتطلبان خادم Twenty + بالإصدار 2.26 أو أحدث. + + +يقوم الخادم أيضًا بتوفير **عرض نظامي** على كل كائن: عرض القائمة الرئيسي (`All {objectLabelPlural}`، ذو المفتاح `ViewKey.INDEX`)، مع عمود واحد لكل حقل قابل للعرض. تمامًا مثل حقول العلاقات النظامية، تُشتق معرّفاتها **من دون أسماء**، لذلك لن يؤدي تغيير اسم كائن أو حقل إلى تغييرها مطلقًا. + +استخدم `getSystemViewUniversalIdentifier` لحلّ العرض: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` هو التطبيق الذي يملك **الكائن**، وهو ما يتم بناء نطاق الاسم (namespace) للعرض على أساسه. +* `objectUniversalIdentifier` هو الكائن الذي يعرضه (يسردُه) هذا العرض. +* `viewKey` هو مفتاح العرض النظامي، وهو `ViewKey.INDEX` حاليًا. + +يعمل المعرّف المحلول في أي مكان يُتوقَّع فيه `viewUniversalIdentifier`، مثل إدخال الشريط الجانبي من النوع [`NavigationMenuItemType.VIEW`](/l/ar/developers/extend/apps/layout/navigation-menu-items). لفتح القائمة الرئيسية لكائن ما ببساطة، يُفضَّل استخدام `NavigationMenuItemType.OBJECT` مع `targetObjectUniversalIdentifier`، إذ لا يحتاج ذلك إلى أي اشتقاق. + +يقوم `getSystemViewFieldUniversalIdentifier` بحلّ **عمود** واحد في عرض نظامي، انطلاقًا من العرض والحقل الذي يعرضه هذا العمود: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +انتبه إلى الوسيطة الأولى: يتم تحديد نطاق اسم العمود بواسطة التطبيق الذي يملك **الحقل الذي يعرضه**، وليس التطبيق الذي يملك العرض. الحقل الذي يضيفه تطبيقك إلى كائن قياسي يحصل على عموده المشتق ضمن نطاق تطبيقك، على عرض مملوك من قِبَل Twenty. + + + العروض النظامية وأعمدتها **مملوكة للخادم**: استخدم حلّ معرّفاتها للرجوع إليها، وليس لتعريفها. إن الخاصية `key` في + [`defineView()`](/l/ar/developers/extend/apps/layout/views) مهملة (deprecated) ويتم تجاهلها، لذلك لا يمكن لعرض مُعرَّف في ملف البيان المطالبة بالمفتاح `INDEX` مطلقًا، كما أن الخادم يوفّر بالفعل عمودًا لكل حقل تضيفه، لذا فإن تعريف `defineViewField()` خاصّتك لنفس الحقل على عرض نظامي يتعارض معه. + + ## الكائنات القياسية في Twenty -بالنسبة إلى كائن Twenty **قياسي** (Person، Company، Opportunity، …)، لا تحتاج إلى اشتقاق أي شيء: فمعرّفات الحقول النظامية هي ثوابت مُسبقة الحساب يمكنك استيرادها مباشرة. +بالنسبة إلى كائن 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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier ``` -الجأ إلى `getFieldUniversalIdentifier` عندما يكون الكائن واحدًا مما يعرّفه تطبيقك باستخدام [`defineObject()`](/l/ar/developers/extend/apps/data/objects)، حيث لا يوجد مثل هذا الثابت. +الجأ إلى أدوات المساعدة المذكورة أعلاه عندما يكون الكائن واحدًا مما يعرّفه **تطبيقك** باستخدام [`defineObject()`](/l/ar/developers/extend/apps/data/objects)، حيث لا يوجد مثل هذا الثابت. `name` حقل **افتراضي**، وليس حقلًا نظاميًا. يحتفظ بمعرّفه الشامل الثابت الخاص به ولا يتم اشتقاقه عبر 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 30f498426f..65977de0ae 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 @@ -4,10 +4,12 @@ description: قم بتوفير عروض محفوظة مُعدّة مسبقًا icon: list --- -يُعد **العرض** تكوينًا محفوظًا لكيفية عرض سجلات كائن معيّن: ما هي الحقول التي تظهر، وترتيبها، وما إذا كانت مرئية، وأي عوامل تصفية أو مجموعات مُطبَّقة. استخدم `defineView()` لتوفير عروض مُعدّة مسبقًا مع تطبيقك — عادةً عرض فهرس افتراضي لكل كائن مخصص تقوم بإنشائه. +يُعد **العرض** تكوينًا محفوظًا لكيفية عرض سجلات كائن معيّن: ما هي الحقول التي تظهر، وترتيبها، وما إذا كانت مرئية، وأي عوامل تصفية أو مجموعات مُطبَّقة. استخدم `defineView()` لتضمين عروض مُهيّأة مسبقًا مع تطبيقك. + +يتلقى كل كيان (object) تلقائيًا عرض قائمة رئيسي خاص به (جدول "All ..." الذي يفتحه عنصر التنقل `OBJECT`) يتم توفيره من الخادم — بما في ذلك الكيانات التي ينشئها تطبيقك، مع عمود واحد لكل حقل يعرّفه تطبيقك. تكون العروض (views) التي تعرّفها باستخدام `defineView()` دائمًا عروضا **إضافية** فوق ذلك العرض الافتراضي. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## النقاط الرئيسية * `objectUniversalIdentifier` يحدّد الكائن الذي ينطبق عليه هذا العرض. يمكن أن يكون كائنًا مخصصًا قمتَ بتعريفه أو كائن Twenty قياسيًا. -* `key: ViewKey.INDEX` يحدد العرض بوصفه عرض القائمة الرئيسي للكائن (ذلك الذي يفتحه عنصر التنقل `OBJECT`). -* يتحكّم `fields` في الأعمدة التي تظهر وترتيبها. يشير كل حقل إلى `fieldMetadataUniversalIdentifier`. للإشارة إلى حقل نظام يتم إنشاؤه تلقائيًا مثل `createdAt`، راجع قسم [استهداف حقول النظام](/l/ar/developers/extend/apps/data/system-fields). +* إن عرض القائمة الرئيسي للكائن مملوك من قبل الخادم: تم إهمال `key` ويتم تجاهله، لذا لا يمكن لعرض البيان المطالبة به مطلقًا. أضف عنصر تنقل `VIEW` إذا كنت تريد أن يكون عرضك على بعد نقرة واحدة في الشريط الجانبي. +* يتحكّم `fields` في الأعمدة التي تظهر وترتيبها. يشير كل حقل إلى `fieldMetadataUniversalIdentifier`. للإشارة إلى حقل نظام يتم إنشاؤه تلقائيًا مثل `createdAt`، راجع قسم [استهداف بيانات النظام الوصفية](/l/ar/developers/extend/apps/data/system-fields). * يمكنك أيضًا تعريف `filters` و`filterGroups` و`sorts` و`groups` و`fieldGroups` لتكوينات أكثر تقدمًا. * يتحكّم `position` في الترتيب عند وجود عدة عروض لنفس الكائن. diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 5017d7d440..641cdb2c6e 100644 --- a/packages/twenty-docs/l/ar/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/ar/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -10,17 +10,16 @@ description: المشاهدة، الملاحة الجانبية، الأوامر A [view](/l/ar/developers/extend/apps/layout/views) هي قائمة محفوظة لكائن معين. ويضع [عنصر قائمة التنقل](/l/ar/developers/extend/apps/layout/navigation-menu-items) -هذا العرض في الشريط الجانبي. +هذا العرض في الشريط الجانبي. يوفر الخادم بالفعل طريقة العرض الافتراضية "All ..." لكل كائن تلقائيًا، لذا فإن طرق العرض التي يعرّفها التطبيق تكون إضافية ومُنتقاة بعناية. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index b7fcfc4e25..7ba7192954 100644 --- 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 @@ -1,16 +1,22 @@ --- -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. +title: Cílení na systémová metadata +description: Vyřešte deterministické univerzální identifikátory metadat, která Twenty automaticky zřizuje u každého objektu, aby se na ně vaše aplikace mohla odkazovat bez hardcodování. 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: +Každý objekt v Twenty má **systémová metadata**, která sami nedefinujete, například sadu polí a hlavní zobrazení seznamu s jeho sloupci. Server všechno vytvoří při zřízení objektu a tato sada roste spolu s tím, jak roste Twenty. + +Protože je nedefinujete, neexistuje žádná konstanta `universalIdentifier`, kterou byste mohli importovat. Místo toho server každý identifikátor **odvozuje** deterministicky a `twenty-sdk` zpřístupňuje stejné odvozování, takže váš manifest může zjistit přesnou hodnotu, kterou server používá. + +## Systémová pole + +Skalární pole přítomná na každém objektu, z nichž žádné nedefinujete pomocí [`defineField()`](/l/cs/developers/extend/apps/data/extending-objects): `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)? +Jak tedy odkážete na `createdAt` jako na sloupec ve [zobrazení](/l/cs/developers/extend/apps/layout/views)? -## Problém +### 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: @@ -18,7 +24,7 @@ Od Twenty 2.19 je univerzální identifikátor systémového pole **deterministi Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## Řešení +### Řešení `getFieldUniversalIdentifier` je k dispozici od `twenty-sdk` verze 2.21 a vyšší. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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í +### 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`: @@ -86,7 +92,7 @@ Tentýž odvozený identifikátor funguje všude tam, kde se očekává `fieldMe vstupy změní, a předchází odchylkám, pokud se samotný způsob odvozování někdy změní. -## Systémová relační pole +### Systémová relační pole `getSystemRelationFieldUniversalIdentifier` je k dispozici od verze `twenty-sdk` @@ -132,18 +138,68 @@ const attachmentTargetRocketFieldId = Stejně jako u skalárních systémových polí funguje vyřešené ID všude tam, kde je očekáváno `fieldMetadataUniversalIdentifier`. +## Systémová zobrazení + + + `getSystemViewUniversalIdentifier` a `getSystemViewFieldUniversalIdentifier` + jsou k dispozici od verze `twenty-sdk` 2.26 a vyžadují server Twenty ve + verzi 2.26 nebo novější. + + +Server také pro každý objekt zřizuje **systémové zobrazení**: hlavní zobrazení seznamu (`All {objectLabelPlural}`, s klíčem `ViewKey.INDEX`) s jedním sloupcem pro každé zobrazitelné pole. Stejně jako u systémových relačních polí jsou jejich identifikátory odvozovány **nezávisle na názvu**, takže přejmenování objektu nebo pole je nikdy nezmění. + +Použijte `getSystemViewUniversalIdentifier` k vyřešení zobrazení: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` je aplikace, která vlastní **objekt**, podle které je zobrazení namespacované. +* `objectUniversalIdentifier` je objekt, který zobrazení vypisuje. +* `viewKey` je klíč systémového zobrazení, aktuálně `ViewKey.INDEX`. + +Vyhodnocené ID funguje všude tam, kde se očekává `viewUniversalIdentifier`, například u položky postranního panelu [`NavigationMenuItemType.VIEW`](/l/cs/developers/extend/apps/layout/navigation-menu-items). Pro pouhé otevření hlavního seznamu objektu preferujte `NavigationMenuItemType.OBJECT` s `targetObjectUniversalIdentifier`: nevyžaduje žádné odvozování. + +`getSystemViewFieldUniversalIdentifier` vyhodnotí jeden konkrétní **sloupec** v systémovém zobrazení na základě zobrazení a pole, které zobrazuje: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Všimněte si prvního argumentu: sloupec je namespacován podle aplikace, která vlastní **pole, které zobrazuje**, nikoli podle aplikace, která vlastní zobrazení. Pole, které vaše aplikace přidá ke standardnímu objektu, má svůj sloupec odvozený pod vaší aplikací, a to v rámci zobrazení vlastněného Twenty. + + + Systémová zobrazení a jejich sloupce jsou **vlastněna serverem**: vyhodnocujte jejich identifikátory pro účely odkazování, nikdy pro jejich deklaraci. `key` u + [`defineView()`](/l/cs/developers/extend/apps/layout/views) je zastaralý a + ignorovaný, takže manifestové zobrazení nikdy nemůže nárokovat klíč `INDEX` a server už zřizuje sloupec pro každé pole, které přidáte, takže deklarovat vlastní + `defineViewField()` pro stejné pole v systémovém zobrazení s tím bude v konfliktu. + + ## 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. +U **standardního** objektu Twenty (Person, Company, Opportunity, …) nemusíte nic odvozovat: identifikátory jsou předpočítané konstanty, které můžete přímo importovat, a to jak pro pole, tak pro zobrazení. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Použijte pomocné funkce uvedené výše 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ý 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 9e3645572e..4f3a631f64 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 @@ -4,10 +4,12 @@ description: Dodávejte předem nakonfigurovaná uložená zobrazení – pořad icon: list --- -**Zobrazení** je uložená konfigurace toho, jak se zobrazují záznamy objektu: která pole se zobrazují, v jakém pořadí, zda jsou viditelná a jaké filtry nebo seskupení jsou použity. Pomocí `defineView()` můžete s aplikací dodávat předem nakonfigurovaná zobrazení – obvykle výchozí indexové zobrazení pro každý vlastní objekt, který vytvoříte. +**Zobrazení** je uložená konfigurace toho, jak se zobrazují záznamy objektu: která pole se zobrazují, v jakém pořadí, zda jsou viditelná a jaké filtry nebo seskupení jsou použity. Pomocí `defineView()` můžete k aplikaci přidat předkonfigurovaná zobrazení. + +Každý objekt automaticky získá své hlavní zobrazení seznamu (tabulku „All ...“, kterou otevírá navigační položka `OBJECT`), poskytované serverem – včetně objektů, které vaše aplikace vytváří, s jedním sloupcem pro každé pole, které vaše aplikace deklaruje. Zobrazení, která definujete pomocí `defineView()`, jsou vždy **dodatečná** zobrazení nad rámec tohoto výchozího. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Hlavní body * `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`. 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). +* Hlavní zobrazení seznamu objektu je vlastněné serverem: `key` je zastaralý a ignorován, takže si je zobrazení definované v manifestu nikdy nemůže nárokovat. Dodejte navigační položku `VIEW`, pokud chcete mít své zobrazení na jedno kliknutí v postranním panelu. +* `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á metadata](/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/cs/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 493e5abdb0..f7e5cc22f5 100644 --- a/packages/twenty-docs/l/cs/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/cs/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ a nativní text **editor** pro šablony. [view](/l/cs/developers/extend/apps/layout/views) je uložený seznam daného objektu. [Položka navigačního menu](/l/cs/developers/extend/apps/layout/navigation-menu-items) -umístí toto zobrazení do postranního panelu. +umístí toto zobrazení do postranního panelu. Server už pro každý objekt automaticky poskytuje výchozí zobrazení „All ...“, takže zobrazení, která aplikace definuje, jsou další, pečlivě vybraná. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 078b1f0de8..47d6e209b1 100644 --- 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 @@ -1,16 +1,22 @@ --- -title: Systemfelder ansprechen -description: Referenzieren Sie automatisch erstellte Systemfelder wie createdAt oder updatedAt aus Ansichten und anderen Entitäten mit getFieldUniversalIdentifier. +title: Systemmetadaten ansprechen +description: Lösen Sie die deterministischen universellen Bezeichner der Metadaten auf, die Twenty für jedes Objekt automatisch bereitstellt, damit Ihre App ohne Hardcoding darauf verweisen kann. 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: +Jedes Objekt in Twenty verfügt über **Systemmetadaten**, die Sie selbst nie deklarieren, wie etwa eine Reihe von Feldern und eine Hauptlistenansicht mit ihren Spalten. Der Server erstellt all dies, wenn das Objekt bereitgestellt wird, und der Umfang wächst mit Twenty. + +Da Sie sie nicht deklarieren, gibt es keine `universalIdentifier`-Konstante, die Sie importieren könnten. Stattdessen **leitet** der Server jeden Bezeichner deterministisch ab, und `twenty-sdk` stellt dieselbe Ableitung zur Verfügung, sodass Ihr Manifest den genauen Wert auflösen kann, den der Server verwendet. + +## Systemfelder + +Die skalaren Felder, die bei jedem Objekt vorhanden sind und die Sie nicht mit [`defineField()`](/l/de/developers/extend/apps/data/extending-objects) deklarieren: `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)? +Wie referenzieren Sie also `createdAt` als Spalte in einer [Ansicht](/l/de/developers/extend/apps/layout/views)? -## Das Problem +### 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: @@ -18,7 +24,7 @@ Seit Twenty 2.19 wird die universelle Kennung eines Systemfelds **deterministisc Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## Die Lösung +### Die Lösung `getFieldUniversalIdentifier` ist ab `twenty-sdk` 2.21 verfügbar. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### 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`: @@ -85,7 +91,7 @@ Dieselbe aufgelöste ID funktioniert überall dort, wo ein `fieldMetadataUnivers Eingaben ändern, und verhindert Abweichungen, falls sich die Ableitung jemals weiterentwickelt. -## System-Relationsfelder +### System-Relationsfelder `getSystemRelationFieldUniversalIdentifier` ist ab Version 2.23 von `twenty-sdk` verfügbar und erfordert einen Twenty-Server in Version 2.23 oder höher. @@ -130,18 +136,63 @@ const attachmentTargetRocketFieldId = Wie bei skalaren Systemfeldern funktioniert die aufgelöste ID überall dort, wo ein `fieldMetadataUniversalIdentifier` erwartet wird. +## Systemansichten + + + `getSystemViewUniversalIdentifier` und `getSystemViewFieldUniversalIdentifier` sind ab Version 2.26 von `twenty-sdk` verfügbar und erfordern einen Twenty-Server in Version 2.26 oder höher. + + +Der Server stellt außerdem für jedes Objekt eine **Systemansicht** bereit: die Hauptlistenansicht (`All {objectLabelPlural}`, mit dem Schlüssel `ViewKey.INDEX`), mit einer Spalte pro anzeigbarem Feld. Wie bei Systembeziehungsfeldern werden ihre Bezeichner **namensfrei** abgeleitet, sodass das Umbenennen eines Objekts oder eines Feldes sie nie ändert. + +Verwenden Sie `getSystemViewUniversalIdentifier`, um die Ansicht aufzulösen: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` ist die Anwendung, der das **Objekt** gehört; sie bestimmt den Namensraum der Ansicht. +* `objectUniversalIdentifier` ist das Objekt, das die Ansicht auflistet. +* `viewKey` ist der Systemansichtsschlüssel, aktuell `ViewKey.INDEX`. + +Die aufgelöste ID funktioniert überall dort, wo ein `viewUniversalIdentifier` erwartet wird, etwa bei einem [`NavigationMenuItemType.VIEW`](/l/de/developers/extend/apps/layout/navigation-menu-items)-Eintrag in der Seitenleiste. Um einfach die Hauptliste eines Objekts zu öffnen, sollten Sie `NavigationMenuItemType.OBJECT` mit `targetObjectUniversalIdentifier` bevorzugen: Es benötigt keine Ableitung. + +`getSystemViewFieldUniversalIdentifier` löst eine einzelne **Spalte** in einer Systemansicht auf, basierend auf der Ansicht und dem Feld, das sie anzeigt: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Beachten Sie das erste Argument: Eine Spalte ist dem Namensraum der Anwendung zugeordnet, die das **Feld, das sie anzeigt**, besitzt – nicht der Anwendung, der die Ansicht gehört. Ein Feld, das Ihre App zu einem Standardobjekt hinzufügt, erhält seine Spalte im Namensraum Ihrer Anwendung – auf einer Ansicht, die Twenty gehört. + + + Systemansichten und ihre Spalten sind im Besitz des Servers: Lösen Sie ihre Bezeichner auf, um auf sie zu verweisen, niemals, um sie zu deklarieren. `key` in [`defineView()`](/l/de/developers/extend/apps/layout/views) ist veraltet und wird ignoriert, sodass eine Manifestansicht niemals den `INDEX`-Schlüssel beanspruchen kann, und der Server stellt bereits eine Spalte für jedes Feld bereit, das Sie hinzufügen, sodass das Deklarieren eines eigenen `defineViewField()` für dasselbe Feld in einer Systemansicht damit in Konflikt steht. + + ## 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. +Für ein **Standard**-Twenty-Objekt (Person, Company, Opportunity, …) müssen Sie nichts ableiten: Die Bezeichner für Felder und Ansichten 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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Greifen Sie auf die obigen Helfer zurück, wenn es sich um ein Objekt handelt, das **Ihre App** mit [`defineObject()`](/l/de/developers/extend/apps/data/objects) definiert und für das es keine solche Konstante gibt. `name` ist ein **Standard**-Feld, kein Systemfeld. Es behält seine eigene hart codierte 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 63ad18653f..87251c96ab 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 @@ -4,10 +4,12 @@ description: Stellen Sie vorkonfigurierte gespeicherte Ansichten bereit – Spal icon: list --- -Eine **Ansicht** ist eine gespeicherte Konfiguration dafür, wie Datensätze eines Objekts angezeigt werden: welche Felder erscheinen, in welcher Reihenfolge, ob sie sichtbar sind und welche Filter oder Gruppen angewendet werden. Verwenden Sie `defineView()`, um vorkonfigurierte Ansichten mit Ihrer App auszuliefern – typischerweise eine Standard-Indexansicht für jedes benutzerdefinierte Objekt, das Sie erstellen. +Eine **Ansicht** ist eine gespeicherte Konfiguration dafür, wie Datensätze eines Objekts angezeigt werden: welche Felder erscheinen, in welcher Reihenfolge, ob sie sichtbar sind und welche Filter oder Gruppen angewendet werden. Verwenden Sie `defineView()`, um vorkonfigurierte Ansichten mit Ihrer App auszuliefern. + +Jedes Objekt erhält automatisch seine Hauptlistenansicht (die "Alle ..."-Tabelle, die ein `OBJECT`-Navigationselement öffnet), die vom Server bereitgestellt wird – einschließlich der Objekte, die Ihre App erstellt, mit einer Spalte pro Feld, das Ihre App definiert. Ansichten, die Sie mit `defineView()` definieren, sind stets **zusätzliche** Ansichten neben der Standardansicht. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Hauptpunkte * `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`. Informationen zum Verweisen auf ein automatisch erstelltes Systemfeld wie `createdAt` finden Sie unter [Systemfelder ansteuern](/l/de/developers/extend/apps/data/system-fields). +* Die Hauptlistenansicht des Objekts gehört dem Server: `key` ist veraltet und wird ignoriert, daher kann eine Manifest-Ansicht sie niemals beanspruchen. Liefern Sie ein `VIEW`-Navigationselement aus, wenn Ihre Ansicht nur einen Klick entfernt in der Seitenleiste sein soll. +* `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 [Systemmetadaten 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/de/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/de/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 92fecc6085..d16a95619e 100644 --- a/packages/twenty-docs/l/de/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/de/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ Dokuments und einen nativen Reiter für den Volltext **Editor** für Vorlagen. Eine [view](/l/de/developers/extend/apps/layout/views) ist eine gespeicherte Liste eines bestimmten Objekts. Ein [Navigationsmenüeintrag](/l/de/developers/extend/apps/layout/navigation-menu-items) -bringt diese Ansicht in die Sidebar. +bringt diese Ansicht in die Sidebar. Der Server stellt für jedes Objekt bereits automatisch die Standardansicht "Alle ..." bereit, daher sind die von einer App definierten Ansichten zusätzliche, kuratierte Ansichten. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index b824c05167..059a1945d7 100644 --- 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 @@ -1,16 +1,22 @@ --- -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. +title: Apuntar a metadatos del sistema +description: Resuelve los identificadores universales deterministas de los metadatos de Twenty que se aprovisionan automáticamente en cada objeto, para que tu aplicación pueda hacer referencia a ellos sin codificarlos de forma rígida. 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: +Cada objeto en Twenty incluye **metadatos de sistema** que tú nunca declaras directamente, como un conjunto de campos y una vista de lista principal con sus columnas. El servidor crea todo esto cuando se aprovisiona el objeto, y el conjunto crece a medida que Twenty lo hace. + +Como no lo declaras, no hay ninguna constante `universalIdentifier` que puedas importar. En su lugar, el servidor **deriva** cada identificador de forma determinista, y `twenty-sdk` expone la misma derivación para que tu manifiesto pueda resolver el valor exacto que usa el servidor. + +## Campos del sistema + +Los campos escalares presentes en cada objeto, ninguno de los cuales declaras con [`defineField()`](/l/es/developers/extend/apps/data/extending-objects): `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)? +Entonces, ¿cómo haces referencia a `createdAt` como una columna en una [vista](/l/es/developers/extend/apps/layout/views)? -## Problema +### 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: @@ -18,7 +24,7 @@ Desde Twenty 2.19, el identificador universal de un campo de sistema se **deriva Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## La solución +### La solución `getFieldUniversalIdentifier` está disponible a partir de `twenty-sdk` 2.21. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### 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`: @@ -86,7 +92,7 @@ El mismo id resuelto funciona en cualquier lugar donde se espere un `fieldMetada entradas cambian, y evita desviaciones si la derivación evoluciona en algún momento. -## Campos de relación del sistema +### Campos de relación del sistema `getSystemRelationFieldUniversalIdentifier` está disponible desde `twenty-sdk` @@ -132,18 +138,71 @@ const attachmentTargetRocketFieldId = Como con los campos de sistema escalares, el id resuelto funciona en cualquier lugar donde se espere un `fieldMetadataUniversalIdentifier`. +## Vistas de sistema + + + `getSystemViewUniversalIdentifier` y `getSystemViewFieldUniversalIdentifier` + están disponibles desde `twenty-sdk` 2.26 en adelante y requieren un servidor + Twenty en la versión 2.26 o posterior. + + +El servidor también aprovisiona una **vista de sistema** en cada objeto: la vista de lista principal (`All {objectLabelPlural}`, con clave `ViewKey.INDEX`), con una columna por cada campo visible. Al igual que los campos de relación de sistema, sus identificadores se derivan **sin usar nombres**, por lo que renombrar un objeto o un campo nunca los cambia. + +Usa `getSystemViewUniversalIdentifier` para resolver la vista: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` es la aplicación propietaria del **objeto**, que es la que define el espacio de nombres de la vista. +* `objectUniversalIdentifier` es el objeto que la vista enumera. +* `viewKey` es la clave de vista de sistema, `ViewKey.INDEX` actualmente. + +El id resuelto funciona en cualquier lugar donde se espere un `viewUniversalIdentifier`, como una entrada en la barra lateral de tipo [`NavigationMenuItemType.VIEW`](/l/es/developers/extend/apps/layout/navigation-menu-items). Para simplemente abrir la lista principal de un objeto, es preferible usar `NavigationMenuItemType.OBJECT` con `targetObjectUniversalIdentifier`: no necesita ninguna derivación. + +`getSystemViewFieldUniversalIdentifier` resuelve una sola **columna** en una vista de sistema, a partir de la vista y del campo que muestra: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Observa el primer argumento: una columna está en el espacio de nombres de la aplicación propietaria del **campo que muestra**, no de la que es propietaria de la vista. Un campo que tu aplicación añade a un objeto estándar obtiene su columna derivada bajo tu aplicación, en una vista propiedad de Twenty. + + + Las vistas de sistema y sus columnas son **propiedad del servidor**: resuelve sus identificadores + para hacer referencia a ellas, nunca para declararlas. `key` en + [`defineView()`](/l/es/developers/extend/apps/layout/views) está en desuso y se + ignora, por lo que una vista de manifiesto nunca puede reclamar la clave + `INDEX`, y el servidor ya aprovisiona una columna para cada campo que añades, + de modo que declarar tu propio `defineViewField()` para ese mismo campo en una + vista de sistema entra en conflicto con ella. + + ## 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. +Para un objeto **estándar** de Twenty (Persona, Compañía, Oportunidad, …), no necesitas derivar nada: los identificadores están precalculados como constantes que puedes importar directamente, tanto para campos como para vistas. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Recurre a los ayudantes anteriores 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 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 69031ce37e..04dcc95d2a 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 @@ -4,10 +4,12 @@ description: Incluye vistas guardadas preconfiguradas — orden de columnas, fil icon: list --- -Una **vista** es una configuración guardada de cómo se muestran los registros de un objeto: qué campos aparecen, su orden, si son visibles y qué filtros o grupos se aplican. Usa `defineView()` para incluir vistas preconfiguradas con tu aplicación — normalmente una vista de índice predeterminada para cada objeto personalizado que crees. +Una **vista** es una configuración guardada de cómo se muestran los registros de un objeto: qué campos aparecen, su orden, si son visibles y qué filtros o grupos se aplican. Usa `defineView()` para incluir vistas preconfiguradas con tu aplicación. + +Cada objeto obtiene automáticamente su vista principal de lista (la tabla "All ..." que abre un elemento de navegación `OBJECT`) aprovisionada por el servidor, incluidos los objetos que crea tu aplicación, con una columna por cada campo que declara tu aplicación. Las vistas que defines con `defineView()` son siempre vistas **adicionales** sobre esa vista predeterminada. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Puntos clave * `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`. 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). +* La vista principal de lista del objeto pertenece al servidor: `key` está en desuso y se ignora, por lo que una vista de manifiesto nunca puede reclamarla. Incluye un elemento de navegación `VIEW` si quieres que tu vista esté a un clic de distancia en la barra lateral. +* `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 [Orientación de metadatos 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/es/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/es/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 3554ad17ea..57c8f090bc 100644 --- a/packages/twenty-docs/l/es/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/es/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ y una pestaña de **editor** de texto nativo para plantillas. Una [view](/l/es/developers/extend/apps/layout/views) es una lista guardada de un objeto dado. Un [elemento del menú de navegación](/l/es/developers/extend/apps/layout/navigation-menu-items) -pone esa vista en la barra lateral. +pone esa vista en la barra lateral. El servidor ya aprovisiona automáticamente la vista predeterminada "All ..." de cada objeto, por lo que las vistas que define una aplicación son adicionales y seleccionadas. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index fd9ab179c2..8333656b2d 100644 --- 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 @@ -1,16 +1,22 @@ --- -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. +title: Ciblage des métadonnées système +description: Résolvez les identifiants universels déterministes des métadonnées Twenty provisionnées automatiquement sur chaque objet, afin que votre application puisse s’y référer sans les coder en dur. 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é : +Chaque objet dans Twenty est fourni avec des **métadonnées système** que vous ne déclarez jamais vous‑même, comme un ensemble de champs et une vue principale en liste avec ses colonnes. Le serveur crée l’ensemble de ces éléments lorsque l’objet est provisionné, et cet ensemble s’agrandit au fur et à mesure que Twenty évolue. + +Comme vous ne les déclarez pas, il n’existe pas de constante `universalIdentifier` que vous puissiez importer. À la place, le serveur **dérive** chaque identifiant de manière déterministe, et `twenty-sdk` expose la même dérivation afin que votre manifeste puisse résoudre la valeur exacte utilisée par le serveur. + +## Champs système + +Les champs scalaires présents sur chaque objet, que vous ne déclarez jamais avec [`defineField()`](/l/fr/developers/extend/apps/data/extending-objects) : `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) ? +Alors, comment référencer `createdAt` en tant que colonne dans une [vue](/l/fr/developers/extend/apps/layout/views) ? -## Le problème +### 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 : @@ -18,7 +24,7 @@ Depuis Twenty 2.19, l'identifiant universel d'un champ système est **dérivé d Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## La solution +### La solution `getFieldUniversalIdentifier` est disponible à partir de `twenty-sdk` 2.21. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### 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` : @@ -86,7 +92,7 @@ Le même id résolu fonctionne partout où un `fieldMetadataUniversalIdentifier` entrées changent, et évite les divergences si la dérivation évolue un jour. -## Champs de relation système +### Champs de relation système `getSystemRelationFieldUniversalIdentifier` est disponible dans `twenty-sdk` @@ -132,18 +138,67 @@ const attachmentTargetRocketFieldId = Comme pour les champs système scalaires, l’id résolu fonctionne partout où un `fieldMetadataUniversalIdentifier` est attendu. +## Vues système + + + `getSystemViewUniversalIdentifier` et `getSystemViewFieldUniversalIdentifier` + sont disponibles dans `twenty-sdk` à partir de la version 2.26 et nécessitent + un serveur Twenty en version 2.26 ou ultérieure. + + +Le serveur provisionne également une **vue système** sur chaque objet : la vue principale en liste (`All {objectLabelPlural}`, indexée par `ViewKey.INDEX`), avec une colonne par champ affichable. Comme pour les champs de relation système, leurs identifiants sont dérivés **sans nom**, de sorte que renommer un objet ou un champ ne les modifie jamais. + +Utilisez `getSystemViewUniversalIdentifier` pour la résoudre : + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` correspond à l’application propriétaire de l’**objet**, ce qui sert d’espace de noms pour la vue. +* `objectUniversalIdentifier` est l’objet que la vue répertorie. +* `viewKey` est la clé de vue système, actuellement `ViewKey.INDEX`. + +L’identifiant résolu fonctionne partout où un `viewUniversalIdentifier` est attendu, par exemple pour une entrée de barre latérale [`NavigationMenuItemType.VIEW`](/l/fr/developers/extend/apps/layout/navigation-menu-items). Pour simplement ouvrir la liste principale d’un objet, privilégiez `NavigationMenuItemType.OBJECT` avec `targetObjectUniversalIdentifier` : cela ne nécessite aucune dérivation. + +`getSystemViewFieldUniversalIdentifier` résout une seule **colonne** sur une vue système, à partir de la vue et du champ qu’elle affiche : + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Notez le premier argument : une colonne est placée dans l’espace de noms de l’application propriétaire du **champ qu’elle affiche**, et non de celle propriétaire de la vue. Un champ que votre application ajoute à un objet standard obtient sa colonne dérivée sous votre application, sur une vue appartenant à Twenty. + + + Les vues système et leurs colonnes sont **la propriété du serveur** : résolvez leurs identifiants pour les référencer, jamais pour les déclarer. `key` sur + [`defineView()`](/l/fr/developers/extend/apps/layout/views) est obsolète et ignoré, de sorte qu’une vue de manifeste ne peut jamais revendiquer la clé `INDEX`, et le serveur provisionne déjà une colonne pour chaque champ que vous ajoutez, de sorte que déclarer votre propre + `defineViewField()` pour ce même champ sur une vue système entre en conflit avec celle‑ci. + + ## 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. +Pour un objet Twenty **standard** (Person, Company, Opportunity, …), vous n’avez rien à dériver : les identifiants sont des constantes pré‑calculées que vous pouvez importer directement, à la fois pour les champs et pour les vues. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Utilisez les fonctions utilitaires ci‑dessus 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 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 9b7157bd4a..14166073ab 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 @@ -4,10 +4,12 @@ description: Livrez des vues enregistrées préconfigurées — ordre des colonn icon: list --- -Une **vue** est une configuration enregistrée pour la façon dont les enregistrements d’un objet sont affichés : quels champs apparaissent, leur ordre, s’ils sont visibles, ainsi que les filtres ou groupes appliqués. Utilisez `defineView()` pour livrer des vues préconfigurées avec votre application — généralement une vue d’index par défaut pour chaque objet personnalisé que vous créez. +Une **vue** est une configuration enregistrée pour la façon dont les enregistrements d’un objet sont affichés : quels champs apparaissent, leur ordre, s’ils sont visibles, ainsi que les filtres ou groupes appliqués. Utilisez `defineView()` pour fournir des vues préconfigurées avec votre application. + +Chaque objet obtient automatiquement sa vue de liste principale (le tableau « All ... » ouvert par un élément de navigation `OBJECT`), provisionnée par le serveur — y compris les objets que votre application crée, avec une colonne par champ que votre application déclare. Les vues que vous définissez avec `defineView()` sont toujours des vues **supplémentaires** en plus de cette vue par défaut. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,7 +34,7 @@ export default defineView({ ## Points clés * `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). +* La vue de liste principale de l’objet appartient au serveur : `key` est obsolète et ignorée, de sorte qu’une vue définie dans le manifeste ne peut jamais la revendiquer. Ajoutez un élément de navigation `VIEW` si vous voulez que votre vue soit à un clic dans la barre latérale. * `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/fr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 6482ecbc7e..73467d599b 100644 --- a/packages/twenty-docs/l/fr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/fr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ et un onglet d'onglet de texte natif **éditeur** pour les modèles. Une [vue](/l/fr/developers/extend/apps/layout/views) est une liste enregistrée d’un objet donné. Un [élément du menu de navigation](/l/fr/developers/extend/apps/layout/navigation-menu-items) -place cette vue dans la barre latérale. +place cette vue dans la barre latérale. Le serveur provisionne déjà automatiquement, pour chaque objet, la vue par défaut « Tous ... » ; les vues définies par une application sont donc des vues supplémentaires, sélectionnées. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 632ba85930..51d41e99c8 100644 --- 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 @@ -1,16 +1,22 @@ --- -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. +title: Fare riferimento ai metadati di sistema +description: Risolvi gli identificatori universali deterministici dei metadati che Twenty predispone automaticamente su ogni oggetto, così la tua app può farvi riferimento senza doverli codificare in modo statico. 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: +Ogni oggetto in Twenty include **metadati di sistema** che non dichiari mai direttamente, come ad esempio un insieme di campi e una vista elenco principale con le sue colonne. Il server crea tutto questo quando l'oggetto viene predisposto e l'insieme cresce man mano che Twenty cresce. + +Poiché non lo dichiari, non esiste alcuna costante `universalIdentifier` da importare. Invece, il server **deriva** ogni identificatore in modo deterministico e `twenty-sdk` espone la stessa derivazione affinché il tuo manifest possa risolvere il valore esatto utilizzato dal server. + +## Campi di sistema + +I campi scalari presenti su ogni oggetto, nessuno dei quali dichiari con [`defineField()`](/l/it/developers/extend/apps/data/extending-objects): `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)? +Quindi, come fai a fare riferimento a `createdAt` come colonna in una [vista](/l/it/developers/extend/apps/layout/views)? -## Il problema +### 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: @@ -18,7 +24,7 @@ A partire da Twenty 2.19, l'identificatore universale di un campo di sistema vie Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## La soluzione +### La soluzione `getFieldUniversalIdentifier` è disponibile da `twenty-sdk` 2.21 in poi. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### 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`: @@ -86,7 +92,7 @@ Lo stesso id risolto funziona ovunque ci si aspetti un `fieldMetadataUniversalId input cambiano ed evita discrepanze se la modalità di derivazione dovesse mai evolvere. -## Campi di relazione di sistema +### Campi di relazione di sistema `getSystemRelationFieldUniversalIdentifier` è disponibile da `twenty-sdk` @@ -132,18 +138,68 @@ const attachmentTargetRocketFieldId = Come per i campi di sistema scalari, l'id risolto funziona ovunque ci si aspetti un `fieldMetadataUniversalIdentifier`. +## Viste di sistema + + + `getSystemViewUniversalIdentifier` e `getSystemViewFieldUniversalIdentifier` + sono disponibili da `twenty-sdk` 2.26 in poi e richiedono un server Twenty + dalla versione 2.26 o successiva. + + +Il server predispone anche una **vista di sistema** su ogni oggetto: la vista elenco principale (`All {objectLabelPlural}`, con chiave `ViewKey.INDEX`), con una colonna per ogni campo visualizzabile. Come per i campi di relazione di sistema, i loro identificatori sono derivati senza dipendere dai nomi, quindi rinominare un oggetto o un campo non li modifica mai. + +Usa `getSystemViewUniversalIdentifier` per risolvere la vista: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` è l’applicazione proprietaria dell’**oggetto**, che è ciò in base a cui viene definito lo spazio dei nomi della vista. +* `objectUniversalIdentifier` è l’oggetto che la vista elenca. +* `viewKey` è la chiave della vista di sistema, oggi `ViewKey.INDEX`. + +L’id risolto funziona ovunque ci si aspetti un `viewUniversalIdentifier`, ad esempio in una voce della sidebar [`NavigationMenuItemType.VIEW`](/l/it/developers/extend/apps/layout/navigation-menu-items). Per aprire semplicemente la lista principale di un oggetto, è preferibile usare `NavigationMenuItemType.OBJECT` con `targetObjectUniversalIdentifier`: non richiede alcuna derivazione. + +`getSystemViewFieldUniversalIdentifier` risolve una singola **colonna** su una vista di sistema, a partire dalla vista e dal campo che visualizza: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Nota il primo argomento: una colonna appartiene allo spazio dei nomi dell’applicazione proprietaria del **campo che visualizza**, non di quella proprietaria della vista. Un campo che la tua app aggiunge a un oggetto standard ottiene la propria colonna derivata sotto la tua applicazione, su una vista di proprietà di Twenty. + + + Le viste di sistema e le loro colonne sono **di proprietà del server**: risolvi i loro identificatori per fare riferimento ad esse, mai per dichiararle. `key` su + [`defineView()`](/l/it/developers/extend/apps/layout/views) è deprecato e + ignorato, quindi una vista del manifest non può mai rivendicare la chiave `INDEX`, e il server predispone già una colonna per ogni campo che aggiungi, pertanto dichiarare un tuo + `defineViewField()` per quello stesso campo su una vista di sistema entra in conflitto con essa. + + ## 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. +Per un oggetto **standard** di Twenty (Person, Company, Opportunity, …), non hai bisogno di derivare nulla: gli identificatori sono costanti pre-calcolate che puoi importare direttamente, sia per i campi che per le viste. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Usa gli helper sopra 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 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 1e3ea7108e..acc70792cc 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 @@ -4,10 +4,12 @@ description: Distribuisci viste preconfigurate salvate — ordine delle colonne, icon: list --- -Una **vista** è una configurazione salvata per come vengono visualizzati i record di un oggetto: quali campi compaiono, il loro ordine, se sono visibili e gli eventuali filtri o gruppi applicati. Usa `defineView()` per distribuire viste preconfigurate con la tua app — in genere una vista indice predefinita per ogni oggetto personalizzato che crei. +Una **vista** è una configurazione salvata per come vengono visualizzati i record di un oggetto: quali campi compaiono, il loro ordine, se sono visibili e gli eventuali filtri o gruppi applicati. Usa `defineView()` per fornire viste preconfigurate con la tua app. + +Ogni oggetto ottiene automaticamente la sua vista elenco principale (la tabella "All ..." che un elemento di navigazione `OBJECT` apre) fornita dal server — inclusi gli oggetti che la tua app crea, con una colonna per ogni campo dichiarato dalla tua app. Le viste che definisci con `defineView()` sono sempre viste **aggiuntive** rispetto a quella predefinita. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Punti chiave * `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`. Per fare riferimento a un campo di sistema creato automaticamente come `createdAt`, vedi [Targeting System Fields](/l/it/developers/extend/apps/data/system-fields). +* La vista principale dell'elenco dell'oggetto è di proprietà del server: `key` è deprecato e ignorato, quindi una vista del manifest non potrà mai rivendicarla. Distribuisci un elemento di navigazione `VIEW` se vuoi avere la tua vista a un clic di distanza nella barra laterale. +* `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 Metadata](/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/it/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/it/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 19077d712b..52981e975e 100644 --- a/packages/twenty-docs/l/it/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/it/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ e una scheda **editor** di testo ricco nativo per i modelli. Un [view](/l/it/developers/extend/apps/layout/views) è una lista salvata di un dato oggetto. Una [voce del menu di navigazione](/l/it/developers/extend/apps/layout/navigation-menu-items) -mette quella vista nella barra laterale. +mette quella vista nella barra laterale. Il server predispone automaticamente la vista predefinita "Tutti ..." per ogni oggetto, quindi le viste definite da un'app sono aggiuntive e curate. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 5ff6e21f6d..7177d06380 100644 --- 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 @@ -1,16 +1,22 @@ --- -title: システムフィールドのターゲット指定 -description: ビューやその他のエンティティから `createdAt` や `updatedAt` のような自動作成されるシステムフィールドを、`getFieldUniversalIdentifier` を使って参照します。 +title: システムメタデータのターゲット指定 +description: メタデータ Twenty の決定論的なユニバーサル識別子を、あらゆるオブジェクトに対して自動的に解決し、アプリがハードコーディングせずに参照できるようにします。 icon: gears --- -Twenty のすべてのオブジェクトには、あなたが自分で宣言する必要のない **システムフィールド** のセットがあらかじめ用意されています。 これらは、オブジェクトがプロビジョニングされるときにサーバーによって自動的に作成されます。 +Twenty のすべてのオブジェクトには、フィールドのセットや、そのカラムを持つメインのリストビューなど、あなた自身が宣言する必要のない **システムメタデータ** が付属しています。 オブジェクトがプロビジョニングされるときに、そのすべてをサーバーが作成し、そのセットは Twenty の拡張に合わせて増えていきます。 + +あなたがそれを宣言しないため、インポートできる `universalIdentifier` 定数は存在しません。 その代わりに、サーバーはそれぞれの識別子を決定論的に**導出**し、`twenty-sdk` が同じ導出処理を公開することで、マニフェストがサーバーで使用される正確な値を解決できるようにします。 + +## システムフィールド + +すべてのオブジェクトに存在し、いずれも [`defineField()`](/l/ja/developers/extend/apps/data/extending-objects) で宣言しないスカラー フィールドは次のとおりです。 `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` をカラムとしてどのように参照すればよいのでしょうか。 +では、[view](/l/ja/developers/extend/apps/layout/views) で `createdAt` をカラムとしてどのように参照すればよいのでしょうか。 -## 問題 +### 問題 Twenty 2.19 以降、システムフィールドのユニバーサル識別子は、アプリケーションのユニバーサル識別子、オブジェクトのユニバーサル識別子、およびフィールド名という 3 つの入力からサーバーによって **決定的に導出** されます。 id を独自に作成してハードコードしても機能しません。サーバー上のどの値とも一致せず、同期時にそのぶら下がった参照は拒否されます。 @@ -18,7 +24,7 @@ Twenty 2.19 以降、システムフィールドのユニバーサル識別子 Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## 解決策 +### 解決策 `getFieldUniversalIdentifier` は `twenty-sdk` 2.21 以降で利用可能です。 @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `objectUniversalIdentifier` は、そのフィールドが属するオブジェクトの識別子です。 * `name` はシステムフィールド名であり、上に挙げた値のいずれかです。 -## 例: ビュー内の createdAt カラム +### 例: ビュー内の createdAt カラム 典型的なケースは、カスタムオブジェクトの 1 つのビューに `createdAt` カラムを追加することです。 フィールド id を解決し、他の `fieldMetadataUniversalIdentifier` と同様にそれを参照します。 @@ -83,7 +89,7 @@ export default defineView({ id は解決して、ハードコードしないでください。 サーバーはその値をアプリケーション id、オブジェクト id、フィールド名から導出するため、`getFieldUniversalIdentifier` を呼び出すことで、それらの入力が変更された場合でも参照を正しい状態に保ち、導出方法が将来変わった場合のずれも防ぐことができます。 -## システムリレーションフィールド +### システムリレーションフィールド `getSystemRelationFieldUniversalIdentifier` は `twenty-sdk` @@ -129,18 +135,63 @@ const attachmentTargetRocketFieldId = スカラーのシステムフィールドと同様に、解決された ID は `fieldMetadataUniversalIdentifier` が想定されるあらゆる場所で使用できます。 +## システムビュー + + + `getSystemViewUniversalIdentifier` と `getSystemViewFieldUniversalIdentifier` は `twenty-sdk` 2.26 以降で利用可能であり、バージョン 2.26 以降の Twenty サーバーが必要です。 + + +サーバーは、すべてのオブジェクトに対して **システムビュー** もプロビジョニングします。つまり、表示可能なフィールドごとに 1 つのカラムを持つメインのリストビュー（`ViewKey.INDEX` をキーとし、`All {objectLabelPlural}`）です。 システムリレーションフィールドと同様に、それらの識別子は **名前に依存しない** 形で導出されるため、オブジェクトやフィールドの名前を変更しても識別子は変わりません。 + +ビューを解決するには、`getSystemViewUniversalIdentifier` を使用します。 + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` は **オブジェクト** を所有しているアプリケーションであり、ビューが名前空間分割されている単位です。 +* `objectUniversalIdentifier` は、そのビューがリストするオブジェクトです。 +* `viewKey` はシステムビューのキーで、現時点では `ViewKey.INDEX` です。 + +解決された ID は、[`NavigationMenuItemType.VIEW`](/l/ja/developers/extend/apps/layout/navigation-menu-items) のサイドバーエントリなど、`viewUniversalIdentifier` が必要とされるあらゆる場所で使用できます。 オブジェクトのメインリストを単に開くだけであれば、導出が不要な `NavigationMenuItemType.OBJECT` と `targetObjectUniversalIdentifier` を優先して使用してください。 + +`getSystemViewFieldUniversalIdentifier` は、ビューとそのビューが表示するフィールドから、システムビュー上の 1 つの**カラム**を解決します。 + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +最初の引数に注目してください。カラムは、そのビューではなく、**表示しているフィールド** を所有するアプリケーションで名前空間分割されます。 あなたのアプリが標準オブジェクトに追加したフィールドは、Twenty が所有するビュー上で、そのアプリケーションの名前空間の下にカラムが導出されます。 + + + システムビューとそのカラムは **サーバー所有** です。これらの識別子は、宣言ではなく参照のためにのみ解決してください。 [`defineView()`](/l/ja/developers/extend/apps/layout/views) の `key` は非推奨で無視されます。そのため、マニフェストのビューが `INDEX` キーを主張することはできません。また、サーバーはあなたが追加するすべてのフィールドに対してすでにカラムをプロビジョニングしているため、同じフィールドについてシステムビュー上で独自の `defineViewField()` を宣言すると競合が発生します。 + + ## 標準の Twenty オブジェクト -**標準** の Twenty オブジェクト（Person、Company、Opportunity など）の場合、何も導出する必要はありません。システムフィールドの識別子はあらかじめ計算された定数として用意されており、直接インポートできます。 +**標準** の 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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier ``` -[`defineObject()`](/l/ja/developers/extend/apps/data/objects) で **あなたのアプリ** が定義するオブジェクトのように、そのような定数が存在しない場合にこそ、`getFieldUniversalIdentifier` を使用してください。 +[`defineObject()`](/l/ja/developers/extend/apps/data/objects) で **あなたのアプリ** が定義するオブジェクトのように、そのような定数が存在しない場合には、ここまでで紹介したヘルパーを使用してください。 `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 5dd6cb6b2c..1472a24152 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 @@ -4,10 +4,12 @@ description: アプリのオブジェクト向けに、列の順序、フィル icon: list --- -**ビュー**とは、オブジェクトのレコードをどのように表示するかについての保存された設定です。どのフィールドを表示するか、その順序、表示・非表示、および適用されるフィルターやグループなどを含みます。 `defineView()` を使用して、アプリにあらかじめ設定されたビューを組み込みます。通常は、作成する各カスタムオブジェクトに対してデフォルトのインデックスビューを用意します。 +**ビュー**とは、オブジェクトのレコードをどのように表示するかについての保存された設定です。どのフィールドを表示するか、その順序、表示・非表示、および適用されるフィルターやグループなどを含みます。 `defineView()` を使用して、事前設定済みのビューをアプリに同梱します。 + +すべてのオブジェクトには、サーバーによってプロビジョニングされるメインのリストビュー（`OBJECT` ナビゲーション項目で開かれる「All ...」テーブル）が自動的に用意されます。これには、アプリが作成するオブジェクトも含まれ、アプリが宣言する各フィールドごとに 1 列が用意されます。 `defineView()` で定義したビューは、そのデフォルトビューに加えて常に**追加の**ビューとして扱われます。 ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,7 +34,7 @@ export default defineView({ ## 主なポイント * `objectUniversalIdentifier` は、このビューを適用するオブジェクトを指定します。 定義したカスタムオブジェクトでも、Twenty の標準オブジェクトでも可能です。 -* `key: ViewKey.INDEX` は、そのビューがオブジェクトのメイン一覧ビュー（`OBJECT` ナビゲーション項目を開いたときに表示されるビュー）であることを示します。 +* オブジェクトのメインのリストビューはサーバー所有です。`key` は非推奨で無視されるため、マニフェストビューがそれを取得することはできません。 サイドバーから 1 クリックでビューにアクセスできるようにしたい場合は、`VIEW` ナビゲーション項目を追加してください。 * `fields` は、どの列をどの順序で表示するかを制御します。 各フィールドは `fieldMetadataUniversalIdentifier` を参照します。 `createdAt` などの自動作成システムフィールドの参照方法については、[システムフィールドのターゲット指定](/l/ja/developers/extend/apps/data/system-fields)を参照してください。 * さらに高度な構成のために、`filters`、`filterGroups`、`sorts`、`groups`、`fieldGroups` も定義できます。 * 同じオブジェクトに複数のビューがある場合、`position` が表示順を制御します。 diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 223fc184ee..05b36b05b4 100644 --- a/packages/twenty-docs/l/ja/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/ja/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -10,17 +10,16 @@ description: ビュー、サイドバーナビゲーション、コマンド、 [view](/l/ja/developers/extend/apps/layout/views) は、指定されたオブジェクトのリストです。 [navigation menu item](/l/ja/developers/extend/apps/layout/navigation-menu-items) -はそのビューをサイドバーに配置します。 +はそのビューをサイドバーに配置します。 サーバーはすでに各オブジェクトのデフォルトの「All ...」ビューを自動で用意しているため、アプリが定義するビューは追加の厳選されたビューとなります。 ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 409055c86a..e1ea42b419 100644 --- 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 @@ -1,16 +1,22 @@ --- -title: 시스템 필드 대상 지정 -description: 뷰와 다른 엔티티에서 `getFieldUniversalIdentifier`를 사용하여 `createdAt` 또는 `updatedAt` 같은 자동 생성 시스템 필드를 참조하세요. +title: 시스템 메타데이터 대상 지정 +description: 모든 객체에서 Twenty 메타데이터의 결정론적 범용 식별자를 자동으로 해석하므로, 앱이 하드코딩 없이 이를 참조할 수 있습니다. icon: gears --- -Twenty의 모든 객체에는 여러분이 직접 선언하지 않아도 되는 **시스템 필드** 세트가 함께 제공됩니다. 이 필드들은 객체가 프로비저닝될 때 서버에 의해 자동으로 생성됩니다: +Twenty의 모든 객체에는 필드 집합과 열이 포함된 기본 목록 보기처럼, 직접 선언하지 않아도 되는 **시스템 메타데이터**가 함께 제공됩니다. 객체가 프로비저닝될 때 서버가 이러한 모든 요소를 생성하며, Twenty가 확장됨에 따라 해당 집합도 함께 증가합니다. + +직접 이를 선언하지 않기 때문에, 가져올 수 있는 `universalIdentifier` 상수가 없습니다. 대신 서버는 각 식별자를 결정론적으로 **도출**하며, `twenty-sdk`는 동일한 도출 방식을 제공하여 매니페스트가 서버가 사용하는 정확한 값을 해석할 수 있게 합니다. + +## 시스템 필드 + +모든 객체에 존재하는 스칼라 필드로, [`defineField()`](/l/ko/developers/extend/apps/data/extending-objects)로 선언하지 않는 필드들입니다: `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`을 컬럼으로 어떻게 참조할 수 있을까요? +그렇다면 [view](/l/ko/developers/extend/apps/layout/views)에서 `createdAt`을 컬럼으로 어떻게 참조할 수 있을까요? -## 문제 +### 문제 Twenty 2.19부터 시스템 필드의 유니버설 식별자는 애플리케이션 유니버설 식별자, 객체 유니버설 식별자, 필드 이름이라는 세 가지 입력값으로부터 서버에서 결정론적으로 도출됩니다. id를 임의로 만들고 하드코딩해도 동작하지 않습니다. 서버에서 어떤 것과도 일치하지 않으며, 동기화에서 이러한 끊어진 참조를 거부합니다: @@ -18,7 +24,7 @@ Twenty 2.19부터 시스템 필드의 유니버설 식별자는 애플리케이 Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## 해결책 +### 해결책 `getFieldUniversalIdentifier`는 `twenty-sdk` 2.21부터 사용할 수 있습니다. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `objectUniversalIdentifier`는 필드가 속한 객체의 식별자입니다. * `name`은 시스템 필드 이름이며, 위에 나열된 값들 중 하나입니다. -## 예시: 뷰의 createdAt 컬럼 +### 예시: 뷰의 createdAt 컬럼 일반적인 사용 사례는 커스텀 객체 중 하나의 뷰에 `createdAt` 컬럼을 추가하는 것입니다. 필드 id를 해석한 다음, 다른 `fieldMetadataUniversalIdentifier`와 동일한 방식으로 참조하세요: @@ -84,7 +90,7 @@ export default defineView({ `getFieldUniversalIdentifier`를 호출하면 이 입력값들이 변경되더라도 참조를 올바르게 유지할 수 있고, 도출 방식이 바뀌더라도 드리프트를 방지할 수 있습니다. -## 시스템 관계 필드 +### 시스템 관계 필드 `getSystemRelationFieldUniversalIdentifier`는 `twenty-sdk` @@ -130,18 +136,63 @@ const attachmentTargetRocketFieldId = 스칼라 시스템 필드와 마찬가지로, 해결된 ID는 `fieldMetadataUniversalIdentifier`가 필요한 곳이면 어디서든 사용할 수 있습니다. +## 시스템 뷰 + + + `getSystemViewUniversalIdentifier`와 `getSystemViewFieldUniversalIdentifier`는 `twenty-sdk` 2.26부터 사용 가능하며, Twenty 서버 버전 2.26 이상이 필요합니다. + + +서버는 또한 모든 객체에 대해 **시스템 뷰**를 프로비저닝합니다. 즉, 표시 가능한 각 필드마다 하나의 열을 가진 기본 목록 보기(`All {objectLabelPlural}`, `ViewKey.INDEX`를 키로 사용)을 제공합니다. 시스템 관계 필드와 마찬가지로, 이들의 식별자는 **이름에 의존하지 않고** 도출되므로, 객체나 필드의 이름을 변경해도 식별자는 절대 바뀌지 않습니다. + +뷰를 해석하려면 `getSystemViewUniversalIdentifier`를 사용하세요: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier`는 **객체**를 소유하는 애플리케이션으로, 뷰의 네임스페이스 기준이 됩니다. +* `objectUniversalIdentifier`는 뷰가 목록으로 표시하는 객체입니다. +* `viewKey`는 시스템 뷰 키이며, 현재는 `ViewKey.INDEX`입니다. + +해석된 ID는 [`NavigationMenuItemType.VIEW`](/l/ko/developers/extend/apps/layout/navigation-menu-items) 사이드바 항목처럼, `viewUniversalIdentifier`가 필요한 모든 곳에서 사용할 수 있습니다. 객체의 기본 목록만 단순히 열고 싶다면, 파생 과정이 필요 없는 `targetObjectUniversalIdentifier`와 함께 `NavigationMenuItemType.OBJECT`를 사용하는 것이 좋습니다. + +`getSystemViewFieldUniversalIdentifier`는 뷰와 해당 뷰에 표시되는 필드 정보를 기반으로 시스템 뷰의 개별 **열**을 해석합니다: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +첫 번째 인자에 주목하세요. 열은 뷰를 소유한 애플리케이션이 아니라, **표시되는 필드를 소유한** 애플리케이션을 기준으로 네임스페이스가 구분됩니다. 앱이 표준 객체에 추가한 필드는, Twenty가 소유한 뷰 위에 있지만 해당 열은 앱이 소유한 애플리케이션 네임스페이스 하에서 도출됩니다. + + + 시스템 뷰와 그 열은 **서버 소유**입니다. 이들을 참조하기 위해서만 식별자를 해석해야 하며, 직접 선언하는 용도로는 사용해서는 안 됩니다. [`defineView()`](/l/ko/developers/extend/apps/layout/views)의 `key`는 더 이상 사용되지 않으며 무시되므로, 매니페스트 뷰가 `INDEX` 키를 차지할 수 없습니다. 또한 서버는 앱이 추가하는 모든 필드에 대해 이미 열을 프로비저닝하므로, 시스템 뷰에서 동일한 필드에 대해 별도의 `defineViewField()`를 선언하면 서버가 생성한 열과 충돌합니다. + + ## 표준 Twenty 객체 -**표준** Twenty 객체(Person, Company, Opportunity 등)의 경우 어떤 것도 도출할 필요가 없습니다. 시스템 필드 식별자는 미리 계산된 상수이므로 바로 import해서 사용할 수 있습니다. +**표준** 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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier ``` -[`defineObject()`](/l/ko/developers/extend/apps/data/objects)로 **앱에서 직접 정의한** 객체처럼, 그러한 상수가 존재하지 않는 경우에 `getFieldUniversalIdentifier`를 사용하세요. +[`defineObject()`](/l/ko/developers/extend/apps/data/objects)로 **앱에서 직접 정의한** 객체처럼, 그러한 상수가 존재하지 않는 경우에는 위에 소개한 헬퍼들을 사용하세요. `name`은 시스템 필드가 아니라 **기본(default)** 필드입니다. 이 필드는 자체 하드코딩된 유니버설 식별자를 유지하며, 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 fd5e231c93..2ebdf5d8c5 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 @@ -4,10 +4,12 @@ description: 앱의 객체에 대해 열 순서, 필터, 그룹이 미리 구성 icon: list --- -**보기**는 객체 레코드가 어떻게 표시될지에 대한 저장된 구성입니다. 어떤 필드가 표시되는지, 그 순서, 표시 여부, 적용된 필터나 그룹 등을 정의합니다. `defineView()`를 사용해 앱에 미리 구성된 보기를 포함할 수 있습니다. 일반적으로 생성하는 각 커스텀 객체마다 기본 목록 보기를 제공합니다. +**보기**는 객체 레코드가 어떻게 표시될지에 대한 저장된 구성입니다. 어떤 필드가 표시되는지, 그 순서, 표시 여부, 적용된 필터나 그룹 등을 정의합니다. 앱과 함께 미리 구성된 뷰를 제공하려면 `defineView()`를 사용하세요. + +모든 개체는 서버에서 기본 목록 뷰(`OBJECT` 탐색 항목이 여는 "All ..." 테이블)를 자동으로 프로비저닝됩니다. 여기에는 앱이 생성하는 개체도 포함되며, 앱이 선언한 각 필드당 하나의 열이 생성됩니다. `defineView()`로 정의한 뷰는 항상 해당 기본 뷰 위에 추가되는 **추가** 뷰입니다. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## 핵심 요점 * `objectUniversalIdentifier`는 이 뷰가 적용되는 객체를 지정합니다. 이 객체는 사용자가 정의한 커스텀 객체일 수도 있고, 표준 Twenty 객체일 수도 있습니다. -* `key: ViewKey.INDEX`는 뷰를 객체의 기본 목록 보기( `OBJECT` 내비게이션 항목이 여는 보기)로 표시합니다. -* `fields`는 어떤 열을 어떤 순서로 표시할지를 제어합니다. 각 필드는 `fieldMetadataUniversalIdentifier`를 참조합니다. 자동 생성된 시스템 필드(예: `createdAt`)를 참조하는 방법은 [시스템 필드 대상으로 지정하기](/l/ko/developers/extend/apps/data/system-fields)를 참조하세요. +* 개체의 기본 목록 뷰는 서버 소유입니다. `key` 는 더 이상 사용되지 않으며 무시되므로 매니페스트 뷰가 이를 소유할 수 없습니다. 사이드바에서 한 번의 클릭으로 뷰에 접근할 수 있게 하려면 `VIEW` 탐색 항목을 제공하십시오. +* `fields`는 어떤 열을 어떤 순서로 표시할지를 제어합니다. 각 필드는 `fieldMetadataUniversalIdentifier`를 참조합니다. 자동 생성된 시스템 필드(예: `createdAt`)를 참조하는 방법은 [시스템 메타데이터 대상으로 지정하기](/l/ko/developers/extend/apps/data/system-fields)를 참조하세요. * 또한 더 고급 구성을 위해 `filters`, `filterGroups`, `sorts`, `groups`, `fieldGroups`를 선언할 수 있습니다. * `position`은 동일한 객체에 여러 뷰가 있을 때의 정렬 순서를 제어합니다. diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index b4866422f8..ad03119209 100644 --- a/packages/twenty-docs/l/ko/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/ko/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -9,17 +9,16 @@ description: 뷰, 사이드바 내비게이션, 커맨드, 그리고 프런트 ## 뷰와 내비게이션 [뷰](/l/ko/developers/extend/apps/layout/views)는 특정 객체에 대해 저장된 목록입니다. -[내비게이션 메뉴 항목](/l/ko/developers/extend/apps/layout/navigation-menu-items)은 해당 뷰를 사이드바에 배치합니다. +[내비게이션 메뉴 항목](/l/ko/developers/extend/apps/layout/navigation-menu-items)은 해당 뷰를 사이드바에 배치합니다. 서버는 이미 각 객체의 기본 "All ..." 보기를 자동으로 생성하므로, 앱이 정의하는 보기는 추가로 제공되는 선별된 보기입니다. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index e2b056e476..9b758dcbc0 100644 --- 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 @@ -1,16 +1,22 @@ --- -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. +title: Metadados de sistema de direcionamento +description: Resolva os identificadores universais determinísticos dos metadados que o Twenty provisiona automaticamente em cada objeto, para que seu app possa referenciá‑los sem hardcode. 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: +Todo objeto no Twenty vem com **metadados de sistema** que você nunca declara explicitamente, como um conjunto de campos e uma visualização principal de lista com suas colunas. O servidor cria tudo isso quando o objeto é provisionado, e o conjunto cresce conforme o Twenty cresce. + +Como você não o declara, não existe nenhuma constante `universalIdentifier` para você importar. Em vez disso, o servidor **deriva** cada identificador de forma determinística, e o `twenty-sdk` expõe a mesma derivação para que seu manifesto possa resolver o valor exato que o servidor usa. + +## Campos do sistema + +Os campos escalares presentes em todo objeto, nenhum dos quais você declara com [`defineField()`](/l/pt/developers/extend/apps/data/extending-objects): `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)? +Então, como você referencia `createdAt` como uma coluna em uma [visualização](/l/pt/developers/extend/apps/layout/views)? -## O Problema +### 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: @@ -18,7 +24,7 @@ Desde o Twenty 2.19, o identificador universal de um campo de sistema é **deriv Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## A Solução +### A Solução `getFieldUniversalIdentifier` está disponível a partir do `twenty-sdk` 2.21. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### 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`: @@ -86,7 +92,7 @@ O mesmo id resolvido funciona em qualquer lugar onde se espera um `fieldMetadata entradas mudem, e evita divergências se a derivação evoluir no futuro. -## Campos de relação do sistema +### Campos de relação do sistema `getSystemRelationFieldUniversalIdentifier` está disponível a partir da versão 2.23 do `twenty-sdk` e requer um servidor Twenty na versão 2.23 ou posterior. @@ -131,18 +137,69 @@ const attachmentTargetRocketFieldId = Assim como acontece com campos de sistema escalares, o id resolvido funciona em qualquer lugar em que um `fieldMetadataUniversalIdentifier` é esperado. +## Visualizações de sistema + + + `getSystemViewUniversalIdentifier` e `getSystemViewFieldUniversalIdentifier` + estão disponíveis a partir da versão 2.26 do `twenty-sdk` e requerem um servidor Twenty na versão 2.26 ou posterior. + + +O servidor também provisiona uma **visualização de sistema** em cada objeto: a visualização principal de lista (`All {objectLabelPlural}`, com chave `ViewKey.INDEX`), com uma coluna por campo exibível. Assim como os campos de relação de sistema, seus identificadores são derivados **sem usar nomes**, então renomear um objeto ou um campo nunca os altera. + +Use `getSystemViewUniversalIdentifier` para resolvê‑la: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` é o aplicativo proprietário do **objeto**, pelo qual a visualização é colocada em namespace. +* `objectUniversalIdentifier` é o objeto que a visualização lista. +* `viewKey` é a chave da visualização de sistema, hoje `ViewKey.INDEX`. + +O id resolvido funciona em qualquer lugar em que um `viewUniversalIdentifier` seja esperado, como uma entrada de barra lateral [`NavigationMenuItemType.VIEW`](/l/pt/developers/extend/apps/layout/navigation-menu-items). Para simplesmente abrir a lista principal de um objeto, prefira `NavigationMenuItemType.OBJECT` com `targetObjectUniversalIdentifier`: isso não precisa de derivação. + +`getSystemViewFieldUniversalIdentifier` resolve uma única **coluna** em uma visualização de sistema, a partir da visualização e do campo que ela exibe: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Observe o primeiro argumento: uma coluna é colocada em namespace pelo aplicativo proprietário do **campo que ela exibe**, não pelo que é proprietário da visualização. Um campo que seu app adiciona a um objeto padrão tem sua coluna derivada sob o seu aplicativo, em uma visualização de propriedade do Twenty. + + + As visualizações de sistema e suas colunas são **de propriedade do servidor**: resolva seus identificadores + para referenciá‑las, nunca para declará‑las. `key` em + [`defineView()`](/l/pt/developers/extend/apps/layout/views) está obsoleto e + é ignorado, portanto uma visualização de manifesto nunca pode reivindicar a chave `INDEX`, e o servidor + já provisiona uma coluna para cada campo que você adiciona, então declarar seu próprio + `defineViewField()` para esse mesmo campo em uma visualização de sistema entra em conflito com ela. + + ## 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. +Para um objeto **padrão** do Twenty (Person, Company, Opportunity, …), você não precisa derivar nada: os identificadores são constantes pré‑computadas que você pode importar diretamente, tanto para campos quanto para visualizações. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Use os helpers acima quando o objeto for 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 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 4cf744e174..9711341b86 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 @@ -4,10 +4,12 @@ description: Distribua visualizações salvas e pré-configuradas — ordem das icon: list --- -Uma **visualização** é uma configuração salva de como os registros de um objeto são exibidos: quais campos aparecem, sua ordem, se estão visíveis e quaisquer filtros ou grupos aplicados. Use `defineView()` para distribuir visualizações pré-configuradas com seu app — normalmente uma visualização de índice padrão para cada objeto personalizado que você cria. +Uma **visualização** é uma configuração salva de como os registros de um objeto são exibidos: quais campos aparecem, sua ordem, se estão visíveis e quaisquer filtros ou grupos aplicados. Use `defineView()` para enviar visualizações pré-configuradas com seu app. + +Cada objeto recebe automaticamente sua principal visualização de lista (a tabela "All ..." que um item de navegação `OBJECT` abre), provisionada pelo servidor — incluindo os objetos que seu app cria, com uma coluna por campo que seu app declara. As visualizações que você define com `defineView()` são sempre visualizações **adicionais** em cima daquela padrão. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Pontos-chave * `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`. 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). +* A visualização principal de lista do objeto é de propriedade do servidor: `key` está obsoleto e é ignorado, portanto uma visualização definida no manifesto nunca poderá reivindicá-la. Envie um item de navegação `VIEW` se quiser que sua visualização fique a um clique de distância na barra lateral. +* `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 metadados 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/pt/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index fbe8e9e6d4..c0431c59ac 100644 --- a/packages/twenty-docs/l/pt/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/pt/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ e uma guia de **editor** nativa para templates. A [view](/l/pt/developers/extend/apps/layout/views) é uma lista salva de um determinado objeto. Um [item de menu de navegação](/l/pt/developers/extend/apps/layout/navigation-menu-items) -coloca essa visualização na barra lateral. +coloca essa visualização na barra lateral. O servidor já provisiona automaticamente a visualização padrão "All ..." de cada objeto, portanto, as visualizações que um app define são adicionais e selecionadas. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 9bc8ec2c3f..83c34c4c94 100644 --- 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 @@ -1,16 +1,22 @@ --- -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. +title: Metadate de sistem pentru țintire +description: Rezolvă identificatorii universali determinați ai metadatelor Twenty pentru provizionări în mod automat pe fiecare obiect, astfel încât aplicația ta să le poată referenția fără hardcodare. 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: +Fiecare obiect din Twenty vine cu **metadate de sistem** pe care nu le declari niciodată tu însuți, cum ar fi un set de câmpuri și o vizualizare principală de listă cu coloanele sale. Serverul le creează pe toate atunci când obiectul este provizionat, iar setul crește pe măsură ce Twenty evoluează. + +Deoarece nu îl declari, nu există nicio constantă `universalIdentifier` pe care să o imporți. În schimb, serverul **derivează** fiecare identificator într-un mod determinist, iar `twenty-sdk` expune aceeași derivare astfel încât manifestul tău să poată rezolva exact valoarea pe care o folosește serverul. + +## Câmpuri de sistem + +Câmpurile scalare prezente pe fiecare obiect, niciunul dintre ele declarat de tine cu [`defineField()`](/l/ro/developers/extend/apps/data/extending-objects): `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)? +Deci cum faci referire la `createdAt` ca o coloană într-o [vizualizare](/l/ro/developers/extend/apps/layout/views)? -## Problema +### 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: @@ -18,7 +24,7 @@ Deoarece nu declari aceste câmpuri cu [`defineField()`](/l/ro/developers/extend Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## Soluția +### Soluția `getFieldUniversalIdentifier` este disponibil începând cu `twenty-sdk` 2.21. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### 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`: @@ -86,7 +92,7 @@ Același id calculat funcționează oriunde este așteptat un `fieldMetadataUniv intrări se schimbă și evită divergența dacă metoda de derivare evoluează vreodată. -## Câmpuri de relație de sistem +### Câmpuri de relație de sistem `getSystemRelationFieldUniversalIdentifier` este disponibil începând cu versiunea 2.23 a `twenty-sdk` și necesită un server Twenty pe versiunea 2.23 sau o versiune ulterioară. @@ -131,18 +137,70 @@ const attachmentTargetRocketFieldId = Ca și în cazul câmpurilor de sistem scalare, id-ul rezolvat funcționează oriunde este așteptat un `fieldMetadataUniversalIdentifier`. +## Vizualizări de sistem + + + `getSystemViewUniversalIdentifier` și `getSystemViewFieldUniversalIdentifier` + sunt disponibile începând cu versiunea 2.26 a `twenty-sdk` și necesită un server Twenty pe + versiunea 2.26 sau o versiune ulterioară. + + +Serverul provizionează, de asemenea, o **vizualizare de sistem** pe fiecare obiect: vizualizarea principală de listă (`All {objectLabelPlural}`, indexată prin `ViewKey.INDEX`), cu câte o coloană pentru fiecare câmp afișabil. La fel ca în cazul câmpurilor de relație de sistem, identificatorii lor sunt derivați **fără nume**, astfel încât redenumirea unui obiect sau a unui câmp nu îi schimbă niciodată. + +Folosește `getSystemViewUniversalIdentifier` pentru a rezolva vizualizarea: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` este aplicația care deține **obiectul**, ceea ce reprezintă spațiul de nume pentru vizualizare. +* `objectUniversalIdentifier` este obiectul pe care îl listează vizualizarea. +* `viewKey` este cheia vizualizării de sistem, astăzi `ViewKey.INDEX`. + +ID-ul rezolvat funcționează oriunde este așteptat un `viewUniversalIdentifier`, cum ar fi o intrare în bara laterală [`NavigationMenuItemType.VIEW`](/l/ro/developers/extend/apps/layout/navigation-menu-items). Pentru a deschide pur și simplu lista principală a unui obiect, preferă `NavigationMenuItemType.OBJECT` cu `targetObjectUniversalIdentifier`: nu are nevoie de derivare. + +`getSystemViewFieldUniversalIdentifier` rezolvă o singură **coloană** dintr-o vizualizare de sistem, pornind de la vizualizare și câmpul pe care îl afișează: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +Observă primul argument: o coloană este plasată în spațiul de nume al aplicației care deține **câmpul pe care îl afișează**, nu al celei care deține vizualizarea. Un câmp pe care aplicația ta îl adaugă la un obiect standard își obține coloana derivată sub aplicația ta, pe o vizualizare deținută de Twenty. + + + Vizualizările de sistem și coloanele lor sunt **deținute de server**: rezolvă-le identificatorii + pentru a le referenția, niciodată pentru a le declara. `key` pe + [`defineView()`](/l/ro/developers/extend/apps/layout/views) este depreciat și + ignorat, astfel încât o vizualizare din manifest nu poate revendica niciodată cheia `INDEX`, iar serverul + provizionează deja o coloană pentru fiecare câmp pe care îl adaugi, deci declararea propriului tău + `defineViewField()` pentru același câmp într-o vizualizare de sistem intră în conflict cu aceasta. + + ## 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. +Pentru un obiect Twenty **standard** (Person, Company, Opportunity, …), nu trebuie să derivezi nimic: identificatorii sunt constante pre-calculate pe care le poți importa direct, atât pentru câmpuri, cât și pentru vizualizări. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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ă. +Apelează la helper-ele de mai sus 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 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 cdbb2985ff..fca77f3f1a 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 @@ -4,10 +4,12 @@ description: Livrați vizualizări salvate preconfigurate — ordinea coloanelor icon: list --- -O **vizualizare** este o configurație salvată pentru modul în care sunt afișate înregistrările unui obiect: ce câmpuri apar, ordinea lor, dacă sunt vizibile și ce filtre sau grupuri sunt aplicate. Folosiți `defineView()` pentru a livra vizualizări preconfigurate împreună cu aplicația dvs. — de obicei o vizualizare index implicită pentru fiecare obiect personalizat pe care îl creați. +O **vizualizare** este o configurație salvată pentru modul în care sunt afișate înregistrările unui obiect: ce câmpuri apar, ordinea lor, dacă sunt vizibile și ce filtre sau grupuri sunt aplicate. Utilizați `defineView()` pentru a livra vizualizări preconfigurate împreună cu aplicația. + +Fiecărui obiect i se atribuie automat vizualizarea principală de listă (tabelul „All ...” pe care îl deschide un element de navigare `OBJECT`) furnizată de server — inclusiv obiectele pe care le creează aplicația dvs., cu o coloană pentru fiecare câmp declarat de aplicația dvs. Vizualizările pe care le definiți cu `defineView()` sunt întotdeauna vizualizări **suplimentare** pe lângă cea implicită. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Puncte cheie * `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`. 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). +* Vizualizarea principală a listei obiectului aparține serverului: `key` este învechit și este ignorat, astfel încât o vizualizare din manifest nu o poate revendica niciodată. Livrați un element de navigare `VIEW` dacă doriți ca vizualizarea dvs. să fie la un singur clic distanță în bara laterală. +* `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 metadatelor 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/ro/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 4498534a7d..54f34f7a3b 100644 --- a/packages/twenty-docs/l/ro/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/ro/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -13,17 +13,16 @@ description: Vizualizări, navigare bară laterală, o comandă și componente f Un [view](/l/ro/developers/extend/apps/layout/views) este o listă salvată a unui obiect dat. Un [element meniu de navigare](/l/ro/developers/extend/apps/layout/navigation-menu-items) -introduce această vizualizare în bara laterală. +introduce această vizualizare în bara laterală. Serverul creează deja automat pentru fiecare obiect vizualizarea implicită "All ...", astfel încât vizualizările pe care le definește o aplicație sunt unele suplimentare, selectate cu atenție. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 7bf37a92bd..5efe425290 100644 --- 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 @@ -1,16 +1,22 @@ --- -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." +title: Sistem Meta Verilerini Hedefleme +description: Twenty meta verilerinin deterministik evrensel tanımlayıcılarını her nesnede otomatik olarak çözümleyin; böylece uygulamanız bunlara, değerleri kodun içine gömmek zorunda kalmadan başvurabilir. 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: +Twenty içindeki her nesne, kendi başınıza asla bildirmediğiniz **sistem meta verileriyle** birlikte gelir; bir alan kümesi ve sütunlarıyla birlikte ana liste görünümü gibi. Sunucu, nesne sağlandığında bunların hepsini oluşturur ve Twenty büyüdükçe bu küme de büyür. + +Siz bunu bildirmediğiniz için, içe aktarabileceğiniz bir `universalIdentifier` sabiti yoktur. Bunun yerine, sunucu her tanımlayıcıyı deterministik olarak **türetir** ve `twenty-sdk`, bildirim dosyanızın sunucunun kullandığı kesin değeri çözümleyebilmesi için aynı türetmeyi dışa açar. + +## Sistem Alanları + +Her nesnede bulunan, hiçbirini [`defineField()`](/l/tr/developers/extend/apps/data/extending-objects) ile bildirmediğiniz skaler alanlar: `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? +Peki bir [görünümde](/l/tr/developers/extend/apps/layout/views) `createdAt` alanına sütun olarak nasıl referans verirsiniz? -## Sorun +### 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: @@ -18,7 +24,7 @@ Twenty 2.19'dan beri, bir sistem alanının evrensel tanımlayıcısı, sunucu t Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## Çözüm +### Çözüm `getFieldUniversalIdentifier`, `twenty-sdk` 2.21 sürümünden itibaren kullanılabilir. @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `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 +### Ö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: @@ -84,7 +90,7 @@ Aynı çözümlenen id, bir `fieldMetadataUniversalIdentifier` beklendiği her y 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. -## Sistem ilişki alanları +### Sistem ilişki alanları `getSystemRelationFieldUniversalIdentifier` 2.23 sürümünden itibaren `twenty-sdk` içinde kullanılabilir ve Twenty sunucusunun 2.23 veya daha yeni bir sürümünü gerektirir. @@ -129,18 +135,64 @@ const attachmentTargetRocketFieldId = Skaler sistem alanlarında olduğu gibi, çözümlenen kimlik, `fieldMetadataUniversalIdentifier` beklendiği her yerde çalışır. +## Sistem görünümleri + + + `getSystemViewUniversalIdentifier` ve `getSystemViewFieldUniversalIdentifier`, `twenty-sdk` 2.26 sürümünden itibaren kullanılabilir ve Twenty sunucusunun 2.26 veya daha yeni bir sürümünü gerektirir. + + +Sunucu ayrıca her nesnede bir **sistem görünümü** de sağlar: ana liste görünümü (`All {objectLabelPlural}`, `ViewKey.INDEX` anahtarıyla), gösterilebilir her alan için bir sütunla. Sistem ilişki alanlarında olduğu gibi, tanımlayıcıları **isimden bağımsız** olarak türetilir; bu nedenle bir nesnenin veya alanın adını değiştirmeniz onları asla değiştirmez. + +Görünümü çözümlemek için `getSystemViewUniversalIdentifier` kullanın: + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier`, görünümün ad alanını belirleyen, **nesneye** sahip olan uygulamadır. +* `objectUniversalIdentifier`, görünümün listelediği nesnedir. +* `viewKey`, bugün için `ViewKey.INDEX` olan sistem görünüm anahtarıdır. + +Çözümlenen kimlik, bir `viewUniversalIdentifier` beklendiği her yerde, örneğin bir [`NavigationMenuItemType.VIEW`](/l/tr/developers/extend/apps/layout/navigation-menu-items) kenar çubuğu girdisinde çalışır. Sadece bir nesnenin ana listesini açmak için, `targetObjectUniversalIdentifier` ile `NavigationMenuItemType.OBJECT` kullanmayı tercih edin: hiçbir türetmeye ihtiyaç duymaz. + +`getSystemViewFieldUniversalIdentifier`, bir sistem görünümündeki tek bir **sütunu**, görünümden ve görüntülediği alandan yola çıkarak çözümler: + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +İlk argümana dikkat edin: bir sütun, **görüntülediği alana** sahip olan uygulamanın ad alanındadır, görünüme sahip olanın değil. Uygulamanızın standart bir nesneye eklediği bir alan, Twenty'ye ait bir görünüm üzerinde, kendi uygulamanız altında türetilen bir sütun alır. + + + Sistem görünümleri ve sütunları **sunucuya aittir**: bunlara asla bildirmek için değil, yalnızca onlara başvurmak için tanımlayıcılarını çözümleyin. [`defineView()`](/l/tr/developers/extend/apps/layout/views) üzerindeki + `key` kullanımdan kaldırılmıştır ve yok sayılır; bu nedenle bir bildirim görünümü asla `INDEX` anahtarını talep edemez ve sunucu, eklediğiniz her alan için zaten bir sütun sağlar; bu yüzden bir sistem görünümünde aynı alan için kendi `defineViewField()` bildiriminizi yapmak bununla çelişir. + + ## 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. +**Standart** bir Twenty nesnesi (Person, Company, Opportunity, …) için hiçbir şey türetmeniz gerekmez: hem alanlar hem de görünümler için, doğrudan içe aktarabileceğiniz önceden hesaplanmış sabit tanımlayıcılar vardır. ```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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.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. +Yukarıdaki yardımcı işlevlere, [`defineObject()`](/l/tr/developers/extend/apps/data/objects) ile **uygulamanızın** tanımladığı ve böyle bir sabitin bulunmadığı nesneler için başvurun. `name`, bir sistem alanı değil, bir **varsayılan** alandır. Kendi hardcode edilmiş 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 6e0ad7533d..b776480ee7 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 @@ -4,10 +4,12 @@ description: Uygulamanızdaki nesneler için önceden yapılandırılmış kayde icon: list --- -Bir **görünüm**, bir nesnenin kayıtlarının nasıl görüntüleneceğine ilişkin kaydedilmiş bir yapılandırmadır: hangi alanların görüneceği, sıraları, görünür olup olmadıkları ve uygulanan tüm filtreler veya gruplar. Uygulamanızla birlikte önceden yapılandırılmış görünümler yayınlamak için `defineView()` kullanın — genellikle oluşturduğunuz her özel nesne için varsayılan bir indeks görünümü şeklinde olur. +Bir **görünüm**, bir nesnenin kayıtlarının nasıl görüntüleneceğine ilişkin kaydedilmiş bir yapılandırmadır: hangi alanların görüneceği, sıraları, görünür olup olmadıkları ve uygulanan tüm filtreler veya gruplar. Uygulamanızla önceden yapılandırılmış görünümler sunmak için `defineView()` kullanın. + +Her nesne, sunucu tarafından otomatik olarak sağlanan kendi ana liste görünümünü (bir `OBJECT` gezinme öğesinin açtığı "All ..." tablosu) alır — buna, uygulamanızın oluşturduğu nesneler de dahildir; uygulamanızın bildirdiği her alan için bir sütunla birlikte. `defineView()` ile tanımladığınız görünümler, bu varsayılan görünümün üzerine eklenen her zaman **ek** görünümlerdir. ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## Önemli noktalar * `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. 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). +* Nesnenin ana liste görünümü sunucuya aittir: `key` kullanımdan kaldırılmıştır ve yok sayılır, bu nedenle bir manifest görünümü bunu asla talep edemez. Görünümünüzün kenar çubuğunda tek tık uzağınızda olmasını istiyorsanız bir `VIEW` gezinme öğesi ekleyin. +* `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 Metaverilerini 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/tr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 70d721873d..508ce37fce 100644 --- a/packages/twenty-docs/l/tr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/tr/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -10,17 +10,16 @@ description: Görünümler, kenar çubuğu gezinmesi, bir komut ve ön uç bile Bir [görünüm](/l/tr/developers/extend/apps/layout/views), belirli bir nesnenin kaydedilmiş bir listesidir. Bir [gezinme menüsü öğesi](/l/tr/developers/extend/apps/layout/navigation-menu-items) -bu görünümü kenar çubuğuna yerleştirir. +bu görünümü kenar çubuğuna yerleştirir. Sunucu, her nesnenin varsayılan "Tümü ..." görünümünü zaten otomatik olarak sağladığından, bir uygulamanın tanımladığı görünümler ek, özenle seçilmiş görünümlerdir. ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER, 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 index 39f2858a33..2e21977e9a 100644 --- 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 @@ -1,16 +1,22 @@ --- -title: 定位系统字段 -description: 在视图和其他实体中，使用 getFieldUniversalIdentifier 引用自动创建的系统字段，例如 createdAt 或 updatedAt。 +title: 定位系统元数据 +description: 解析 Twenty 在每个对象上自动预配置的元数据的确定性通用标识符，这样你的应用无需硬编码就能引用它。 icon: gears --- -Twenty 中的每个对象都带有一组你无需自行声明的**系统字段**。 这些字段在对象初始化时由服务器自动创建： +Twenty 中的每个对象都带有你无需自行声明的**系统元数据**，例如一组字段以及带有列的主列表视图。 当对象被预配置时，服务器会创建所有这些内容，并且随着 Twenty 的发展，这个集合也会随之增长。 + +由于你不会声明它，因此也就没有可供你导入的 `universalIdentifier` 常量。 相反，服务器会以确定性方式**派生**每个标识符，而 `twenty-sdk` 暴露了相同的派生逻辑，这样你的 manifest 就能解析出服务器实际使用的精确值。 + +## 系统字段 + +存在于每个对象上的标量字段，你不会使用 [`defineField()`](/l/zh/developers/extend/apps/data/extending-objects) 来声明其中任何一个： `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` 作为一列来引用呢？ +那么，如何在[视图](/l/zh/developers/extend/apps/layout/views)中将 `createdAt` 作为一列来引用呢？ -## 问题 +### 问题 从 Twenty 2.19 起，系统字段的通用标识符由服务器根据三个输入**确定性派生**：应用通用标识符、对象通用标识符以及字段名称。 自行构造一个 id 并将其硬编码是行不通的：它在服务器上不会匹配任何内容，同步时会拒绝这个悬空引用： @@ -18,7 +24,7 @@ Twenty 中的每个对象都带有一组你无需自行声明的**系统字段** Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found ``` -## 解决方案 +### 解决方案 `getFieldUniversalIdentifier` 从 `twenty-sdk` 2.21 版本开始可用。 @@ -40,7 +46,7 @@ const createdAtFieldId = getFieldUniversalIdentifier({ * `objectUniversalIdentifier` 是该字段所属对象的标识符。 * `name` 是系统字段名称，为上面列出的值之一。 -## 示例：视图中的 createdAt 列 +### 示例：视图中的 createdAt 列 典型场景是：为你某个自定义对象的视图添加一列 `createdAt`。 解析字段 id，并像引用其他 `fieldMetadataUniversalIdentifier` 一样引用它： @@ -84,7 +90,7 @@ export default defineView({ `getFieldUniversalIdentifier` 能在这些输入发生变化时仍保持引用正确，并在派生逻辑演进时避免偏差。 -## 系统关系字段 +### 系统关系字段 `getSystemRelationFieldUniversalIdentifier` 可在 `twenty-sdk` @@ -130,18 +136,63 @@ const attachmentTargetRocketFieldId = 与标量系统字段一样，解析得到的 id 可在任何需要 `fieldMetadataUniversalIdentifier` 的地方使用。 +## 系统视图 + + + `getSystemViewUniversalIdentifier` 和 `getSystemViewFieldUniversalIdentifier` 可在 `twenty-sdk` 2.26 及更高版本中使用，并且需要 Twenty 服务器版本为 2.26 或更高。 + + +服务器还会在每个对象上预配置一个**系统视图**：主列表视图（`All {objectLabelPlural}`，以 `ViewKey.INDEX` 作为键），其中每个可显示字段对应一列。 与系统关联字段类似，它们的标识符是以**与名称无关**的方式派生的，因此重命名对象或字段都不会改变这些标识符。 + +使用 `getSystemViewUniversalIdentifier` 来解析该视图： + +```ts +import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define'; + +const rocketIndexViewId = getSystemViewUniversalIdentifier({ + objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER, + viewKey: ViewKey.INDEX, +}); +``` + +* `objectMetadataApplicationUniversalIdentifier` 是拥有该**对象**的应用程序，也是视图命名空间所基于的应用。 +* `objectUniversalIdentifier` 是该视图所列出的对象。 +* `viewKey` 是系统视图键，目前为 `ViewKey.INDEX`。 + +解析得到的 id 可用于任何需要 `viewUniversalIdentifier` 的地方，例如侧边栏中的 [`NavigationMenuItemType.VIEW`](/l/zh/developers/extend/apps/layout/navigation-menu-items) 条目。 如果只是要打开某个对象的主列表，优先使用带有 `targetObjectUniversalIdentifier` 的 `NavigationMenuItemType.OBJECT`：它不需要派生。 + +`getSystemViewFieldUniversalIdentifier` 会从视图以及其显示的字段中解析系统视图上的单个**列**： + +```ts +import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define'; + +const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({ + fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER, + viewUniversalIdentifier: rocketIndexViewId, + fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER, +}); +``` + +注意第一个参数：列是由**其显示的字段**所属的应用程序进行命名空间划分的，而不是由拥有该视图的应用程序进行划分。 你的应用向标准对象添加的字段，会在 Twenty 拥有的视图上，以你的应用为命名空间来派生其列。 + + + 系统视图及其列是由**服务器所有**的：解析它们的标识符是为了引用它们，而不是为了声明它们。 [`defineView()`](/l/zh/developers/extend/apps/layout/views) 上的 `key` 已被弃用且会被忽略，因此 manifest 视图永远无法占用 `INDEX` 键，并且服务器已经为你添加的每个字段预配置了一列，所以在系统视图上为同一个字段声明你自己的 `defineViewField()` 会与其发生冲突。 + + ## 标准 Twenty 对象 -对于**标准** Twenty 对象（Person、Company、Opportunity 等），你不需要进行任何派生：系统字段标识符是预先计算好的常量，你可以直接导入。 +对于**标准** 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 +// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier ``` -当对象是由**你的应用**使用 [`defineObject()`](/l/zh/developers/extend/apps/data/objects) 定义、且不存在此类常量时，再使用 `getFieldUniversalIdentifier`。 +当对象是由**你的应用**使用 [`defineObject()`](/l/zh/developers/extend/apps/data/objects) 定义、且不存在此类常量时，再使用上面的辅助方法。 `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 34abe9b21a..91d13aff09 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 @@ -4,10 +4,12 @@ description: 为你的应用中的对象提供预配置的已保存视图—— icon: list --- -**视图（view）** 是关于对象记录如何显示的已保存配置：包括显示哪些字段、它们的顺序、是否可见，以及应用的任何筛选器或分组。 使用 `defineView()` 为你的应用提供预配置视图——通常是你创建的每个自定义对象的默认索引视图。 +**视图（view）** 是关于对象记录如何显示的已保存配置：包括显示哪些字段、它们的顺序、是否可见，以及应用的任何筛选器或分组。 使用 `defineView()` 随你的应用一起提供预配置的视图。 + +每个对象都会自动获得其主列表视图（服务器预置的“全部 …”表格，即 `OBJECT` 导航项打开的视图）——包括你的应用创建的对象，其中每个字段对应一列。 你使用 `defineView()` 定义的视图始终是基于该默认视图之上的**附加**视图。 ```ts src/views/example-view.ts -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object'; @@ -16,7 +18,6 @@ export default defineView({ name: 'All example items', objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconList', - key: ViewKey.INDEX, position: 0, fields: [ { @@ -33,8 +34,8 @@ export default defineView({ ## 关键点 * `objectUniversalIdentifier` 指定此视图适用于哪个对象。 它可以是你定义的自定义对象，也可以是标准的 Twenty 对象。 -* `key: ViewKey.INDEX` 将该视图标记为对象的主列表视图（`OBJECT` 导航项打开的那个）。 -* `fields` 控制显示哪些列以及它们的顺序。 每个字段引用一个 `fieldMetadataUniversalIdentifier`。 若要引用自动创建的系统字段（例如 `createdAt`），请参阅[定位系统字段](/l/zh/developers/extend/apps/data/system-fields)。 +* 对象的主列表视图由服务器拥有：`key` 已被弃用并会被忽略，因此清单视图永远无法声明它。 如果你希望你的视图在侧边栏中只需一次点击即可访问，请提供一个 `VIEW` 导航项。 +* `fields` 控制显示哪些列以及它们的顺序。 每个字段引用一个 `fieldMetadataUniversalIdentifier`。 若要引用自动创建的系统字段（例如 `createdAt`），请参阅[定位系统元数据](/l/zh/developers/extend/apps/data/system-fields)。 * 你还可以声明 `filters`、`filterGroups`、`sorts`、`groups` 和 `fieldGroups` 以进行更高级的配置。 * 当同一对象存在多个视图时，`position` 控制其排序。 diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx index 1b3b0d3bdf..d4b491f687 100644 --- a/packages/twenty-docs/l/zh/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx +++ b/packages/twenty-docs/l/zh/developers/extend/apps/tutorials/document-generator/building-the-ui.mdx @@ -10,17 +10,16 @@ description: 查看、侧边栏导航、命令和前部件。 [view](/l/zh/developers/extend/apps/layout/views) 是一个已保存的对象列表。 [导航菜单项](/l/zh/developers/extend/apps/layout/navigation-menu-items) -将此视图放置在侧边栏中。 +将此视图放置在侧边栏中。 服务器已经为每个对象自动预配了默认的 "All ..." 视图，因此应用定义的视图是额外的、经过精心筛选的视图。 ```ts filename="src/views/documents.view.ts" -import { defineView, ViewKey } from 'twenty-sdk/define'; +import { defineView } from 'twenty-sdk/define'; export default defineView({ universalIdentifier: DOCUMENTS_VIEW_UNIVERSAL_IDENTIFIER, name: 'All documents', objectUniversalIdentifier: DOCUMENT_OBJECT_UNIVERSAL_IDENTIFIER, icon: 'IconFile', - key: ViewKey.INDEX, position: 0, fields: [ { universalIdentifier: DOCUMENTS_VIEW_NAME_FIELD_UNIVERSAL_IDENTIFIER,