📘 תיעוד 201

בניית מחולל קוד QR

במדריך הזה תבנו ותפרסמו יישום Worker שמייצר קודי QR.

אם תרצו לעיין בקוד של המדריך הזה, הגרסה הסופית של בסיס הקוד זמינה ב-GitHub ↗︎. אפשר לקחת את הקוד שמופיע במאגר הדוגמה, להתאים אותו, ולפרוס אותו לשימוש בפרויקטים שלכם.

#לפני שמתחילים

כל המדריכים מניחים שכבר השלמתם את מדריך תחילת העבודה, שמכין אתכם עם חשבון Cloudflare Workers, C3 ↗︎ ו-Wrangler.

#1. יצירת פרויקט Workers חדש

קודם, השתמשו ב-create-cloudflare CLI כדי ליצור פרויקט Cloudflare Workers חדש. כדי לעשות זאת, פתחו חלון מסוף והריצו את אחת הפקודות הבאות:

npm:

npm create cloudflare@latest -- qr-code-generator

yarn:

yarn create cloudflare qr-code-generator

pnpm:

pnpm create cloudflare@latest qr-code-generator

בהגדרה, בחרו את האפשרויות הבאות:

• עבור What would you like to start with?, בחרו Hello World example.
• עבור Which template would you like to use?, בחרו Worker only.
• עבור Which language do you want to use?, בחרו JavaScript.
• עבור Do you want to use git for version control?, בחרו Yes.
• עבור Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, בחרו Yes.
• עבור Do you want to deploy your application?, בחרו No (נבצע כמה שינויים לפני הפריסה).

אחר כך, עברו לספרייה החדשה שיצרתם:

cd qr-code-generator

בתוך ספריית פרויקט ה-Worker החדשה qr-code-generator, הקובץ index.js מייצג את נקודת הכניסה ליישום Cloudflare Workers שלכם.

כל יישומי Cloudflare Workers מתחילים בהאזנה לאירועי fetch, שמופעלים כשלקוח שולח בקשה לנתיב Workers. אחרי שה-Worker מקבל בקשה, התגובה שהיישום שלכם בונה תוחזר למשתמש. המדריך הזה ילווה אתכם בהבנה של אופן הפעולה של דפוס הבקשה והתגובה, ואיך אפשר להשתמש בו כדי לבנות יישומים מלאים.

export default {
	async fetch(request, env, ctx) {
		return new Response("Hello Worker!");
	},
};

בקובץ index.js ברירת המחדל אפשר לראות את דפוס הבקשה והתגובה בפעולה. ה-fetch בונה Response חדש עם טקסט הגוף 'Hello Worker!'.

כש-Worker מקבל אירוע fetch, ה-Worker מחזיר ללקוח את התגובה שנבנתה זה עתה. ה-Worker שלכם יגיש תגובות חדשות ישירות מ-הרשת הגלובלית של Cloudflare ↗︎ במקום להמשיך לשרת המקור שלכם. שרת רגיל היה מקבל בקשות ומחזיר תגובות. Cloudflare Workers מאפשר להגיב במהירות על ידי בניית תגובות ישירות ברשת הגלובלית של Cloudflare.

#2. טיפול בבקשה נכנסת

כל פרויקט שמפרסמים ל-Cloudflare Workers יכול להשתמש בכלי JavaScript מודרניים כמו מודולי ES, חבילות npm ופונקציות async/await ↗︎ כדי לבנות את היישום. בנוסף לכתיבת Workers, אפשר להשתמש ב-Workers כדי לבנות יישומים מלאים באמצעות אותם כלים ואותו תהליך כמו במדריך הזה.

מחולל קוד ה-QR שתבנו במדריך הזה יהיה Worker שרץ על נתיב יחיד ומקבל בקשות. כל בקשה תכיל הודעת טקסט (לדוגמה כתובת URL), שהפונקציה תקודד לקוד QR. אחר כך הפונקציה תגיב עם קוד ה-QR בפורמט תמונת PNG.

בשלב הזה במדריך, פונקציית ה-Worker יכולה לקבל בקשות ולהחזיר תגובה פשוטה עם הטקסט "Hello Worker!". כדי לטפל בנתונים שנכנסים ל-Worker, בדקו אם הבקשה הנכנסת היא בקשת POST:

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return new Response("Hello Worker!");
		}
	},
};

כרגע, אם בקשה נכנסת אינה POST, הפונקציה תחזיר undefined. עם זאת, Worker תמיד צריך להחזיר Response. מכיוון שהפונקציה צריכה לקבל רק בקשות POST נכנסות, החזירו Response חדש עם קוד סטטוס 405 ↗︎ אם הבקשה הנכנסת אינה POST:

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return new Response("Hello Worker!");
		}

		return new Response("Expected POST request", {
			status: 405,
		});
	},
};

קבעתם את הזרימה הבסיסית של הבקשה. עכשיו תגדירו תגובה לבקשות תקינות נכנסות. אם מגיעה בקשת POST, הפונקציה צריכה לייצר קוד QR. כדי להתחיל, העבירו את תגובת "Hello Worker!" לפונקציה חדשה, generateQRCode, שבסופו של דבר תכיל את עיקר הלוגיקה של הפונקציה:

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
		}
	},
};

async function generateQRCode(request) {
	// TODO: Include QR code generation
	return new Response("Hello worker!");
}

אחרי שפונקציית generateQRCode מולאה, קראו לה מתוך פונקציית fetch והחזירו את התוצאה שלה ישירות ללקוח:

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return generateQRCode(request);
		}
	},
};

#3. בניית מחולל קוד QR

כל הפרויקטים שנפרסים ל-Cloudflare Workers תומכים בחבילות npm. התמיכה הזו מקלה לבנות במהירות פונקציונליות ב-Workers. החבילה 'qrcode-svg' ↗︎ היא דרך טובה לקחת טקסט ולקודד אותו לקוד QR. בשורת הפקודה, התקינו ושמרו את 'qrcode-svg' ב-package.json של הפרויקט באמצעות אחת הפקודות הבאות:

npm:

npm i qrcode-svg

yarn:

yarn add qrcode-svg

pnpm:

pnpm add qrcode-svg

bun:

bun add qrcode-svg

ב-index.js, ייבאו את החבילה qrcode-svg כמשתנה QRCode. בפונקציה generateQRCode, נתחו את הבקשה הנכנסת כ-JSON באמצעות request.json, וצרו קוד QR חדש באמצעות החבילה qrcode-svg. קוד ה-QR נוצר כ-SVG. בנו מופע חדש של Response, העבירו את נתוני ה-SVG כגוף, וכותרת Content-Type עם הערך image/svg+xml. זה יאפשר לדפדפנים לנתח נכון את הנתונים שחוזרים מה-Worker כתמונה:

import QRCode from "qrcode-svg";

async function generateQRCode(request) {
	const { text } = await request.json();
	const qr = new QRCode({ content: text || "https://workers.dev" });
	return new Response(qr.svg(), {
		headers: { "Content-Type": "image/svg+xml" },
	});
}

#4. בדיקה בממשק יישום

ה-Worker ירוץ כשמשתמש שולח בקשת POST לנתיב, אבל מומלץ גם לספק ממשק מתאים לבדיקת הפונקציה. בשלב הזה במדריך, אם הפונקציה מקבלת בקשה שאינה POST, מוחזרת תגובת 405. הגרסה החדשה של fetch צריכה להחזיר Response חדש עם מסמך HTML סטטי במקום שגיאת 405:

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return generateQRCode(request);
		}

		return new Response(landing, {
			headers: {
				"Content-Type": "text/html",
			},
		});
	},
};

async function generateQRCode(request) {
	const { text } = await request.json();
	const qr = new QRCode({ content: text || "https://workers.dev" });
	return new Response(qr.svg(), {
		headers: { "Content-Type": "image/svg+xml" },
	});
}

const landing = `
<h1>QR Generator</h1>
<p>Click the below button to generate a new QR code. This will make a request to your Worker.</p>
<input type="text" id="text" value="https://workers.dev"></input>
<button onclick="generate()">Generate QR Code</button>
<p>Generated QR Code Image</p>
<img id="qr" src="#" />
<script>
	function generate() {
		fetch(window.location.pathname, {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({ text: document.querySelector("#text").value })
		})
		.then(response => response.blob())
		.then(blob => {
			const reader = new FileReader();
			reader.onloadend = function () {
				document.querySelector("#qr").src = reader.result; // Update the image source with the newly generated QR code
			}
			reader.readAsDataURL(blob);
		})
	}
</script>
`;

המשתנה landing, שהוא מחרוזת HTML סטטית, מגדיר תג input ו-button מתאים, שקורא לפונקציה generateQRCode. הפונקציה הזו תשלח בקשת HTTP POST בחזרה ל-Worker, וכך תוכלו לראות בדף את תמונת קוד ה-QR המתאימה שמוחזרת.

אחרי השלמת השלבים שלמעלה, ה-Worker מוכן. הגרסה המלאה של הקוד נראית כך:

const QRCode = require("qrcode-svg");

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return generateQRCode(request);
		}

		return new Response(landing, {
			headers: {
				"Content-Type": "text/html",
			},
		});
	},
};

async function generateQRCode(request) {
	const { text } = await request.json();
	const qr = new QRCode({ content: text || "https://workers.dev" });
	return new Response(qr.svg(), {
		headers: { "Content-Type": "image/svg+xml" },
	});
}

const landing = `
<h1>QR Generator</h1>
<p>Click the below button to generate a new QR code. This will make a request to your Worker.</p>
<input type="text" id="text" value="https://workers.dev"></input>
<button onclick="generate()">Generate QR Code</button>
<p>Generated QR Code Image</p>
<img id="qr" src="#" />
<script>
	function generate() {
		fetch(window.location.pathname, {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({ text: document.querySelector("#text").value })
		})
		.then(response => response.blob())
		.then(blob => {
			const reader = new FileReader();
			reader.onloadend = function () {
				document.querySelector("#qr").src = reader.result; // Update the image source with the newly generated QR code
			}
			reader.readAsDataURL(blob);
		})
	}
</script>
`;

#5. פריסת ה-Worker

אחרי השלמת כל השלבים שלמעלה, כתבתם את הקוד למחולל קוד QR ב-Cloudflare Workers.

ל-Wrangler יש תמיכה מובנית באריזה, בהעלאה ובשחרור של יישום Cloudflare Workers. כדי לעשות זאת, הריצו את npx wrangler deploy, שיבנה ויפרוס את הקוד.

Deploy your Worker projectsh

npx wrangler deploy

#משאבים קשורים

במדריך הזה בניתם ופרסתם יישום Worker ליצירת קודי QR. אם תרצו לראות את קוד המקור המלא של היישום הזה, אפשר למצוא אותו ב-GitHub ↗︎.

אם תרצו להתחיל לבנות פרויקטים משלכם, עיינו ברשימה הקיימת של תבניות Quickstart.