# العمل مع القوائم

## **إنشاء قائمة جديدة** 

create\_list()

{% tabs %}
{% tab title="الوصف" %}
أدخل الدالة في **"الحاسبة"** الحقل في إعدادات الكتلة: 

**create\_list(name)** - ينشئ قائمة جديدة. النتيجة هي معرّف القائمة.

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;name** - اسم القائمة. يُحدَّد الاسم بين علامتي اقتباس مفردتين.
{% endtab %}

{% tab title="مثال" %}
`list_id = create_list("registered")`

<div data-with-frame="true"><figure><img src="/files/69e040bb9adf7457e96874a1fa3830f3c65df8f1" alt="" width="563"><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

## إنشاء قائمة من الكتلة بدون تكرارات

create\_list\_if\_not\_exist()

{% tabs %}
{% tab title="الوصف" %}
**create\_list\_if\_not\_exist('list\_name')** - ينشئ قائمة جديدة إذا لم تكن قائمة بهذا الاسم موجودة بعد ويعيد معرّفها، أو يعيد معرّف القائمة الموجودة.

المعامل المطلوب:

**list\_name** - اسم القائمة الجديدة المراد إنشاؤها.
{% endtab %}

{% tab title="مثال" %}

<div data-with-frame="true"><figure><img src="/files/11d39e851ddfb2de7c51a03a7ebab4adf767ee62" alt="" width="563"><figcaption></figcaption></figure></div>

```
new_list = create_list_if_not_exist('List of participants')
```

{% endtab %}
{% endtabs %}

## إضافة عميل إلى القائمة

add\_to\_list()

{% tabs %}
{% tab title="الوصف" %}
**add\_to\_list(list\_id, client\_id)** - يضيف عميلًا إلى قائمة. تُرجع الدالة قيمة none.

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;list\_id** - معرّف القائمة

**client\_id** - معرّف عميل MaviBot. إذا لم يتم توفيره، فسيُستخدم معرّف العميل الحالي.
{% endtab %}
{% endtabs %}

## نقل عميل إلى القائمة

move\_to\_list()

{% tabs %}
{% tab title="الوصف" %}
**move\_to\_list(list\_id, client\_id)** - ينقل عميلًا إلى القائمة (مهم! تتم إزالة العميل من جميع القوائم الأخرى ونقله إلى القائمة المحددة). النتيجة قيمة منطقية (True أو False).

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;list\_id** - معرّف القائمة

**client\_id** - معرّف عميل MaviBot. إذا لم يتم توفيره، فسيُستخدم معرّف العميل الحالي.
{% endtab %}
{% endtabs %}

## إزالة عميل من القائمة

remove\_from\_list()

{% tabs %}
{% tab title="الوصف" %}
**remove\_from\_list(list\_id, client\_id)** - يزيل العميل ذي المعرّف client\_id من القائمة.

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;list\_id** - معرّف القائمة

**client\_id** - معرّف عميل MaviBot. إذا لم يتم توفيره، فسيُستخدم معرّف العميل الحالي.
{% endtab %}
{% endtabs %}

## حذف القوائم&#x20;

remove\_list\_from\_project(list\_id, clear\_list)

{% tabs %}
{% tab title="الوصف" %} <mark style="color:red;">**!**</mark>**&#x20;list\_id** - معامل مطلوب؛ معرّف القائمة المراد حذفها.

**clear\_list** — معامل اختياري؛ يقبل قيمتين: True أو False (القيمة الافتراضية هي False).

إذا لم تُوفّر هذا المعامل وكانت القائمة تحتوي على عملاء، فستتلقى الرد التالي:
***"Can't delete list, list not empty"***

إذا كانت القائمة فارغة، فسيتم حذفها دون مشاكل. ومع ذلك، إذا قمت بتعيين **clear\_list** إلى True، فسيتم حذف القائمة بغضّ النظر عمّا إذا كانت تحتوي على عملاء أم لا.
{% endtab %}
{% endtabs %}

## حذف الوسوم

remove\_label\_from\_project(list\_id, clear\_list)

{% tabs %}
{% tab title="الوصف" %} <mark style="color:red;">**!**</mark>**&#x20;list\_id** - معامل مطلوب؛ معرّف الوسم المراد حذفه.

**clear\_list** - معامل اختياري؛ يقبل قيمتين: True أو False (القيمة الافتراضية هي False).

إذا لم يتم توفير هذا المعامل وكان الوسم مُسنَدًا إلى عملاء، فستتلقى الرد التالي:
&#x20;***"Can't delete list, list not empty"***

إذا لم يكن الوسم مُسنَدًا إلى أي عملاء، فسيتم حذفه دون مشاكل. ومع ذلك، إذا **clear\_list** تم تعيينه إلى True، فسيتم حذف الوسم بغضّ النظر عمّا إذا كان مُسنَدًا إلى عملاء أم لا.
{% endtab %}
{% endtabs %}

## مسح قائمة العملاء&#x20;

clear\_list()

{% tabs %}
{% tab title="الوصف" %}
**clear\_list(list\_id)** - يمسح قائمة العملاء

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;list\_id -** معرّف القائمة. بعد الاستخدام، ستتم إزالة جميع العملاء من القائمة المحددة.&#x20;
{% endtab %}
{% endtabs %}

## الحصول على عدد العملاء في القائمة

list\_size()

{% tabs %}
{% tab title="الوصف" %}
**list\_size(list\_id)** – يحسب العدد الإجمالي للعملاء في القائمة

المعلمات:&#x20;

<mark style="color:red;">**!**</mark>**&#x20;list\_id**- معرّف القائمة
{% endtab %}
{% endtabs %}

## حساب عدد إدخالات العملاء الفريدة عبر عدة قوائم

lists\_joint\_count()

{% tabs %}
{% tab title="الوصف" %}
**lists\_joint\_count(massive\_list)** – يحسب العدد الإجمالي لإدخالات العملاء الفريدة عبر عدة قوائم. تأخذ الدالة مصفوفة من معرّفات القوائم كمدخل وتُرجع عددًا.

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;massive\_list** - مصفوفة تحتوي على معرّفات القوائم التي سيتم فيها احتساب إدخالات العملاء الفريدة. الصيغة هي: **\['list\_id1', 'list\_id2', ..., 'list\_idN']**
{% endtab %}

{% tab title="مثال على الكود للنسخ" %}

```
/*إنشاء قائمة*/
list_id = create_list('New list')

/*التحقق مما إذا كان العميل موجودًا في القائمة*/
k=inlist(list_id, client_id)

/*الحصول على حجم القائمة — العدد الإجمالي للعملاء في القائمة*/
razm=list_size(1)

/*الحصول على العدد الإجمالي لإدخالات العملاء الفريدة عبر عدة قوائم*/
k=lists_joint_count('[144636,144634]')
```

{% endtab %}
{% endtabs %}

## التحقق مما إذا كان العميل موجودًا في القائمة

inlist()

{% tabs %}
{% tab title="الوصف" %}
**inlist(list\_id,client\_id)** - يتحقق مما إذا كان العميل موجودًا في القائمة. النتيجة قيمة منطقية (True أو False).

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;list\_id** - معرّف القائمة

**client\_id** - معرّف عميل MaviBot. إذا لم يتم توفيره، فسيُستخدم معرّف العميل الحالي.&#x20;
{% endtab %}
{% endtabs %}

## التحقق مما إذا كان أحد المشاركين في الدردشة موجودًا في قائمة محددة

some\_client\_in\_list()

{% tabs %}
{% tab title="الوصف" %}
**some\_client\_in\_list(list\_id, recepient)**

المعلمات:

<mark style="color:red;">**!**</mark>**&#x20;list\_id** - معرّف القائمة؛&#x20;

<mark style="color:red;">**!**</mark>**&#x20;recepient** - معرّف مستخدم المراسلة الذي يتم التحقق منه (platform\_id). بالنسبة للدردشات، تكون قيمة المتغير هي chat\_member\_id.&#x20;

تُرجع القيم:

True - العميل موجود في القائمة؛

False - العميل غير موجود في القائمة المحددة.
{% endtab %}

{% tab title="مثال" %}

<div data-with-frame="true"><figure><img src="/files/ebccdef07c9e5d53d110bdca5ef3dadcddcc9490" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="مثال على الكود للنسخ" %}

```
/*مثال على التحقق مما إذا كان أحد المشاركين في الدردشة موجودًا في القائمة، حيث إن المعامل الأول هو معرّف القائمة، والثاني هو معرّف دردشة المستخدم*/

r = some_client_in_list(123456, chat_member_id)
```

{% endtab %}
{% endtabs %}

### استرجاع العناصر من قائمة

count\_occurrences()

{% tabs %}
{% tab title="الوصف" %}
**count\_occurrences(array, element)** - تُرجع عدد العناصر المحددة الموجودة في القائمة.

المعلمات:

**مصفوفة** - معامل مطلوب؛ قائمة بالعناصر

**element** - معامل مطلوب؛ العنصر المراد عدّه
{% endtab %}
{% endtabs %}

## الحصول على معرّف عميل عشوائي من القائمة

random\_list\_member(list\_id)

{% tabs %}
{% tab title="الوصف" %}
random\_list\_member(list\_id) - تُرجع معرّف عميل واحدًا عشوائيًا في القائمة المحددة.

list\_id - معامل مطلوب، معرّف القائمة.

يمكن العثور على معرّف القائمة التي تحتوي على عملائك في **"Lists"** :

<figure><img src="/files/e5a1cfa209d98918fbca77844752e3bb701b7f71" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## مثال على العمل مع القوائم في الحاسبة

<details>

<summary>example</summary>

لنلقِ نظرة على مثال لاستخدام الدوال في **"الحاسبة"** للعمل مع القوائم.

<mark style="color:red;">**مهم!**</mark> تحتاج إلى حفظ معرّف قائمة جديدة لكي تتمكن من استخدامه لاحقًا. للقيام بذلك، أسند نتيجة الدالة إلى متغير، أي list\_id = ...

<div data-with-frame="true"><figure><img src="/files/9fbdf5f5cf1f0f643132318ebd1480158b48a9dd" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/c77dc979ec91cbca1022736b505d00ddef638245" alt="" width="375"><figcaption></figcaption></figure></div>

يمكنك الآن تنفيذ عمليات أخرى بسهولة على القائمة — التحقق مما إذا كان عميل موجودًا في القائمة، أو إضافة عميل، أو نقله، أو إزالته.

على سبيل المثال، لنتحقق مما إذا كان عميل موجودًا في القائمة ذات المعرّف 12333:

<div data-with-frame="true"><figure><img src="/files/e37be84d25426112d9ba6740c17c60d5710bd379" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/952efe2f899e7feffcbb850af152bf0b97dd1e9e" alt="" width="375"><figcaption></figcaption></figure></div>

من الملائم جدًا استخدام القوائم عند عرض البيانات الإحصائية:

<figure><img src="/files/0d33601ed34455531252ede8d4279e683098ee59" alt="" width="563"><figcaption></figcaption></figure>

غالبًا ما يلزم الحصول على العدد الإجمالي للإدخالات الفريدة عبر مجموعة من القوائم — ويمكن القيام بذلك بسهولة باستخدام `lists_joint_count()` .

<div data-with-frame="true"><figure><img src="/files/f2300e69341d81710eb793cc7866af9040e3da16" alt="" width="563"><figcaption></figcaption></figure></div>

أ

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/ar/chatbot/functions/alaalh-alhasbh/lists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.