Ενσωμάτωση του Προβολέα Εγγράφων Legalesign στον Ιστότοπό σας
Μπορείτε να δείτε αυτό το συστατικό σε δράση ως Quick Send στην Κονσόλα.
Τρέχουσα έκδοση: v1.0.27 — ημερολόγιο αλλαγών
Ο Προβολέας Εγγράφων Legalesign είναι ένα πλατφόρμα-ανεξάρτητο διαδικτυακό συστατικό που σας επιτρέπει να επεξεργάζεστε, να προεπισκοπείτε και να προσαρμόζετε πρότυπα για υπογραφή εγγράφων. Λειτουργεί άψογα σε HTML με JavaScript, React, Vue, Angular ή οποιοδήποτε web framework.
Αυτό το συστατικό plug and play έχει σχεδιαστεί έτσι ώστε να μπορείτε να ενσωματώσετε βασικά μέρη της δημιουργίας εγγράφων στα εσωτερικά σας συστήματα, όπως ένα CRM ή μια εφαρμογή επιχειρησιακής γραμμής.
Όσο το σύστημά σας μπορεί να αποδώσει και να υποστηρίξει HTML συστατικά, μπορείτε να χρησιμοποιήσετε τον Προβολέα Εγγράφων.
Εάν χρειάζεστε επιπλέον βοήθεια για την ενσωμάτωση του Προβολέα Εγγράφων στο τεχνικό σας stack, παρακαλούμε επικοινωνήστε με το τμήμα υποστήριξής μας.
Μπορείτε να χρησιμοποιήσετε αυτά τα μεγαλύτερα widgets με ενσωματώσεις REST/GraphQL API για να παρέχετε αδιάλειπτες διαδικασίες υπογραφής εγγράφων για το προσωπικό και τους πελάτες σας.
Εγκατάσταση
Εγκατάσταση μέσω NPM
npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer
Για Έργα React
npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react
Βασική Ενσωμάτωση
HTML/JavaScript
Η έκδοση HTML/JavaScript αυτού του συστατικού μπορεί να χρησιμοποιηθεί με οποιοδήποτε στοίβα ανάπτυξης, όπως PHP, ASP .Net κλπ. Μπορείτε να συνδέσετε το συστατικό απευθείας από το npm αν το περιβάλλον σας δεν επιτρέπει την εγκατάσταση. Μπορείτε να δοκιμάσετε μια σελίδα επίδειξης από το παράδειγμα αποθετηρίου εδώ [https://github.com/legalesign/ls-viewer-demo].
Προσθέστε τα script του συστατικού στο 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>
Αυθεντικοποίηση - Λήψη token
Θα χρειαστεί να χρησιμοποιήσετε κώδικα server-side για να πάρετε το YOUR_AUTH_TOKEN. Υπάρχουν δύο επιλογές, και οι δύο χρησιμοποιούν το API key σας:
- GraphQL
generateComponentToken— Καλέστε το mutation με το API key σας για να δημιουργήσετε ένα βραχυπρόθεσμο, scoped token συστατικού. - REST API — Καλέστε το
GET /templatepdf/{pdfId}/component-token/με το API key σας.
Επιλογή 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;
Επιλογή 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();
Περάστε το επιστρεφόμενο token στο widget. Δείτε Εξουσιοδότηση Widget για περισσότερες λεπτομέρειες σχετικά με τις επιλογές token.
Ενσωμάτωση React
Έχουμε επίσης δημιουργήσει μια έκδοση του συστατικού που ενσωματώνεται απευθείας με τα React frameworks.
import { LsDocumentViewer } from 'legalesign-document-viewer-react';
function App() {
return (
<LsDocumentViewer
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
mode="compose"
/>
);
}
Απαιτούμενα Χαρακτηριστικά
token
Το token ασφαλείας σας για την αυθεντικοποίηση: ένα βραχυπρόθεσμο token συστατικού από το generateComponentToken ή το REST endpoint component-token. Δείτε Εξουσιοδότηση Widget για την ασφαλή διαδικασία token.
token="eyJraWQiOiJBTkJIeT..."
templateid
Το API ID του προτύπου που θέλετε να παρουσιάσετε στους χρήστες. Μπορείτε να το βρείτε κοιτάζοντας το url όταν επεξεργάζεστε το πρότυπο στην Web App.
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
Τρόποι Widget
Λειτουργία Επεξεργασίας
Πλήρως εξοπλισμένη δημιουργία και επεξεργασία προτύπων με όλα τα διαθέσιμα εργαλεία. Αυτό προορίζεται για ροές εργασίας όπου ένα εξαιρετικά επαναχρησιμοποιήσιμο πρότυπο με ρόλους είναι χρήσιμο. Αν η πρόθεσή σας είναι να χρησιμοποιήσετε το έγγραφό σας μόνο μία φορά (ίσως το σύστημά σας δημιουργίας εγγράφων έχει ήδη συμπληρώσει όλες τις πληροφορίες του πελάτη), τότε μπορεί να θέλετε να εξετάσετε τη λειτουργία compose.
<ls-document-viewer mode="editor" ...></ls-document-viewer>
Λειτουργία Σύνθεσης
Αυτή η λειτουργία είναι μια μέθοδος «πρώτα ο παραλήπτης» για την απλοποίηση της εμπειρίας χρήστη. Στην Web App Legalesign αυτή είναι η λειτουργία 'Quick send'.
Προσθέστε τους παραλήπτες σας στο χαρακτηριστικό 'recipients' και ο χρήστης σας μπορεί γρήγορα να τοποθετήσει τις υπογραφές και τα πεδία φορμών, πριν την αποστολή. Ιδανικό για ενσωματωμένους πελάτες όπου οι παραλήπτες έχουν ήδη οριστεί.
Η τυπική ροή εργασίας είναι αντιγραφή ή ανέβασμα PDF, στη συνέχεια ενσωμάτωση του προβολέα όπου ο χρήστης μπορεί να προσθέσει πεδία υπογραφής και φορμών, και τελικά να προσφερθεί ένα κουμπί για αποστολή του εγγράφου.
Αντιγραφή
Αντιγράψτε ένα υπάρχον πρότυπο χρησιμοποιώντας το mutation 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;
Ή Ανέβασμα
Δημιουργήστε ένα πρότυπο και ανεβάστε το στο παρεχόμενο uploadUrl. Χρησιμοποιήστε τίτλο [deleted] αν δεν θέλετε το pdf στη βιβλιοθήκη σας. Θα διαγραφεί μέσα στις επόμενες 24 ώρες. Διαφορετικά, χρησιμοποιήστε οποιονδήποτε τίτλο επιθυμείτε:
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;
Τώρα κάντε PUT το αρχείο σας στο uploadUrl. Ο τύπος περιεχομένου πρέπει να είναι application/pdf.
Ενσωμάτωση προβολέα
Το βασικό χαρακτηριστικό είναι το 'recipients'. Θα χρειαστείτε επιπλέον λεπτομέρειες για εγκριτές ή μάρτυρες - για περισσότερες πληροφορίες δείτε Παραλήπτες.
<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>
Η λειτουργία σύνθεσης αυτόματα:
- Ανιχνεύει προκαθορισμένους παραλήπτες
- Αποκρύπτει τον αποστολέα από το dropdown
- Αποκρύπτει επιλογές εγγράφου
- Εμφανίζει προεπιλεγμένα τα απαιτούμενα πεδία
- Αφαιρεί τον αποστολέα και τα πεδία αποστολέα από τον επεξεργαστή
- Προωθεί την γρήγορη επιλογή των απαιτούμενων πεδίων για κάθε παραλήπτη
Λειτουργία Προεπισκόπησης
Μια βοηθητική προεπισκόπηση εγγράφου που δείχνει το έγγραφο με όλα τα τρέχοντα πεδία και επιτρέπει στον χρήστη να περιηγηθεί μέσα από τις σελίδες.
<ls-document-viewer mode="preview" ...></ls-document-viewer>
Η λειτουργία προεπισκόπησης αυτόματα:
- Αποκρύπτει τη γραμμή εργαλείων
- Αποκρύπτει τις επιλογές εγγράφου
- Αποκρύπτει το toolbox
- Κάνει τους συμμετέχοντες και τα πεδία μόνο για ανάγνωση
Προηγμένη Ρύθμιση
Φίλτρο Toolbox
Περιορίστε τους διαθέσιμους τύπους πεδίων χρησιμοποιώντας τιμές διαχωρισμένες με pipe. Αν δεν δοθεί τιμή, υποτίθεται ότι το toolbox θα είναι χωρίς φίλτρο και όλες οι επιλογές θα είναι διαθέσιμες.
<ls-document-viewer
filtertoolbox="signature|initials|date|text"
...
></ls-document-viewer>
Διαθέσιμες τιμές φίλτρου:
| Τιμή | Περιγραφή |
|---|---|
signature | Πεδίο υπογραφής (μόνο για υπογράφοντα) |
auto sign | Πεδίο αυτόματης υπογραφής (μόνο για αποστολέα) |
text | Ελεύθερη εισαγωγή κειμένου |
signing date | Ημερομηνία συμπληρωμένη αυτόματα κατά την υπογραφή (μόνο για υπογράφοντα) |
date | Επιλογέας ημερομηνίας |
email | Εισαγωγή email |
initials | Πεδίο αρχικών |
number | Αριθμητική είσοδος |
dropdown | Επιλογή από dropdown |
checkbox | Checkbox |
regex | Είσοδος με επαλήθευση regex (μόνο για υπογράφοντα) |
image | Ανέβασμα εικόνας (μόνο για υπογράφοντα) |
file | Ανέβασμα αρχείου (μόνο για υπογράφοντα) |
drawn | Σχεδιασμένο/χειρόγραφο πεδίο (μόνο για υπογράφοντα) |
Παραλήπτες
Ορίστε τους παραλήπτες εγγράφου σε μορφή JSON.
Τα απαραίτητα στοιχεία για κάθε παραλήπτη είναι το firstname, το lastname, το email και το signerIndex;
Προαιρετικά μπορείτε να δώσετε το role και τον αριθμό τηλεφώνου για κάθε παραλήπτη. Η παράλειψη του role σημαίνει ότι ο παραλήπτης θα θεωρείται υπογράφων.
Μπορείτε να ορίσετε ρόλο "WITNESS" ή "APPROVER". Για ρόλο "WITNESS" προσθέστε 100 στο signerIndex του αντίστοιχου υπογράφοντα. Για παράδειγμα, αν χρειάζεστε μάρτυρα για τον υπογράφοντα 2 (signerIndex: 2), ο WITNESS θα έχει 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>
Προσαρμοσμένα Κουμπιά με Slots
Προσθέστε προσαρμοσμένα κουμπιά στη γραμμή εργαλείων χρησιμοποιώντας slots. Πιθανότατα θα τα χρησιμοποιήσετε για να ακυρώσετε τη δράση ή να στείλετε το έγγραφο.
<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>
Χειρισμός Συμβάντων
Ακούστε συμβάντα του συστατικού για να παρακολουθείτε αλλαγές:
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('update', (event) => {
console.log('Template changed:', event.detail);
});
Μπορείτε να παρακολουθείτε αν ένα πρότυπο έχει γίνει έγκυρο ή μη έγκυρο χρησιμοποιώντας το συμβάν validate.
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('validate', (event) => {
console.log('Template validation changed:', event.detail.valid);
});
Παράδειγμα Χειρισμού Συμβάντων σε React
Η χρήση ενός συμβάντος σε react το προθέτει με το οικείο on<EventName>.
<LsDocumentViewer
onUpdate={(event) => {
console.log('Template changed:', event.detail);
}}
...
/>
Τύποι Συμβάντων
Συμβάν update
Εκκινείται όταν το πρότυπο εγγράφου αλλάζει, όπως προσθήκη ή αφαίρεση πεδίων. Παρέχει όχι μόνο το συμβάν που το προκάλεσε αλλά και την ενημερωμένη κατάσταση του αντικειμένου προτύπου ως JSON.
Συμβάν validate
Εκκινείται όταν το πρότυπο εγγράφου αλλάζει, το property valid στο detail δείχνει αν το πρότυπο έχει γίνει έγκυρο ή μη έγκυρο.
Συμβάν selectFields
Εκκινείται όταν επιλέγεται ένα πεδίο στον επεξεργαστή.
Συμβάν addParticipant
Εκκινείται όταν ένας ρόλος συμμετέχοντα προστίθεται στο πρότυπο.
Πλήρες Παράδειγμα
<!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>
Στείλτε το έγγραφο από τον διακομιστή χρησιμοποιώντας το API key σας, είτε με χρήση GraphQL είτε με το REST interface.
- Αποστολή mutation — αποστολή ενός εγγράφου
- Σχήμα Εισόδου Αποστολής — πλήρης αναφορά εισόδων
- Αποστολή REST - αναφορά αποστολής εγγράφου REST
Επίλυση Προβλημάτων
Εάν αντιμετωπίσετε προβλήματα με το συστατικό, βεβαιωθείτε ότι:
- έχετε πρόσβαση ή έχετε προσθέσει στη λίστα επιτρεπόμενων τον τομέα αποθήκευσης εγγράφων στο https://s3.amazonaws.com/*
Υποστήριξη Περιηγητών
Το συστατικό χρησιμοποιεί σύγχρονα διαδικτυακά πρότυπα και υποστηρίζει:
- Chrome/Edge (τελευταία έκδοση)
- Firefox (τελευταία έκδοση)
- Safari (τελευταία έκδοση)
- Περιαγωγικούς περιηγητές (iOS Safari, Chrome Mobile)
Ημερολόγιο Αλλαγών
| Έκδοση | Ημερομηνία | Περίληψη |
|---|---|---|
| v1.0.27 | 19 Οκτ 2026 | Βελτιώσεις στη θέση πεδίων |
| v1.0.26 | 3 Σεπ 2026 | Διορθώσεις κύλισης; Deferred render κατά τη φόρτωση |
| v1.0.21 | 12 Αυγ 2026 | Επιλογές λειτουργίας προεπισκόπησης; βελτιώσεις στο update συμβάν |
| v1.0.18 | 17 Ιουλ 2026 | Πίνακας πεδίων regex; πολλά πεδία με προχωρημένα χαρακτηριστικά; βελτιώσεις dropdown; μετονομασία witness |
| v1.0.12 | 10 Ιουλ 2026 | Ιδιότητα πεδίου excludeFromPdf |
| v1.0.9 | 9 Ιουλ 2026 | Αυτόματη ημερομηνία και πεδία regex; προχωρημένα χαρακτηριστικά; σειρά πεδίων |
| v1.0.6 | 2 Ιουλ 2026 | Διόρθωση γραμματοσειράς που απέτρεπε αποτυχίες υπογραφής; περιθώρια προεπισκόπησης |
| v1.0.5 | 29 Ιουν 2026 | Συντομεύσεις πληκτρολογίου για undo/redo |
| v1.0.4 | 26 Ιουν 2026 | Βελτιώσεις συμβάντων; βελτιστοποιημένες ενημερώσεις; undo/redo |
| v1.0.0 | 24 Ιουν 2026 | Αρχική σταθερή έκδοση |
Πόροι
- Οδηγός Ενσωμάτωσης GraphQL — πώς να συνδέσετε τον προβολέα με το GraphQL API για αποστολή
- Τεκμηρίωση GraphQL API
- Πακέτο NPM
- Πακέτο React
- Υποστήριξη
Λήψη Βοήθειας
Για τεχνική υποστήριξη ή ερωτήσεις σχετικά με την ενσωμάτωση, επικοινωνήστε με την ομάδα υποστήριξης Legalesign ή επισκεφτείτε την τεκμηρίωση API.