Integreiddio Gwylwr Dogfen Legalesign i’ch Gwefan
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:
- GraphQL
generateComponentToken— Galwch y newidiad gyda’ch allwedd API i lunio tocyn cydran byrhoedlog ac ar raddfa benodol. - 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:
| Gwerth | Disgrifiad |
|---|---|
signature | Maes llofnod (dim ond ar gyfer llofnodwr) |
auto sign | Maes llofnodi awtomatig (dim ond ar gyfer anfonwr) |
text | Mewnbwn testun rhydd |
signing date | Dyddiad yn cael ei lenwi’n awtomatig wrth lofnodi (dim ond ar gyfer llofnodwr) |
date | Maes dewis dyddiad |
email | Mewnbwn e-bost |
initials | Maes cychwynnolion |
number | Mewnbwn rhifol |
dropdown | Dewislen cwympo |
checkbox | Blwch ticio |
regex | Mewnbwn wedi’i ddilysu gan regex (dim ond ar gyfer llofnodwr) |
image | Uwchlwytho delwedd (dim ond ar gyfer llofnodwr) |
file | Uwchlwytho ffeil (dim ond ar gyfer llofnodwr) |
drawn | Maes 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.
- Send mutation — anfon dogfen sengl
- Send Input Schema — cyfeirnod mewnbwn llawn
- REST Send - cyfeirnod anfon dogfen REST
Datrys Problemau
Os cewch chi broblemau gyda’r cydran, sicrhewch fod:
- gallwch chi gael mynediad neu wedi rhestru gwyn y parth storio dogfennau yn https://s3.amazonaws.com/*
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
| Fersiwn | Dyddiad | Crynodeb |
|---|---|---|
| v1.0.27 | 19 Hyd 2026 | Gwella lleoli meysydd |
| v1.0.26 | 3 Medi 2026 | Trwsio sgwrolio; rendro oedi ar lwytho |
| v1.0.21 | 12 Awst 2026 | Opsiynau modd rhagolwg; gwella digwyddiad update |
| v1.0.18 | 17 Gorff 2026 | Panel maes regex; priodoleddau uwch sawl maes; gwella dropdown; ail-enwi tyst |
| v1.0.12 | 10 Gorff 2026 | Priodoledd maes excludeFromPdf |
| v1.0.9 | 9 Gorff 2026 | Meysydd dyddiad auto a regex; priodoleddau uwch; trefn maes |
| v1.0.6 | 2 Gorff 2026 | Trwsio ffont yn atal methiant llofnodi; gweddillion rhagolwg |
| v1.0.5 | 29 Mehefin 2026 | Byrlwybrau bysellfwrdd dadwneud/ailwneud |
| v1.0.4 | 26 Mehefin 2026 | Gwella digwyddiadau; diweddariadau optimistaidd; dadwneud/ailwneud |
| v1.0.0 | 24 Mehefin 2026 | Gofod cyntaf sefydlog |
Adnoddau
- Canllaw Integreiddio GraphQL — sut i gysylltu’r gwylwr gyda’r API GraphQL ar gyfer anfon
- Dogfennaeth API GraphQL
- Pecyn NPM
- Pecyn React
- Cymorth
Cael Cymorth
Ar gyfer cymorth technegol neu gwestiynau ynghylch integreiddiad, cysylltwch â thîm cymorth Legalesign neu ymweliwch â’r dogfennaeth API.