مرجع واجهة برمجة التطبيقات: `getOwnedObjects`

استرجاع قائمة بالكائنات المملوكة بعنوان محدد.

الفئة: SuiClient نوع الطريقة: عملية قراءة، بدون غاز

نظرة عامة

تملأ هذه الطريقة شاشات "المخزون" أو "المحفظة". نظرًا لأن العنوان يمكن أن يمتلك الآلاف من الكائنات، فإن هذه الطريقة ترقم النتائج.

التوقيع

client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>

المعلمات

المعلمة	النوع	مطلوب	الوصف
`owner`	`string`	نعم	عنوان المحفظة 32 بايت المطلوب التحقق منه.
`filter`	`SuiObjectDataFilter`	لا	تصفية النتائج حسب النوع أو الحزمة، انظر أدناه.
`options`	`SuiObjectDataOptions`	لا	أعلام لتضمين التفاصيل، على سبيل المثال، `showType`.
`cursor`	`string`	لا	`nextCursor` من استجابة سابقة، لترقيم الصفحات.
`limit`	`number`	لا	الحد الأقصى للعناصر المراد إرجاعها، الافتراضي: 50.

`SuiObjectDataFilter`

توفر معلمة filter تصفية قوية. تتيح لك طرح أسئلة محددة مثل "أرني العملات فقط" بدلاً من تنزيل مخزون المستخدم بالكامل.

مفتاح التصفية	نوع القيمة	الوصف
`MatchAll`	`Filter[]`	منطقية و. يجب أن يتطابق الكائن مع جميع المرشحات المقدمة.
`MatchAny`	`Filter[]`	منطقية أو. يمكن أن يتطابق الكائن مع أي عامل تصفية متوفر.
`StructType`	`string`	مطابقة تامة لنوع بنية متحركة، على سبيل المثال، `0x2::sui::SUI`.
`Package`	`string`	تطابق أي كائن معرّف في معرّف حزمة محدد.

قيمة الإرجاع

إرجاع PaginatedObjectsResponse.

{
  "data": [
    { "data": { "objectId": "0xA...", "type": "..." } },
    { "data": { "objectId": "0xB...", "type": "..." } }
  ],
  "hasNextPage": true,
  "nextCursor": "0x12345...ResultCursor"
}

data: تحتوي هذه المصفوفة على كائنات هذه الصفحة.
hasNextPage: true إذا كان هناك المزيد من الكائنات لجلبها.
nextCursor: السلسلة التي يجب عليك تمريرها إلى معلمة cursor في استدعاء التالي للحصول على الصفحة التالية.

أمثلة على الاستخدام

سيناريو أ: جلب المخزون الأساسي، الصفحة الأولى

احصل على أول 5 عناصر مملوكة لعنوان ما.

const response = await client.getOwnedObjects({
    owner: '0xMyAddress...',
    limit: 5,
    options: { showType: true }
});

response.data.forEach(item => {
    console.log(`ID: ${item.data.objectId}, Type: ${item.data.type}`);
});

سيناريو ب: التصفية لأصول محددة

احصل على فقط على "رموز Sui DevNet غير القابلة للاستبدال" التي يمتلكها المستخدم، مع تجاهل عملاته وعناصره الأخرى.

const response = await client.getOwnedObjects({
    owner: '0xMyAddress...',
    filter: {
        StructType: '0x2::devnet_nft::DevNetNFT'
    },
    options: { showContent: true }
});

سيناريو ج: ترقيم الصفحات الكامل، جلب الكل

استخدم حلقة while لجلب كل كائن يمتلكه الحساب، صفحة بصفحة.

let hasNextPage = true;
let nextCursor = null;
const allObjects = [];

while (hasNextPage) {
    const response = await client.getOwnedObjects({
        owner: '0xMyAddress...',
        cursor: nextCursor
    });

    allObjects.push(...response.data);
    
    hasNextPage = response.hasNextPage;
    nextCursor = response.nextCursor;
}

console.log(`Total objects fetched: ${allObjects.length}`);

الأخطاء الشائعة

رمز الخطأ	السبب	الحل
`cursor_invalid`	السلسلة التي تم تمريرها إلى `cursor` غير صالحة أو من استعلام مختلف.	تأكد من تمرير السلسلة التي تم إرجاعها بالضبط في `nextCursor` من الاستدعاء السابق.

| limit_exceeded | إذا طلبت حدًا أعلى مما تسمح به العقدة، على سبيل المثال، 1000، قلل الحد الأقصى. الحد الأقصى القياسي عادةً هو 50. |

انظر أيضاً

getObject: جلب كائن واحد من خلال معرفه.
multiGetObjects: جلب العديد من الكائنات حسب معرّفاتها في طلب واحد.

نظرة عامة​

التوقيع​

المعلمات​

SuiObjectDataFilter​

قيمة الإرجاع​

أمثلة على الاستخدام​

سيناريو أ: جلب المخزون الأساسي، الصفحة الأولى​

سيناريو ب: التصفية لأصول محددة​

سيناريو ج: ترقيم الصفحات الكامل، جلب الكل​

الأخطاء الشائعة​

انظر أيضاً​