Sut Mae Tudalenwaith yn Gweithio

Mae API GraphQL Legalesign yn defnyddio tudalenwaith seiliedig ar gwrsor yn ôl safon cysylltiad Relay. Mae pob rhestr o eitemau — dogfennau, templedi, cyswllt, anfonebau — yn defnyddio’r un patrwm hwn.

Y Patrwm Cysylltiad

Mae’r derminoleg yn deillio o ddamcaniaeth graffiau — mae nodau yn bwyntiau, ac mae cyrnau yn linellau sy’n eu cysylltu. Yn yr API, mae corn yn disgrifio’r berthynas rhwng dau fath ac yn gallu cludo metadata ychwanegol (fel pa awdurdodau sydd gan User mewn Group).

Pan wyt ti’n gwneud ymholiad ar restr, dydy ti ddim yn cael arae syml. Rwyt ti’n cael gwrthrych cysylltiad gyda thair rhan:

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

Pam Ddim Dim Ond Arae?

Mae tudalenwaith seiliedig ar gwrsor yn sefydlog. Yn wahanol i dudalenwaith offset (page=2), dydy cyrsorau ddim yn torri pan ychwanegir neu gael eu tynnu eitemau rhwng ceisiadau. Mae hyn yn bwysig pan mae dogfennau yn cael eu hanfon a’u llofnodi mewn amser real.

Nôl y Dudalen Gyntaf

Defnyddia first i gyfyngu canlyniadau. Wrth dudalennu drwy set canlyniadau llawn yn nhrefn eu creu, pasia "0" neu "START" fel yr argument after ar dy alwad gyntaf i nodi dy fod yn cychwyn dilyniant tudalenwaith:

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

Nôl y Dudalen Nesaf

Os yw hasNextPage yn true, pasia endCursor fel yr argument after:

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

Ailadrodd nes bod hasNextPage yn false.

Dadleuon Tudalenwaith

Mae pob cysylltiad yn derbyn y dadleuon canlynol:

Dadl	Math	Disgrifiad
first	Int	Nifer y eitemau i’w dychwelyd o’r dechrau
after	ID	Cwrsor i ddechrau ar ôl (ar gyfer tudalenwaith ymlaen)
last	Int	Nifer y eitemau i’w dychwelyd o’r diwedd
before	ID	Cwrsor i ddechrau cyn (ar gyfer tudalenwaith ymlaen)

Mae’r mwyafrif o gysylltiadau hefyd yn derbyn dadleuon hidlo penodol i’r math o ddata. Er enghraifft, mae documentConnection yn derbyn from, to, status, search, sendType, a sender.

Y Byrglen Cyrn

Mae cysylltiadau yn darparu edges (gyda chyrsor ar gyfer pob eitem) a rhestr byrglen. Mewn mwyafrif y defnyddiau, mae’r byrlen yn symlach:

# 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
  }
}

Defnyddia’r byrlen oni bai bod angen cyrsorau unigol arnat (e.e. i ddileu eitem benodol a pharhau o’r pwynt hwnnw).

nodyn

Mae totalCount yn dychwelyd y cyfrif ar gyfer y dudalen bresennol, nid y cyfanswm ar draws pob tudalen. Mae cost cyfrifo cyfanswm byd-eang ar draws miliynau posib o gofnodion yn gwneud cyfanswm gwirioneddol yn anos ei weithredu.

Enghraifft Byd-Go iawn

Dyma sut mae ap Console Legalesign yn tudalennu dogfennau gan ddefnyddio llusgo diwethaf gyda 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
    }
  }
}

Mae’r ap yn nôl y dudalen gyntaf, ac yna wrth lusgo yn defnyddio endCursor fel after i lwytho’r batch nesaf.

Pa Fathau Sy’n Defnyddio Cysylltiadau?

Mae pob cysylltiad rhestr yn yr API yn defnyddio’r patrwm hwn:

• 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