Neidio i’r prif gynnwys

Integreiddio Gwylwr Dogfen Legalesign i’ch Gwefan

cyngor

Gallwch weld y cydran hon mewn gweithred fel Anfon Cyflym yn Console.

Fersiwn cyfredol: v1.0.27 — newidiadau

Mae Gwylwr Dogfen Legalesign yn gydran gwe annibynnol ar lwyfannau sy’n caniatáu ichi olygu, rhagweld, a phersonoli templedi ar gyfer llofnodi dogfennau. Mae’n gweithio’n ddi-dor mewn HTML gyda JavaScript, React, Vue, Angular, neu unrhyw fframwaith gwe.

Mae’r gydran plygio a chwarae hon wedi’i dylunio fel y gallwch integreiddio rhannau allweddol o greu dogfennau i’ch systemau mewnol, megis CRM neu gais llinell busnes.

Cyn belled â bod eich system yn gallu rendro a chefnogi cydrannau HTML, gallwch ddefnyddio’r Gwylwr Dogfen.

Os ydych angen cymorth ychwanegol i integreiddio’r Gwylwr Dogfen i’ch stac technegol, cysylltwch â’n desg gymorth.

Gallwch ddefnyddio’r widgits mwy hyn gyda integreiddiadau API REST/GraphQL i ddarparu prosesau llofnodi dogfennau di-dor i’ch staff a’ch cwsmeriaid.

Gosod​

Gosod NPM​

npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer

Ar gyfer Prosiectau React​

npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react

Integreiddiad Sylfaenol​

HTML/JavaScript​

Gellir defnyddio’r fersiwn HTML/Javascript o’r cydran hon gyda unrhyw stac datblygu, megis PHP, ASP .Net ac ati. Gallwch gysylltu â’r cydran yn uniongyrchol o npm os na chaniateir ei gosod yn eich amgylchedd. Gallwch geisio tudalen arddangosfa o’r adran enghreifftiol yma [https://github.com/legalesign/ls-viewer-demo].

Ychwanegwch sgriptiau’r gydran at eich HTML:

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.css" />
<script type="module" src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.esm.js"></script>
<script nomodule src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.js"></script>
</head>
<body>
<ls-document-viewer
id="my-editor"
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
></ls-document-viewer>
</body>
</html>

Awthentigiaeth - Cael tocyn​

Bydd angen defnyddio cod ochr y gweinydd i gael YOUR_AUTH_TOKEN. Mae dau opsiwn, ac mae’r ddau yn defnyddio’ch allwedd API:

  1. GraphQL generateComponentToken — Galwch y newidiad gyda’ch allwedd API i lunio tocyn cydran byrhoedlog ac ar raddfa benodol.
  2. REST API — Galwch GET /templatepdf/{pdfId}/component-token/ gyda’ch allwedd API.

Opsiwn 1 (GraphQL):

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
body: JSON.stringify({
query: `mutation {
generateComponentToken(input: { component: LS_DOCUMENT_VIEWER }) {
token
expiresIn
expiresAt
}
}`,
}),
});

const { data } = await response.json();
const token = data.generateComponentToken.token;

Opsiwn 2 (REST):

const response = await fetch(
`https://eu-api.legalesign.com/api/v1/templatepdf/${pdfId}/component-token/`,
{
headers: {
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
}
);

const { token } = await response.json();

Pasio’r token a ddychwelyd i’r widgit. Gweler Awdurdodi Widgit am ragor o fanylion ar opsiynau tocyn.

Integreiddiad React​

Rydym hefyd wedi creu fersiwn o’r gydran sy’n integreiddio’n uniongyrchol gyda fframweithiau React.

import { LsDocumentViewer } from 'legalesign-document-viewer-react';

function App() {
return (
<LsDocumentViewer
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
mode="compose"
/>
);
}

Nodweddion Gofynnol​

tocyn​

Eich tocyn diogelwch ar gyfer awthentigiaeth: tocyn cydran byrhoedlog o generateComponentToken neu'r pwynt diwedd tocyn cydran REST. Gweler Awdurdodi Widgit am y llif tocyn diogel.

token="eyJraWQiOiJBTkJIeT..."

templateid​

ID API y deunydd templed rydych chi am ei gyflwyno i ddefnyddwyr. Gallwch ei gael drwy edrych yn y URL pan fyddwch yn golygu’r templed yn y Gwe Ap.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Moddau Widgit​

Modd Golygydd​

Creu a golygu templed llawn gyda’r holl offer sydd ar gael. Mae hyn wedi’i fwriadu ar gyfer llifoedd gwaith lle mae templed sydd wedi’i ailddefnyddio’n helaeth gyda rolau’n ddefnyddiol. Os yw eich bwriad yw defnyddio’ch dogfen unwaith yn unig (efallai bod eich system creu dogfennau eisoes wedi llenwi’r holl wybodaeth cleient), yna efallai yr hoffech ystyried modd cyfansoddi yn lle hynny.

<ls-document-viewer mode="editor" ...></ls-document-viewer>

Modd Cyfansoddi​

Mae’r modd hwn yn ddull 'derbynnydd-yn-gyntaf' i symleiddio profiad y defnyddiwr. Yn y Gwe Ap Legalesign dyma’r swyddogaeth 'Anfon Cyflym'.

Ychwanegwch eich derbynwyr i’r nodwedd 'recipients' a gall eich defnyddiwr leoli eu llofnodion a maes ffurflen yn gyflym, cyn eu hanfon. Yn berffaith ar gyfer cwsmeriaid integredig lle mae derbynwyr eisoes wedi’u diffinio.

Y llif gwaith arferol yw clôn neu uwchlwytho PDF, yna mewnblannu’r gwylwr lle gall y defnyddiwr ychwanegu llofnodion a meysydd ffurflen, a chynnig botwm i anfon y ddogfen.

Clôn​

Clôn templed sydd eisoes yn bodoli trwy ddefnyddio'r newidiad copyTemplate:

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CopyTemplate {
copyTemplate(input: {
groupId: "yourGroupId",
templateId: "yourTemplateId",
newTitle: "new document title",
copyFields: true|false
})
}
`
})
});
const { data } = await response.json();
const templateId = data.copyTemplate;

Neu Uwchlwytho​

Creu templed yna ei uwchlwytho i’r uploadUrl a ddarperir. Defnyddiwch y teitl [deleted] os nad ydych am i’r pdf fod yn eich llyfrgell. Bydd yn cael ei ddileu yn y 24 awr nesaf. Yn arall gallwch ddefnyddio unrhyw deitl rydych chi’n ei ddewis:

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CreateTemplate {
createTemplate(input: {groupId: "yourGroupid", title: "[deleted]"}) {
id
uploadUrl
}
}
`
})
});
const { data } = await response.json();
const templateId = data.createTemplate.id;
const uploadUrl = data.createTemplate.uploadUrl;

Nawr POSTiwch eich ffeil i’r uploadUrl. Rhaid i fath y cynnwys fod yn application/pdf.

Mewnosod y Gwylwr​

Y prif nodwedd yw 'recipients'. Bydd angen manylion ychwanegol ar gyfer cymeradwyaid neu dystion - am ragor o wybodaeth gweler Derbynwyr.

<ls-document-viewer 
mode="compose"
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
]'
...></ls-document-viewer>

Yn awtomatig, mae modd cyfansoddi yn:

  • Canfod derbynwyr a gynhyrchwyd ymlaen llaw
  • Cuddio’r anfonwr o’r gwymplen
  • Cuddio opsiynau dogfen
  • Dangos meysydd angenrheidiol fel diofyn
  • Tynnu’r anfonwr a meysydd anfonwr o’r golygydd
  • Hybu dewis cyflym o’r meysydd angenrheidiol ar gyfer pob derbynnydd

Modd Rhagolwg​

Rhagolwg dogfen defnyddiol sy’n dangos y ddogfen gyda’r holl feysydd presennol ac yn gadael i’r defnyddiwr bori drwy’r tudalennau.

<ls-document-viewer mode="preview" ...></ls-document-viewer>

Yn awtomatig, mae modd rhagolwg yn:

  • Cuddio’r bar offer
  • Cuddio opsiynau dogfen
  • Cuddio’r blwch offer
  • Gwneud y cyfranogwyr a’r meysydd yn ddarllen yn unig

Cyfluniad Uwch​

Hidlo’r Bocs Offer​

Cyfyngu mathau meysydd sydd ar gael gan ddefnyddio gwerthoedd wedi’u gwahanu gan bibellau. Os na ddarperir gwerth, tybir bydd y blwch offer heb hidlydd ac mae’r holl opsiynau ar gael.

<ls-document-viewer
filtertoolbox="signature|initials|date|text"
...
></ls-document-viewer>

Gwerthoedd hidlo sydd ar gael:

GwerthDisgrifiad
signatureMaes llofnod (dim ond ar gyfer llofnodwr)
auto signMaes llofnodi awtomatig (dim ond ar gyfer anfonwr)
textMewnbwn testun rhydd
signing dateDyddiad yn cael ei lenwi’n awtomatig wrth lofnodi (dim ond ar gyfer llofnodwr)
dateMaes dewis dyddiad
emailMewnbwn e-bost
initialsMaes cychwynnolion
numberMewnbwn rhifol
dropdownDewislen cwympo
checkboxBlwch ticio
regexMewnbwn wedi’i ddilysu gan regex (dim ond ar gyfer llofnodwr)
imageUwchlwytho delwedd (dim ond ar gyfer llofnodwr)
fileUwchlwytho ffeil (dim ond ar gyfer llofnodwr)
drawnMaes lluniadu/llaw rhydd (dim ond ar gyfer llofnodwr)

Derbynwyr​

Diffinio derbynwyr dogfen mewn fformat JSON.

Mae’r elfennau gofynnol ar gyfer pob derbynnydd yn firstname, lastname, email a signerIndex;

Yn opsiynol gallwch basio rôl a rhif ffôn ar gyfer pob derbynnydd. Os byddwch yn hepgor rôl, bydd y derbynnydd yn cael ei drin fel llofnodwr.

Gallwch basio rôl "WITNESS" neu "APPROVER". Ar gyfer rôl "WITNESS" ychwanegwch 100 at rif signerIndex eu llofnodwr. Er enghraifft os oes angen tyst arlofnodwr 2 (signerIndex: 2), gwnewch y WITNESS yn signerIndex: 102.

<ls-document-viewer
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
{"email": "user3@example.com", "firstname": "Joan", "lastname": "Mitchell", "signerIndex": 102, roleType: "WITNESS"}
]'
...
></ls-document-viewer>

Botymau Custom gyda Slots​

Ychwanegwch fotymau custom i’r bar offer gan ddefnyddio slots. Yn debygol byddwch yn defnyddio’r rhain i ganslo’r gweithred neu anfon y ddogfen.

<ls-document-viewer ...>
<style>
.custom-button {
padding: 2px 12px;
border-radius: 1rem;
background-color: #9df5d4;
color: #125241;
font-weight: 500;
}
</style>
<span slot="left-button">
<button class="custom-button">Cancel</button>
</span>
<span slot="right-button">
<button class="custom-button">Send Document</button>
</span>
</ls-document-viewer>

Rheoli Digwyddiadau​

Gwrandewch ar ddigwyddiadau cydran i olrhain newidiadau:

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
console.log('Template changed:', event.detail);
});

Gallwch olrhain a yw templed wedi dod yn ddilys neu annilys drwy ddefnyddio ’r digwyddiad validate.

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('validate', (event) => {
console.log('Template validation changed:', event.detail.valid);
});

Enghraifft Rheoli Digwyddiadau React​

Wrth ddefnyddio digwyddiad mewn react mae’n cael ei rag-enwi gyda’r on<EventName> cyfarwydd.

<LsDocumentViewer
onUpdate={(event) => {
console.log('Template changed:', event.detail);
}}
...
/>

Mathau o Ddigwyddiadau​

Digwyddiad update​

Yn cael ei danio pan fydd templed y ddogfen yn cael ei newid, megis ychwanegu neu dynnu meysydd. Mae’n darparu nid yn unig y digwyddiad a achosodd hynny ond hefyd y statws wedi’i ddiweddaru o’r gwrthrych templed fel JSON.

Digwyddiad validate​

Yn cael ei danio pan fydd templed y ddogfen yn cael ei newid, mae’r eiddo valid yn y manylion yn dangos os yw’r templed wedi dod yn ddilys neu annilys.

Digwyddiad selectFields​

Yn cael ei danio pan ddewisir maes yn y golygydd.

Digwyddiad addParticipant​

Yn cael ei danio pan ychwanegir rôl cyfranogwr at y templed.

Enghraifft Gwbl​

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document Editor</title>
<link rel="stylesheet" href="https://unpkg.com/legalesign-document-viewer/ls-document-viewer.css" />
<script type="module" src="https://unpkg.com/legalesign-document-viewer"></script>
</head>
<body style="padding: 0; margin: 0">
<ls-document-viewer
id="my-editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_TOKEN_HERE"
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1}
]'
filtertoolbox="signature|initials|date"
>
<span slot="left-button">
<button onclick="handleCancel()">Cancel</button>
</span>
<span slot="right-button">
<button onclick="handleSend()">Send</button>
</span>
</ls-document-viewer>

<script>
const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
// shows the change event and the template details
console.log('Document updated:', event.detail);
});

function handleCancel() {
// Implement the cancel logic, e.g. go to a home page
window.location.href = '/cancelpage';
}

function handleSend() {
// Implement send logic if required.
console.log('Sending document...');
}
</script>
</body>
</html>

Anfonwch y ddogfen ochr gweinydd gan ddefnyddio eich allwedd API, gyda’r rhyngwyneb GraphQL neu REST.

Datrys Problemau

Os cewch chi broblemau gyda’r cydran, sicrhewch fod:

Cefnogaeth Pori​

Mae’r gydran yn defnyddio safonau gwe modern ac yn cefnogi:

  • Chrome/Edge (yn ddiweddaraf)
  • Firefox (yn ddiweddaraf)
  • Safari (yn ddiweddaraf)
  • Porwyr symudol (iOS Safari, Chrome Mobile)

Newidiadau​

FersiwnDyddiadCrynodeb
v1.0.2719 Hyd 2026Gwella lleoli meysydd
v1.0.263 Medi 2026Trwsio sgwrolio; rendro oedi ar lwytho
v1.0.2112 Awst 2026Opsiynau modd rhagolwg; gwella digwyddiad update
v1.0.1817 Gorff 2026Panel maes regex; priodoleddau uwch sawl maes; gwella dropdown; ail-enwi tyst
v1.0.1210 Gorff 2026Priodoledd maes excludeFromPdf
v1.0.99 Gorff 2026Meysydd dyddiad auto a regex; priodoleddau uwch; trefn maes
v1.0.62 Gorff 2026Trwsio ffont yn atal methiant llofnodi; gweddillion rhagolwg
v1.0.529 Mehefin 2026Byrlwybrau bysellfwrdd dadwneud/ailwneud
v1.0.426 Mehefin 2026Gwella digwyddiadau; diweddariadau optimistaidd; dadwneud/ailwneud
v1.0.024 Mehefin 2026Gofod cyntaf sefydlog

Adnoddau​

Cael Cymorth​

Ar gyfer cymorth technegol neu gwestiynau ynghylch integreiddiad, cysylltwch â thîm cymorth Legalesign neu ymweliwch â’r dogfennaeth API.