Πώς Λειτουργεί η Σελιδοποίηση

Το Legalesign GraphQL API χρησιμοποιεί σελιδοποίηση με βάση τον δείκτη (cursor-based pagination) σύμφωνα με τις προδιαγραφές Relay connection. Κάθε λίστα αντικειμένων — έγγραφα, πρότυπα, επαφές, τιμολόγια — χρησιμοποιεί το ίδιο μοτίβο.

Το Μοτίβο Σύνδεσης

Η ορολογία προέρχεται από τη θεωρία γραφημάτων — κόμβοι είναι σημεία, άκρες είναι οι γραμμές που τα συνδέουν. Στο API, μια άκρη περιγράφει τη σχέση μεταξύ δύο τύπων και μπορεί να μεταφέρει επιπλέον μεταδεδομένα (όπως ποιες άδειες έχει ένας User σε μια Group).

Όταν κάνετε ένα ερώτημα σε μια λίστα, δεν λαμβάνετε έναν απλό πίνακα. Λαμβάνετε ένα αντικείμενο σύνδεσης (connection) με τρία μέρη:

documentConnection(first: 20) {
  documents { ... }     # the items (shortcut)
  totalCount            # total matching items
  pageInfo {            # pagination cursors
    startCursor
    endCursor
    hasNextPage
    hasPreviousPage
  }
}

Γιατί Όχι Απλώς Ένας Πίνακας;

Η σελιδοποίηση με δείκτες είναι σταθερή. Σε αντίθεση με την σελιδοποίηση με offset (page=2), οι δείκτες δεν διακόπτονται όταν προστίθενται ή αφαιρούνται αντικείμενα μεταξύ των αιτημάτων. Αυτό είναι σημαντικό όταν τα έγγραφα αποστέλλονται και υπογράφονται σε πραγματικό χρόνο.

Ανάκτηση της Πρώτης Σελίδας

Χρησιμοποιήστε το first για να περιορίσετε τα αποτελέσματα. Όταν κάνετε σελιδοποίηση σε ένα πλήρες σύνολο αποτελεσμάτων με σειρά δημιουργίας, περάστε "0" ή "START" ως παράμετρο after στην πρώτη σας κλήση για να δηλώσετε ότι ξεκινάτε μια ακολουθία σελιδοποίησης:

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "0") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Ανάκτηση της Επόμενης Σελίδας

Αν το hasNextPage είναι true, περάστε το endCursor ως παράμετρο after:

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "eyJpZCI6ImRvYzEyMyJ9") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Επαναλάβετε μέχρι το hasNextPage να γίνει false.

Παράμετροι Σελιδοποίησης

Όλες οι συνδέσεις δέχονται αυτές τις παραμέτρους:

Παράμετρος	Τύπος	Περιγραφή
first	Int	Αριθμός αντικειμένων για επιστροφή από την αρχή
after	ID	Δείκτης για εκκίνηση μετά από αυτόν (για προωθημένη σελιδοποίηση)
last	Int	Αριθμός αντικειμένων για επιστροφή από το τέλος
before	ID	Δείκτης για εκκίνηση πριν από αυτόν (για οπισθοδρομική σελιδοποίηση)

Οι περισσότερες συνδέσεις δέχονται επίσης παραμέτρους φιλτραρίσματος ειδικές για τον τύπο δεδομένων. Για παράδειγμα, το documentConnection δέχεται from, to, status, search, sendType και sender.

Η Συντόμευση με τις Άκρες

Οι συνδέσεις παρέχουν τόσο τα edges (με έναν δείκτη ανά αντικείμενο) όσο και μια σύντομη λίστα. Για τις περισσότερες περιπτώσεις, η σύντομη λίστα είναι απλούστερη:

# Shortcut — simpler, no per-item cursor
documentConnection(first: 20) {
  documents {
    id
    name
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

# Full edges — needed if you want per-item cursors
documentConnection(first: 20) {
  edges {
    node {
      id
      name
    }
    cursor
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

Χρησιμοποιήστε τη συντόμευση εκτός αν χρειάζεστε μεμονωμένους δείκτες (π.χ. για διαγραφή συγκεκριμένου αντικειμένου και συνέχιση από εκεί).

σημείωση

Το totalCount επιστρέφει τον αριθμό για την τρέχουσα σελίδα, όχι το συνολικό αριθμό σε όλες τις σελίδες. Το κόστος υπολογισμού ενός συνολικού αριθμού σε πιθανώς εκατομμύρια εγγραφές καθιστά την πραγματική συνολική τιμή μη πρακτική.

Παράδειγμα Σε Πραγματικό Περιβάλλον

Να πώς η εφαρμογή Legalesign Console σελιδοποιεί έγγραφα χρησιμοποιώντας infinite scroll με TanStack Query:

query queryInfiniteDocuments {
  group(id: "grpYourGroupId") {
    documentConnection(
      first: 100
      after: "eyJpZCI6ImRvYzEyMyJ9"
      sendType: SINGLE
      from: "2025-01-01T00:00:00Z"
      to: "2025-06-01T00:00:00Z"
    ) {
      documents {
        id
        name
        status
        senderName
        created
        recipients {
          id
          email
          status
          signedDateTime
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Η εφαρμογή ανακτά την πρώτη σελίδα και στη συνέχεια με κύλιση χρησιμοποιεί το endCursor ως after για να φορτώσει το επόμενο πακέτο.

Ποιοι Τύποι Χρησιμοποιούν Συνδέσεις;

Κάθε σχέση λίστας στο API χρησιμοποιεί αυτό το μοτίβο:

• Group.documentConnection, templateConnection, batchConnection, contactConnection, experienceConnection, scheduleConnection, attachmentConnection, memberConnection, invitationConnection, standardMessageConnection, contactGroupConnection, draftConnection, activityConnection
• Organisation.groupConnection, dataStopConnection, dataDeletionConnection, retentionConnection, userConnection, invoiceConnection, dataSubjectConnection
• Batch.documentConnection
• Billing.invoiceConnection
• Invoice.lineItemConnection
• Template.elementConnection, userSignatureConnection
• Document.elementConnection
• Recipient.elementConnection
• User.memberConnection, organisationConnection, supportTicketConnection