الصفحة الرئيسية>المتعلقة بالبرمجة>شفرة المصدر الأخرى
تنزيل

Angular ng-select - خفيف الوزن الكل في واحد لتحديد واجهة المستخدم والتحديد المتعدد والإكمال التلقائي

انظر الصفحة التجريبية.

الإصدارات

الزاوي نانوغرام حدد
>=19.0.0 <20.0.0 v14.x
>=18.0.0 <19.0.0 v13.x
>=17.0.0 <18.0.0 v12.x
>=16.0.0 <17.0.0 v11.x
>=15.0.0 <16.0.0 v10.x
>=14.0.0 <15.0.0 v9.x
>=13.0.0 <14.0.0 v8.x
>=12.0.0 <13.0.0 v7.x
>=11.0.0 <12.0.0 v6.x
>=10.0.0 <11.0.0 v5.x
>=9.0.0 <10.0.0 v4.x
>=8.0.0 <9.0.0 v3.x
>=6.0.0 <8.0.0 v2.x
v5.xx v1.x

دعم المتصفح

يدعم ng-select جميع المتصفحات التي يدعمها Angular. للحصول على القائمة الحالية، راجع https://angular.io/guide/browser-support#browser-support. يتضمن ذلك الإصدارات المحددة التالية: 

 Chrome	2 most recent versions
Firefox	latest and extended support release (ESR)
Edge	2 most recent major versions
Safari	2 most recent major versions
iOS	2 most recent major versions
Android	2 most recent major versions

جدول المحتويات

  • سمات
  • ابدء
  • واجهة برمجة التطبيقات
  • كشف التغيير
  • أنماط مخصصة
    • حالة التحقق من الصحة
  • المساهمة
  • تطوير
  • إلهام

سمات

  • ربط مخصص بالخاصية أو الكائن
  • قوالب الخيارات والتسمية والرأس والتذييل المخصصة
  • دعم التمرير الظاهري مع مجموعات البيانات الكبيرة (> 5000 عنصر).
  • التمرير اللانهائي
  • التنقل عبر لوحة المفاتيح
  • تحديد متعدد
  • الإكمال التلقائي المرن مع تصفية العميل/الخادم
  • بحث مخصص
  • العلامات المخصصة
  • إلحاق ب
  • عناصر المجموعة
  • أحداث الإخراج
  • إمكانية الوصول
  • تغطية جيدة لاختبار الوظائف الأساسية
  • المواضيع

تحذير

المكتبة قيد التطوير النشط وقد تحتوي على تغييرات في واجهة برمجة التطبيقات (API) للإصدارات الرئيسية اللاحقة بعد 1.0.0.

ابدء

الخطوة 1: تثبيت ng-select :

الآلية الوقائية الوطنية 

npm install --save @ng-select/ng-select

غزل 

yarn add @ng-select/ng-select

الخطوة 2:

مستقل: قم باستيراد NgSelectComponent والتوجيهات الضرورية الأخرى مباشرةً: 

 import { NgLabelTemplateDirective , NgOptionTemplateDirective , NgSelectComponent } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;

@ Component ( {
  selector : 'example' ,
  standalone : true ,
  template : './example.component.html' ,
  styleUrl : './example.component.scss' ,
  imports : [
    NgLabelTemplateDirective ,
    NgOptionTemplateDirective ,
    NgSelectComponent ,
  ] ,
} )
export class ExampleComponent { }

NgModule: قم باستيراد وحدة NgSelectModule ووحدة FormsModule الزاوية: 

 import { NgSelectModule } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;

@ NgModule ( {
  declarations : [ AppComponent ] ,
  imports : [ NgSelectModule , FormsModule ] ,
  bootstrap : [ AppComponent ]
} )
export class AppModule { }

الخطوة 3: تضمين موضوع:

للسماح بالتخصيص والسمات، تتضمن حزمة ng-select فقط الأنماط العامة الضرورية للتخطيط وتحديد الموضع الصحيحين. للحصول على المظهر الكامل لعنصر التحكم، قم بتضمين أحد السمات في تطبيقك. إذا كنت تستخدم Angular CLI، فيمكنك إضافة هذا إلى styles.scss الخاص بك أو تضمينه في .angular-cli.json (Angular v5 وما دونه) أو angular.json (Angular v6 وما بعده). 

 @import " ~@ng-select/ng-select/themes/default.theme.css " ;
// ... or 
@import " ~@ng-select/ng-select/themes/material.theme.css " ;

الخطوة 4 (اختياري): التكوين

يمكنك أيضًا تعيين رسائل التكوين والترجمة العامة عن طريق إدخال خدمة NgSelectConfig، عادةً في المكون الجذر لديك، وتخصيص قيم خصائصها لتوفير القيم الافتراضية. 

  constructor ( private config : NgSelectConfig ) {
      this . config . notFoundText = 'Custom not found' ;
      this . config . appendTo = 'body' ;
      // set the bindValue to global config when you use the same 
      // bindValue in most of the place. 
      // You can also override bindValue for the specified template 
      // by defining `bindValue` as property
      // Eg : <ng-select bindValue="some-new-value"></ng-select>
      this . config . bindValue = 'value' ;
  }

الاستخدام

تحديد الخيارات في مكون الاستهلاك الخاص بك: 

@ Component ( { ... } )
export class ExampleComponent {

    selectedCar : number ;

    cars = [
        { id : 1 , name : 'Volvo' } ,
        { id : 2 , name : 'Saab' } ,
        { id : 3 , name : 'Opel' } ,
        { id : 4 , name : 'Audi' } ,
    ] ;
}

في القالب، استخدم مكون ng-select مع خياراتك 

 <!--Using ng-option and for loop-->
< ng-select [(ngModel)] =" selectedCar " >
    @for (car of cars; track car.id) {
        < ng-option [value] =" car.id " > {{car.name}} </ ng-option >
    }
</ ng-select >

<!--Using items input-->
< ng-select [items] =" cars " 
           bindLabel =" name " 
           bindValue =" id " 
           [(ngModel)] =" selectedCar " >
</ ng-select >

لمزيد من الأمثلة التفصيلية، راجع صفحة العرض التوضيحي

SystemJS

إذا كنت تستخدم SystemJS، فيجب عليك أيضًا ضبط التكوين الخاص بك للإشارة إلى حزمة UMD.

في ملف التكوين systemjs الخاص بك، تحتاج map إلى إخبار مُحمل النظام بالمكان الذي يبحث فيه عن ng-select : 

map: {
  '@ng-select/ng-select' : 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js' ,
}

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

المدخلات

مدخل يكتب تقصير مطلوب وصف
[أضف علامة] boolean | ((term: string) => any | Promise<any>) false لا يسمح بإنشاء خيارات مخصصة.
addTagText string Add item لا قم بتعيين نص مخصص عند استخدام العلامات
مظهر string underline لا يسمح بتحديد مظهر القائمة المنسدلة. اضبط على outline لإضافة حدود بدلاً من التسطير (ينطبق فقط على سمة المادة)
إلحاق ب string باطل لا إلحاق القائمة المنسدلة بالنص أو أي عنصر آخر باستخدام محدد CSS. للحصول على الوضع الصحيح، يجب أن يكون body position:relative
bufferAmount string باطل لا إلحاق القائمة المنسدلة بالنص أو أي عنصر آخر باستخدام محدد CSS. للحصول على الوضع الصحيح، يجب أن يكون body position:relative
bindValue string - لا خاصية الكائن المراد استخدامها للنموذج المحدد. بشكل افتراضي يرتبط بالكائن بأكمله.
bindLabel string label لا خاصية الكائن المراد استخدامها للتسمية. label الافتراضية
[كلوسيونسيليكت] boolean حقيقي لا ما إذا كان سيتم إغلاق القائمة عند تحديد قيمة
ClearAllText string Clear all لا قم بتعيين نص مخصص لمسح كل عنوان الرمز
[واضح] boolean true لا السماح بمسح القيمة المحددة. الافتراضي true
[كليرونباكسبيس] boolean true لا امسح القيم المحددة واحدًا تلو الآخر عند النقر فوق مسافة للخلف. الافتراضي true
[قارن مع] (a: any, b: any) => boolean (a, b) => a === b لا وظيفة لمقارنة قيم الخيارات مع القيم المحددة. الوسيطة الأولى هي قيمة من أحد الخيارات. والثاني هو قيمة من التحديد (النموذج). يجب إرجاع قيمة منطقية.
dropdownPosition bottom | top | auto auto لا اضبط موضع القائمة المنسدلة على الفتح
[عنصر نائب ثابت] boolean false لا قم بتعيين العنصر النائب مرئيًا حتى عند تحديد عنصر
[مجموعة حسب] string | Function باطل لا السماح بتجميع العناصر حسب تعبير المفتاح أو الوظيفة
[قيمة المجموعة] (groupKey: string, children: any[]) => Object - لا تعبير الوظيفة لتوفير قيمة المجموعة
[مجموعة قابلة للتحديد] boolean خطأ شنيع لا السماح بتحديد المجموعة عند استخدام groupBy
[selectableGroupAsModel] boolean حقيقي لا يشير إلى ما إذا كان سيتم تحديد كافة الأطفال أو المجموعة نفسها
[أغراض] Array<any> [] نعم مصفوفة العناصر
[تحميل] boolean - لا يمكنك ضبط حالة التحميل من الخارج (مثل تحميل العناصر غير المتزامنة)
loadingText string Loading... لا قم بتعيين نص مخصص عند تحميل العناصر
labelForId string - لا معرف لربط التحكم بالتسمية.
[ماركفيرست] boolean true لا وضع علامة على العنصر الأول باعتباره موضع التركيز عند الفتح/التصفية.
[مفتوح] boolean - لا يسمح بالتحكم اليدوي في فتح وإغلاق القائمة المنسدلة. true - لن يغلق. false - لن تفتح.
maxSelectedItems number لا أحد لا عندما يكون المتعدد = صحيح، يسمح بتعيين عدد محدد من الاختيارات.
[إخفاء المحدد] boolean false لا يسمح بإخفاء العناصر المحددة.
[عديد] boolean false لا يسمح بتحديد عناصر متعددة.
notFoundText string No items found لا قم بتعيين نص مخصص عندما يقوم الفلتر بإرجاع نتيجة فارغة
العنصر النائب string - لا نص العنصر النائب.
[قابل للبحث] boolean true لا السماح بالبحث عن القيمة. الافتراضي true
[للقراءة فقط] boolean false لا قم بتعيين ng-select للقراءة فقط. تستخدم في الغالب مع النماذج التفاعلية.
[بحث فن] (term: string, item: any) => boolean null لا السماح بالتصفية حسب وظيفة البحث المخصصة
[البحث أثناء التأليف] boolean true لا ما إذا كان يجب تصفية العناصر أثناء بدء التكوين أم لا
[تراكبيفن] (item: any) => any null لا توفير وظيفة TrackBy مخصصة
[مسح البحث عن الإضافة] boolean true لا مسح مدخلات البحث عند تحديد العنصر. true افتراضي . القيمة الافتراضية false عندما تكون قيمة CloseOnSelect false
[إلغاء التحديد عند النقر] boolean false لا يلغي تحديد العنصر المحدد عند النقر عليه في القائمة المنسدلة. افتراضي false . true افتراضي عندما يكون المتعدد true
[مصطلح البحث القابل للتحرير] boolean false لا السماح بتحرير استعلام البحث إذا تم تحديد الخيار. افتراضي false . يعمل فقط إذا كان المتعدد false .
[حددأونتاب] boolean false لا حدد عنصر القائمة المنسدلة المحدد باستخدام علامة التبويب. الافتراضي false
[فتحونتر] boolean true لا افتح القائمة المنسدلة باستخدام الإدخال. الافتراضي true
[الطباعة] Subject - لا الإكمال التلقائي المخصص أو المرشح المتقدم.
[طول المدة الدنيا] number 0 لا الحد الأدنى لطول المدة لبدء البحث. ينبغي أن تستخدم مع typeahead
typeToSearchText string Type to search لا قم بتعيين نص مخصص عند استخدام Typehead
[التمرير الافتراضي] boolean خطأ شنيع لا قم بتمكين التمرير الافتراضي للحصول على أداء أفضل عند عرض الكثير من البيانات
[إدخالات] { [key: string]: string } - لا تمرير السمات المخصصة إلى عنصر input الأساسي
[فهرس علامة التبويب] number - لا قم بتعيين tabindex على ng-select
[منعToggleOnRightClick] boolean false لا منع فتح ng-select عند النقر بزر الماوس الأيمن
[keyDownFn] ($event: KeyboardEvent) => bool true لا توفير وظيفة keyDown المخصصة. تم تنفيذه قبل المعالج الافتراضي. قم بإرجاع false لمنع تنفيذ المعالجات الافتراضية للمفتاح السفلي

النواتج

الإخراج وصف
(يضيف) يتم إطلاقه عند إضافة عنصر أثناء [multiple]="true" . تمت إضافة النواتج إلى العنصر
(طمس) أطلقت على تحديد طمس
(يتغير) أطلقت على تغيير النموذج. مخرجات النموذج كله
(يغلق) تم إطلاقه عند إغلاق القائمة المنسدلة المحددة
(واضح) أطلقت على أيقونة واضحة فوق
(ركز) أطلقت على تحديد التركيز
(يبحث) تم إطلاقه أثناء كتابة مصطلح البحث. إخراج مصطلح البحث مع العناصر التي تمت تصفيتها
(يفتح) تم إطلاقه عند فتح القائمة المنسدلة
(يزيل) يتم التشغيل عند إزالة العنصر أثناء [multiple]="true"
(التمرير) أطلقت عند التمرير. يوفر فهرس البداية والنهاية للعناصر المتوفرة حاليًا. يمكن استخدامه لتحميل المزيد من العناصر في أجزاء قبل أن ينتقل المستخدم إلى أسفل القائمة.
(انتقل إلى النهاية) يتم إطلاقه عند التمرير إلى نهاية العناصر. يمكن استخدامها لتحميل المزيد من العناصر في قطع.

طُرق

اسم وصف
يفتح يفتح لوحة التحديد المنسدلة
يغلق لإغلاق لوحة التحديد المنسدلة
ركز يركز على عنصر التحديد
طمس يطمس عنصر التحديد

آخر

اسم يكتب وصف
[ngOptionHighlight] التوجيه يسلط الضوء على مصطلح البحث في الخيار. يقبل مصطلح البحث. ينبغي أن تستخدم على عنصر الخيار. التمهيدي
NgSelectConfig إعدادات موفر التكوين لمكون NgSelect. يمكنك حقن هذه الخدمة وتوفير التكوين على مستوى التطبيق.
SELECTION_MODEL_FACTORY خدمة رمز DI لتنفيذ SelectionModel. يمكنك توفير تنفيذ مخصص لتغيير سلوك الاختيار.

منطق الاختيار المخصص

يسمح Ng-select بتوفير تنفيذ التحديد المخصص باستخدام SELECTION_MODEL_FACTORY . لتجاوز المنطق الافتراضي، قم بتوفير طريقة المصنع الخاصة بك في الوحدة الزاويّة الخاصة بك. 

 // app.module.ts
providers: [
    { provide : SELECTION_MODEL_FACTORY , useValue : < SelectionModelFactory > CustomSelectionFactory }
]

// selection-model.ts
export function CustomSelectionFactory ( ) {
    return new CustomSelectionModel ( ) ;
}

export class CustomSelectionModel implements SelectionModel {
    ...
}

كشف التغيير

يقوم مكون Ng-select بتنفيذ اكتشاف التغيير OnPush مما يعني عمليات التحقق القذرة لأنواع البيانات غير القابلة للتغيير. وهذا يعني أنه إذا قمت بإجراء طفرات كائنية مثل: 

 this . items . push ( { id : 1 , name : 'New item' } )

لن يكتشف المكون أي تغيير. بدلا من ذلك عليك القيام بما يلي: 

 this . items = [ ... this . items , { id : 1 , name : 'New item' } ] ;

سيؤدي هذا إلى اكتشاف المكون للتغيير والتحديث. قد يكون لدى البعض مخاوف من أن هذه عملية باهظة الثمن، ومع ذلك، فهي أكثر أداءً من تشغيل ngDoCheck وتمييز المصفوفة باستمرار.

أنماط مخصصة

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

 < ng-select class =" custom " > </ ng-select > 
. ng-select . custom {
    border : 0 px ;
    min-height : 0 px ;
    border-radius : 0 ;
}
. ng-select . custom . ng-select-container  {            
    min-height : 0 px ;
    border-radius : 0 ;
}

إذا كنت تستخدم ViewEncapsulation ، فيمكنك استخدام محدد خاص ::ng-deep والذي سيمنع تحديد نطاق المحددات المتداخلة على الرغم من أن هذا يعد بمثابة حل بديل ونوصي باستخدام الحل الموضح أعلاه. 

. ng-select . custom :: ng-deep . ng-select-container  {            
    min-height : 0 px ;
    border-radius : 0 ;
}

تحذير: ضع في اعتبارك أن ng-deep تم إهماله ولا يوجد بديل له حتى الآن. انظر هنا.

حالة التحقق من الصحة

افتراضيًا، عند استخدام أدوات التحقق من النماذج التفاعلية أو أدوات التحقق من النماذج المستندة إلى القوالب، سيتم تطبيق فئة css ng-invalid على ng-select. يمكنك إظهار حالة الأخطاء عن طريق إضافة نمط CSS مخصص 

 ng-select . ng-invalid . ng-touched . ng-select-container {
    border-color : # dc3545 ;
    box-shadow : inset 0 1 px 1 px rgba ( 0 , 0 , 0 , 0.075 ) , 0 0 0 3 px # fde6e8 ;
}

المساهمة

المساهمات هي موضع ترحيب. يمكنك البدء من خلال النظر في المشكلات ذات التصنيف " المساعدة مطلوبة" أو إنشاء مشكلة جديدة مع الاقتراح أو تقرير الأخطاء. لاحظ أننا نستخدم تنسيق الالتزامات https://conventionalcommits.org/.

تطوير

قم بتنفيذ خطوات الاستنساخ لبدء التشغيل باستخدام هذه الأوامر الطرفية.

قم بتشغيل الصفحة التجريبية في وضع المشاهدة 

 git clone https://github.com/ng-select/ng-select
cd ng-select
yarn
yarn run start

اختبار 

 yarn run test
or
yarn run test:watch

يطلق

للإصدار إلى npm، ما عليك سوى تشغيل ./release.sh ، بالطبع إذا كان لديك الأذونات؛)

إلهام

هذا المكون مستوحى من React Select والتمرير الظاهري. تحقق من عملهم ومكوناتهم الرائعة :)

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل