استهداف البيانات الوصفية النظامية

كل كائن في Twenty يأتي مع بيانات وصفية نظامية لا تقوم أنت بتعريفها، مثل مجموعة من الحقول وعرض القائمة الرئيسي مع أعمدته. يقوم الخادم بإنشاء كل ذلك عند توفير الكائن، وتنمو هذه المجموعة مع نمو Twenty. نظرًا لأنك لا تعرّفها، فلا يوجد ثابت universalIdentifier لتقوم باستيراده. بدلًا من ذلك، يقوم الخادم باستخلاص كل معرّف بشكل حتمي، ويعرض twenty-sdk نفس طريقة الاستخلاص بحيث يمكن لملف البيان (manifest) لديك حلّ القيمة الدقيقة التي يستخدمها الخادم.

حقول النظام

الحقول البسيطة (scalar) الموجودة على كل كائن، والتي لا تعرّف أيًا منها باستخدام defineField(): id, createdAt, updatedAt, deletedAt, createdBy, updatedBy, position, searchVector فكيف تُشير إلى createdAt كعمود في عرض؟

المشكلة

منذ Twenty 2.19، يتم اشتقاق المعرّف الشامل للحقل النظامي بشكل حتمي بواسطة الخادم من ثلاثة مُدخلات: المعرّف الشامل للتطبيق، والمعرّف الشامل للكائن، واسم الحقل. ابتكار معرّف (id) وتضمينه بشكل ثابت لن ينجح: لن يطابق أي شيء على الخادم، وسترفض المزامنة المرجع المعلّق:

Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found

الحل

يتوفر getFieldUniversalIdentifier في twenty-sdk بدءًا من الإصدار 2.21 فصاعدًا.

استخدم getFieldUniversalIdentifier لاشتقاق نفس القيمة تمامًا التي يستخدمها الخادم. يأخذ المُدخلات الثلاثة ويُرجِع المعرّف الشامل للحقل:

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

const createdAtFieldId = getFieldUniversalIdentifier({
  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
  name: 'createdAt',
});

applicationUniversalIdentifier هو معرّف تطبيقك، وهو نفسه الذي تمرّره إلى defineApplication().
objectUniversalIdentifier هو معرّف الكائن الذي ينتمي إليه الحقل.
name هو اسم الحقل النظامي، وهو إحدى القيم المُدرجة أعلاه.

مثال: عمود `createdAt` في عرض

الحالة النموذجية هي إضافة عمود createdAt إلى عرض لأحد الكائنات المخصّصة لديك. اشتقّ معرّف الحقل واستدعِه كما تستدعي أي fieldMetadataUniversalIdentifier آخر:

src/views/example-view.ts

import {
  defineView,
  getFieldUniversalIdentifier,
} from 'twenty-sdk/define';

const APPLICATION_UNIVERSAL_IDENTIFIER =
  '0b04e15c-27b2-4741-9046-b32e07469072';
const MY_OBJECT_UNIVERSAL_IDENTIFIER =
  'c782b61c-70fd-4c88-9cd6-4e61ab8d7591';

export default defineView({
  universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0',
  name: 'All records',
  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  position: 0,
  fields: [
    {
      universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104',
      fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({
        applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
        objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
        name: 'createdAt',
      }),
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});

المعرّف المُشتقّ نفسه يعمل في أي مكان يُتوقَّع فيه fieldMetadataUniversalIdentifier: حقول العرض، عوامل التصفية، أوامر الفرز، المجموعات، وعناصر واجهة تخطيط الصفحة.

اشتقّ المعرّف، ولا تقُم بتضمينه بشكل ثابت. نظرًا لأن الخادم يشتق القيمة من معرّف التطبيق، ومعرّف الكائن، واسم الحقل، فإن استدعاء getFieldUniversalIdentifier يُبقي مرجعك صحيحًا حتى إذا تغيّرت تلك المُدخلات، ويتجنّب الانحراف إذا تطوّر أسلوب الاشتقاق في أي وقت.

حقول العلاقات الخاصة بالنظام

getSystemRelationFieldUniversalIdentifier متوفر في twenty-sdk بدءًا من الإصدار 2.23، ويتطلب خادم Twenty بالإصدار 2.23 أو أحدث.

بالإضافة إلى حقول النظام البدائية المذكورة أعلاه، يوفِّر الخادم أيضًا أربعة حقول علاقات للنظام على كل كائن: timelineActivities وattachments وnoteTargets وtaskTargets، يشير كلٌّ منها إلى كائن العلاقة القياسي المطابِق. لا يتم حلّ هذه الحقول باستخدام getFieldUniversalIdentifier، إذ يتم اشتقاق معرّفها بدون الاعتماد على الاسم، من الكائن المستضيف للحقل والكائن الذي يشير إليه الحقل. وبهذه الطريقة، فإن إعادة تسمية كائن ما لا تغيِّر مطلقًا معرّفات حقول العلاقات الخاصة به. استخدم getSystemRelationFieldUniversalIdentifier لحلّها:

import {
  getSystemRelationFieldUniversalIdentifier,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';

// rocket.attachments — the relation field hosted on your custom object
const rocketAttachmentsFieldId = getSystemRelationFieldUniversalIdentifier({
  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  relationTargetObjectUniversalIdentifier:
    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
});

objectUniversalIdentifier هو الكائن الذي يستضيف الحقل.
relationTargetObjectUniversalIdentifier هو الكائن الذي يشير إليه الحقل.

يتم ترميز الاتجاه من خلال ترتيب الوسيطات. لحلّ الجانب العكسي (مثلًا attachment.targetRocket، حقل morph الذي يُنشِئه الخادم على كائن العلاقة القياسي)، قم بمبادلة الاثنين:

// attachment.targetRocket — the reverse morph field on Attachment
const attachmentTargetRocketFieldId =
  getSystemRelationFieldUniversalIdentifier({
    applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
    objectUniversalIdentifier:
      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
    relationTargetObjectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  });

كما هو الحال مع حقول النظام القياسية (scalar)، يعمل المعرّف الناتج في أي موضع يُتوقَّع فيه fieldMetadataUniversalIdentifier.

العروض النظامية

إن getSystemViewUniversalIdentifier وgetSystemViewFieldUniversalIdentifier متوفران في twenty-sdk بدءًا من الإصدار 2.26، ويتطلبان خادم Twenty بالإصدار 2.26 أو أحدث.

يقوم الخادم أيضًا بتوفير عرض نظامي على كل كائن: عرض القائمة الرئيسي (All {objectLabelPlural}، ذو المفتاح ViewKey.INDEX)، مع عمود واحد لكل حقل قابل للعرض. تمامًا مثل حقول العلاقات النظامية، تُشتق معرّفاتها من دون أسماء، لذلك لن يؤدي تغيير اسم كائن أو حقل إلى تغييرها مطلقًا. استخدم getSystemViewUniversalIdentifier لحلّ العرض:

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. لفتح القائمة الرئيسية لكائن ما ببساطة، يُفضَّل استخدام NavigationMenuItemType.OBJECT مع targetObjectUniversalIdentifier، إذ لا يحتاج ذلك إلى أي اشتقاق. يقوم getSystemViewFieldUniversalIdentifier بحلّ عمود واحد في عرض نظامي، انطلاقًا من العرض والحقل الذي يعرضه هذا العمود:

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

const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({
  fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  viewUniversalIdentifier: rocketIndexViewId,
  fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER,
});

انتبه إلى الوسيطة الأولى: يتم تحديد نطاق اسم العمود بواسطة التطبيق الذي يملك الحقل الذي يعرضه، وليس التطبيق الذي يملك العرض. الحقل الذي يضيفه تطبيقك إلى كائن قياسي يحصل على عموده المشتق ضمن نطاق تطبيقك، على عرض مملوك من قِبَل Twenty.

العروض النظامية وأعمدتها مملوكة للخادم: استخدم حلّ معرّفاتها للرجوع إليها، وليس لتعريفها. إن الخاصية key في defineView() مهملة (deprecated) ويتم تجاهلها، لذلك لا يمكن لعرض مُعرَّف في ملف البيان المطالبة بالمفتاح INDEX مطلقًا، كما أن الخادم يوفّر بالفعل عمودًا لكل حقل تضيفه، لذا فإن تعريف defineViewField() خاصّتك لنفس الحقل على عرض نظامي يتعارض معه.

الكائنات القياسية في Twenty

بالنسبة إلى كائن Twenty قياسي (Person، Company، Opportunity، …)، لا تحتاج إلى اشتقاق أي شيء: فمعرّفات الحقول والعروض النظامية هي ثوابت مُسبقة الحساب يمكنك استيرادها مباشرة.

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()، حيث لا يوجد مثل هذا الثابت.

name حقل افتراضي، وليس حقلًا نظاميًا. يحتفظ بمعرّفه الشامل الثابت الخاص به ولا يتم اشتقاقه عبر getFieldUniversalIdentifier. في الكائنات التي تعرّفها، استدعِ حقل name باستخدام المعرّف الذي منحته له في defineObject().

نظرة عامة

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

استهداف البيانات الوصفية النظامية

حقول النظام

المشكلة

الحل

مثال: عمود `createdAt` في عرض

حقول العلاقات الخاصة بالنظام

العروض النظامية

الكائنات القياسية في Twenty

​حقول النظام

​المشكلة

​الحل

​مثال: عمود createdAt في عرض

​حقول العلاقات الخاصة بالنظام

​العروض النظامية

​الكائنات القياسية في Twenty

حقول النظام

المشكلة

الحل

مثال: عمود `createdAt` في عرض

حقول العلاقات الخاصة بالنظام

العروض النظامية

الكائنات القياسية في Twenty