Menjana PDF dalam CFML dengan cfdocument

Menjana PDF dalam CFML dengan cfdocument

Tag cfdocument menukar blok CFML dan HTML kepada dokumen PDF tanpa memerlukan pustaka luaran. Anda tulis kandungan sebagai HTML biasa di dalam tag, dan Lucee memaparkannya menjadi fail PDF yang boleh disimpan atau dihantar terus ke pelayar. Artikel ini membimbing anda daripada PDF pertama hingga kawalan halaman, fon, dan prestasi.

Tag cfdocument dan Cara Asas

Contoh paling ringkas ialah membungkus kandungan HTML dalam cfdocument dan menetapkan atribut format="pdf". Jika atribut filename tidak dinyatakan, Lucee menulis PDF terus ke strim respons, jadi ia dibuka dalam pelayar sebagai muat turun:

<cfdocument format="pdf">
<h1>Laporan Jualan</h1>
<p>Jumlah jualan bulan ini adalah memuaskan.</p>
</cfdocument>

Dalam Lucee 7, fungsi PDF disediakan oleh PDF Extension untuk Jakarta EE, jadi pastikan sambungan itu dipasang sebelum cfdocument digunakan. Penukaran Word dan Excel tidak disokong oleh cfdocument, jadi jangan rancang menjana fail .docx atau .xlsx daripadanya.

Menetapkan Saiz Halaman dan Margin

Atribut pagetype menetapkan format halaman, dengan nilai sah legal, letter, A4, A5, B4, B5, B4-JIS, B5-JIS, dan custom. Untuk saiz tersuai, gabungkan pagetype="custom" dengan pagewidth dan pageheight:

<cfdocument format="pdf" pagetype="A4" orientation="portrait"
    margintop="2" marginbottom="2" marginleft="1.5" marginright="1.5">
<h1>Invois</h1>
</cfdocument>

Margin diukur dalam inci secara lalai, dan anda boleh menukar kepada sentimeter dengan menambah atribut unit="cm". Atribut margin tunggal menetapkan keempat-empat sisi serentak, manakala margin dalam bentuk struktur membolehkan nilai berbeza bagi setiap sisi. Orientation pula menerima portrait atau landscape, dengan portrait sebagai lalai.

cfdocumentitem untuk Kepala, Pengaki, dan Pemisah Halaman

Tag cfdocumentitem mengawal elemen berulang dalam dokumen. Atribut type menerima pagebreak untuk memulakan halaman baharu, header untuk kepala yang berulang pada setiap halaman, dan footer untuk pengaki berulang:

<cfdocument format="pdf" pagetype="A4">
<cfdocumentitem type="header">
    <p align="right">Dokumen Sulit</p>
</cfdocumentitem>
<cfdocumentitem type="footer">
    <p align="center">Kedai Dalam Talian, 2026</p>
</cfdocumentitem>
<h1>Bab Satu</h1>
<p>Kandungan bab pertama.</p>
<cfdocumentitem type="pagebreak">
<h1>Bab Dua</h1>
<p>Kandungan bab kedua.</p>
</cfdocument>

Kepala dan pengaki amat berguna untuk invois dan laporan berbilang halaman supaya setiap halaman membawa nombor dokumen atau penjenamaan yang sama tanpa anda mengulang HTML pada setiap bahagian.

cfdocumentsection untuk Bahagian Berbeza

Tag cfdocumentsection membahagikan dokumen kepada bahagian, dan setiap bahagian boleh membawa kepala serta pengaki yang berbeza melalui cfdocumentitem. Ia juga membolehkan anda menukar orientasi halaman pada bahagian tertentu, contohnya bahagian landskap untuk jadual lebar diikuti bahagian potret untuk teks:

<cfdocument format="pdf">
<cfdocumentsection orientation="landscape">
<cfdocumentitem type="header">Jadual Data Tahunan</cfdocumentitem>
<h1>Jadual Data</h1>
</cfdocumentsection>
<cfdocumentsection orientation="portrait">
<cfdocumentitem type="header">Analisis</cfdocumentitem>
<h1>Analisis</h1>
</cfdocumentsection>
</cfdocument>

Atribut orientation menerima landscape atau portrait dan lalai kepada orientasi cfdocument yang melingkunginya, manakala margin setiap bahagian boleh dilaraskan melalui margintop dan seumpamanya. Atribut name pula menetapkan nama penanda buku bagi bahagian itu.

Gaya Cetak dan Pemisah Halaman

Kerana kandungan cfdocument ialah HTML, anda mengawal rupa menggunakan CSS yang sama seperti halaman web, termasuk warna, jidar, dan saiz fon. Dua sifat khusus cetakan patut diberi perhatian: page-break-before dan page-break-after untuk memaksa pemisahan halaman pada elemen tertentu, dan @page untuk kawalan halaman.

Satu kehalusan penting ialah enjin PDF tidak memahami keseluruhan CSS moden seperti grid dan flexbox. Kekal dengan susun atur berasaskan jadual dan blok yang ringkas supaya hasil PDF konsisten dengan apa yang anda lihat dalam pelayar.

Imej dalam PDF

Imej boleh dimasukkan dengan tag img biasa yang menunjuk kepada fail tempatan atau URL. Atribut localUrl pada cfdocument menentukan sama ada imej diambil terus dari cakera tempatan, yang mempercepatkan pemprosesan apabila semua aset berada pada pelayan yang sama:

<cfdocument format="pdf" pagetype="A4" localUrl="true">
<h1>Katalog Produk</h1>
<img src="/aset/produk-1.jpg" width="300">
<p>Penerangan produk.</p>
</cfdocument>

Pastikan laluan imej boleh diakses oleh proses Lucee, dan gunakan format yang disokong seperti JPG dan PNG. Imej bersaiz besar meningkatkan saiz PDF akhir, jadi kecilkan imej dahulu sebelum dimasukkan, satu topik yang dibincangkan dalam panduan memproses imej.

Fon dan fontembed

Atribut fontembed menentukan sama ada fon dibenamkan ke dalam PDF. Membenamkan fon memastikan dokumen kelihatan sama pada setiap mesin, tetapi menambah saiz fail. Atribut fontdirectory pula menunjuk kepada direktori yang mengandungi fon tersuai yang ingin anda gunakan dalam dokumen.

Untuk teks Bahasa Melayu, kebanyakan fon lalai menyokong aksara Latin dengan baik, jadi isu fon jarang timbul melainkan anda menggunakan aksara khas atau fon jenama tersendiri. Apabila menggunakan fon tersuai, benamkannya supaya penerima tidak melihat penggantian fon yang tidak diingini.

Perlindungan PDF dengan Kata Laluan dan Keizinan

cfdocument menyokong penyulitan dokumen melalui atribut encryption, userpassword untuk kata laluan membuka dokumen, dan ownerpassword untuk kata laluan pemilik. Atribut permissions menghadkan apa yang boleh dilakukan penerima, dengan nilai seperti AllowPrinting, AllowCopy, dan AllowModifyContents:

<cfdocument format="pdf" encryption="128-bit"
    userpassword="buka123" ownerpassword="pemilik123"
    permissions="AllowPrinting,AllowCopy">
<h1>Dokumen Rahsia</h1>
</cfdocument>

Gunakan ciri ini untuk invois dan laporan kewangan yang sepatutnya tidak mudah disalin atau diubah oleh penerima.

Jenis Kandungan yang Sesuai

cfdocument paling sesuai untuk dokumen berstruktur yang paparannya boleh diramal: invois, laporan, penyata, surat rasmi, dan sijil. Kandungan ini berkongsi ciri susun atur halaman tetap yang menjadi kekuatan PDF. Jadual berikut meringkaskan padanan antara jenis kandungan dan sebab PDF sesuai untuknya:

Untuk kandungan yang berubah-ubah seperti halaman web interaktif, PDF ialah format yang salah, dan anda sepatutnya mengekalkannya sebagai HTML.

Data untuk dokumen ini lazimnya datang daripada pangkalan data, jadi gabungkan cfdocument dengan query yang selamat seperti yang dijelaskan dalam panduan cfquery dan cfqueryparam.

Menulis ke Fail lawan Respons

Selain menghantar terus ke pelayar, anda boleh menyimpan PDF ke cakera dengan atribut filename, dan atribut overwrite mengawal sama ada fail sedia ada diganti. Atribut name pula menyimpan kandungan PDF ke dalam pemboleh ubah dalam memori, berguna apabila anda ingin menghantar PDF itu sebagai lampiran e-mel menggunakan cfmail tanpa menulis fail perantaraan:

cfdocument(format="pdf", pagetype="A4", name="pdfInvois") {
    writeOutput("<h1>Invois</h1>");
}
mail from="kedai@contoh.com" to="pelanggan@contoh.com" subject="Invois Anda" {
    cfmailparam(type="application/pdf", content=pdfInvois, filename="invois.pdf");
};

Prestasi untuk Dokumen Besar

Penjanaan PDF menggunakan memori dan CPU, dan dokumen besar dengan banyak halaman boleh memperlahankan permintaan. Untuk dokumen berat, jana PDF secara tak segerak dan simpan hasilnya, kemudian sediakan untuk muat turun, dan bukannya menjana semula pada setiap permintaan. Cache hasil yang tidak berubah seperti yang dibincangkan dalam panduan caching dan prestasi.

Pantau juga memori JVM: penjanaan PDF yang kerap menambah tekanan pada timbunan, dan pelarasan saiz timbunan yang betul membantu mengelak kegagalan OutOfMemory, seperti yang dijelaskan dalam panduan tala JVM Lucee.

Had dan Alternatif Sambungan PDF

cfdocument ialah pilihan baik untuk kebanyakan dokumen, tetapi ia ada had: kawalan susun atur yang halus sukar dicapai berbanding pustaka khusus, dan enjin HTML-ke-PDF tidak menyokong CSS moden sepenuhnya. Untuk keperluan lanjutan seperti manipulasi PDF sedia ada, Lucee menyediakan tag cfpdf untuk menggabung, memecah, dan mengekstrak halaman, bersama cfpdfparam untuk tindakan merge.

Jika anda memerlukan templat reka bentuk yang sangat tepat atau isipadu penjanaan yang sangat tinggi, pertimbangkan alat penjanaan PDF luaran yang dipanggil daripada CFML, tetapi untuk kebanyakan invois dan laporan, cfdocument sudah memadai dan menjimatkan banyak kerja.

Soalan Lazim (FAQ)

Bagaimana cara menjana PDF dalam CFML?

Guna tag cfdocument dengan atribut format="pdf" dan tulis kandungan HTML di dalamnya, kemudian simpan dengan filename atau hantar terus ke pelayar.

Bagaimana cara menetapkan saiz halaman dalam cfdocument?

Guna atribut pagetype dengan nilai seperti A4 atau letter, atau pagetype="custom" bersama pagewidth dan pageheight untuk saiz tersuai.

Bagaimana cara menambah kepala dan pengaki pada setiap halaman?

Guna tag cfdocumentitem dengan type="header" atau type="footer", dan kandungannya akan berulang pada setiap halaman dokumen.

Bolehkah cfdocument melindungi PDF dengan kata laluan?

Ya, guna atribut userpassword untuk kata laluan membuka dokumen dan ownerpassword untuk kata laluan pemilik, bersama encryption dan permissions.

Bagaimana cara melampirkan PDF yang dijana ke e-mel?

Simpan PDF ke pemboleh ubah dengan atribut name, kemudian hantar menggunakan cfmailparam dengan type="application/pdf".

Sumber

• cfdocument, docs.lucee.org
• cfdocumentitem, docs.lucee.org
• cfdocumentsection, docs.lucee.org
• PDFs, docs.lucee.org
• cfpdf, docs.lucee.org
• Lucee Documentation