درس

الجولة

درس: قائمة المهام

ابنِ قائمة مهام تبقى في متصفح القارئ: أنواع، ومخزن يتذكّر، ومكوّن، ومرشّح في العنوان، واختبارات تنقر.

يبني هذا الدرس قائمة مهام تبقى في متصفح القارئ، فيها مخزن (store) ومكوّن ومرشّح في العنوان واختبارات تنقر.

ملاحظة

لم تُترجم كل فصول الدليل بعد: الروابط إلى فصل غير مترجم تفتح نسخته الإنجليزية.

هو ثاني دروس الكتاب، بعد Shelf. ويبني مشروعان أطول في الوصفات على الاثنين. قائمة المهام والمشروعان الأطول موجودة كاملة في المستودع تحت examples/tutorials/، ولا يحتاج أي منها إلى خادم: ما يحفظه المشروع يحفظه في متصفح القارئ.

درس: قائمة المهام
المشروع ما تبنيه ما يعلّمه الوقت

Shelf (الفصل 2)

موقع قائمة قراءة: صفحة لكل كتاب، ورفّ محفوظ، ونموذج

data ذات أنواع، ومكوّن، وصفحات :slug، ومخزن بـpersist، ونموذج، وسمة، واختبار، ونشر

نصف ساعة

قائمة المهام (هذا الفصل)

قائمة بما عليك فعله: أضف، وعلّم، وأعد التسمية، ورشّح

الأنواع، ومخزن بـpersist، ومكوّن، وقائمة بمفاتيح، ومرشّح في العنوان، واختبارات تنقر

20 دقيقة

Field Notes (مشروع أطول)

موقع دفتر ملاحظات، مبني بناءً ثابتًا، بصفحة لكل ملاحظة

ملفات data، وتخطيط، وصفحات :slug مع paths:، وصفحات Markdown، والبحث والوسوم، وما يمكن لصفحة مُصيَّرة مسبقًا أن تعرفه

ساعة

Pocket (مشروع أطول)

متتبّع ميزانية بلوحة معلومات ونماذج ولغتين

Money وDate، والمجاميع المشتقة، وترحيل persist، وvalidate، ونافذة حوار واختصارات، والترجمة (i18n) والنص من اليمين إلى اليسار، وسكربت من كتابتك، والعمل دون اتصال

بضع ساعات

إن لم تكتب WebFluent من قبل، فابدأ بـدرس Shelf: نصف ساعته الأولى ألطف.

ما ستبنيه. قائمة بما عليك فعله، تبقى في متصفح القارئ: أضف مهمة، وعلّمها منجزة، وأعد تسميتها، واحذفها، واعرض المفتوحة منها فقط. هي صفحة واحدة ومخزن واحد ومكوّن واحد. المشروع المكتمل هو examples/tutorials/easy-todos.

الوقت: نحو 20 دقيقة.

قبل أن تبدأ

تحتاج إلى:

  • wf مثبّتًا وفي PATH لديك — يطبع wf --version القيمة wf 7.0.0 أو أحدث (البدء).
  • Chrome أو Chromium على الجهاز، للاختبارات التي تنقر ولـwf verify. اضبط WF_CHROME على مساره إن لم يكن في مكان معتاد.
  • Git، لجلب المشاريع المكتملة.

كل كتلة شيفرة يسمّي سطرها الأول ملفًا — // src/stores/Todos.wf — هي ذلك الملف، أو مجموعة متتالية من أسطره، كما هي في المشروع تمامًا. يُلزم اختبارٌ هذا الفصل بالمشاريع، فالشيفرة التي تقرؤها هنا هي الشيفرة التي تُبنى.

لتبدأ من مشروع مكتمل بدلًا من ذلك، انسخ المستودع وشغّل أحد المشاريع:

bash

$ git clone https://github.com/monzeromer-lab/WebFluent $ cd WebFluent/examples/tutorials/easy-todos $ wf serve

تحقّق: تطبع الطرفية Starting dev server at http://localhost:3000/، ويعرض ذلك العنوان المشروع.

لا تحتاج في هذا الدرس إلا إلى wf وChrome. تكتب كل ملف في هذا المشروع بنفسك، والكتل أدناه تحمل كل ملف كاملًا، إلا الاختبارات، إذ يظهر منها واحد من ستة.

الخطوة 1: أنشئ المشروع

أنشئ مشروع صفحة واحدة وادخل إليه:

bash

$ wf init todos -t spa $ cd todos

احذف كل ما وضعه القالب في src/ وtests/: ستكتب كل ملف بنفسك، واختبارات القالب ستفشل دون صفحاته. ثم استبدل webfluent.app.json بهذا:

json

{ "name": "todos", "version": "1.0.0", "theme": { "name": "Paper", "dark": "Night" }, "build": { "output": "./build", "output_type": "spa", "csp": true }, "meta": { "title": "Todos", "description": "A small list of things to do, kept in your browser.", "lang": "en", "favicon": "/favicon.svg" } }
  • "output_type": "spa" يصنع تطبيق صفحة واحدة: غلاف HTML واحد، تُبدَّل فيه الصفحات دون إعادة تحميل (المواقع الثابتة وتطبيقات الصفحة الواحدة).
  • "csp": true يشحن سياسة أمان المحتوى ويُلزم البناء بها (الأمان).
  • يسمّي theme سمتين (themes)، Paper وNight، تكتبهما في الخطوة التالية.
  • favicon هي الأيقونة في تبويب المتصفح. يُقدَّم الملف الموجود في public/ من جذر الموقع، فضع واحدة في public/favicon.svg:

bash

$ mkdir -p public $ printf '%s' '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#0F766E"/><path d="M9 16l5 5 9-10" stroke="#fff" stroke-width="3" fill="none"/></svg>' > public/favicon.svg

تحقّق: يطبع wf check الرسالة IO Error: No .wf files found in src/. هذا متوقّع: يبقى src/ فارغًا حتى الخطوة التالية.

الخطوة 2: أعطه مظهرًا خاصًا به

الإعدادات تسمّي سمة، فصرّح بها أولًا. لا تسمّي السمة إلا رموز التصميم (design tokens) التي تغيّرها؛ ويبقى كل رمز آخر على قيمته الافتراضية (التنسيق). Night هي السمة المسمّاة "dark" في الإعدادات، وتستعملها الصفحة حين يكون نظام القارئ على الوضع الداكن:

wf

// src/theme.wf /// Warm paper and ink, with one teal for what you can act on. theme Paper { color-primary: #0F766E color-background: #F6F4EF color-surface: #FFFFFF color-text: #1F2328 color-text-muted: #5E6670 color-border: #E4E0D8 font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif radius-md: 10px } /// The same page after dark. theme Night { color-primary: #2DD4BF color-on-primary: #14171A color-background: #14171A color-surface: #1C2024 color-text: #ECEEF0 color-text-muted: #A3ABB3 color-border: #2C3238 }

الأخضر المزرقّ في Night فاتح، فيصعب قراءة نص أبيض فوقه؛ لذلك يضبط Night أيضًا color-on-primary، لون نص الزر الأساسي، على لون الخلفية الداكن. يُبلّغ wf check عن زوج كهذا بـA13 في أيّ من السمتين.

الصفحة التي تكتبها في الخطوة 6 تسمّي أصنافًا (classes) — card وtodo وis-done وfilters — ويُنسّقها src/todos.css. يجمع البناء كل ملف .css تحت src/، فلا يحتاج الملف إلى رابط. هذه أربع من قواعده؛ انسخ الملف كاملًا من المشروع المكتمل:

css

.todo { flex-wrap: nowrap; padding: 0.6rem 0.25rem; border-top: 1px solid var(--color-border); } .todo__title { flex: 1; } .todo.is-done .todo__title { text-decoration: line-through; color: var(--color-text-muted); } .filters a.is-on { background: var(--color-background); color: var(--color-text); font-weight: 600; }

كل لون رمز، var(--color-border)، فتعيد السمة الداكنة تلوين الصفحة دون قاعدة خاصة بها.

تحقّق: يطبع wf check الرسالة No problems in todos.

الخطوة 3: صِف المهمة

يسمّي type الحقول التي تملكها القيمة، ويُلزم المدقّق كل استعمال بها (الأنواع). وenum مجموعة ثابتة من الحالات:

wf

// src/types.wf /// One thing to do. type Todo { id: Uuid title: String done: Bool = false } /// Which todos the list shows. enum Filter { all, open, done }
  • Uuid من الأنواع التي تأتي مع اللغة؛ وuuid() تصنع قيمة منه.
  • للحقل done قيمة افتراضية، فيمكن للمهمة الجديدة أن تُغفله.
  • تُكتب الحالة بنقطة، .open، حيثما يُطلب Filter.

لأن المدقّق يعرف الحقول، فإن todo.titel خطأ في الموضع الذي كُتب فيه، والرسالة تسمّي الحقل الذي قصدته.

تحقّق: يطبع wf check الرسالة No problems in todos.

الخطوة 4: اكتب مخزنًا يتذكّر

يحمل المخزن حالة يمكن لأي صفحة أو مكوّن قراءتها (المخازن). هذا المخزن يحفظ القائمة:

wf

// src/stores/Todos.wf /// The list, kept in the browser between visits. store Todos { persist items: [Todo] = [] derived open = items.filter(todo => !todo.done) derived done = items.filter(todo => todo.done) action add(title: String) { let text = title.trim() if text == "" { return } items = items.concat([Todo(id: uuid(), title: text)]) } action toggle(id: Uuid) { items = items.map(todo => if todo.id == id { { ...todo, done: !todo.done } } else { todo }) } action rename(id: Uuid, title: String) { let text = title.trim() if text == "" { return } items = items.map(todo => if todo.id == id { { ...todo, title: text } } else { todo }) } action remove(id: Uuid) { items = items.filter(todo => todo.id != id) } action clearDone() { items = items.filter(todo => !todo.done) } }
  • persist حالة (state) تُحفظ في تخزين المتصفح. تبقى القائمة بعد إعادة التحميل، ويتبع التبويب الثاني الأول، دون أن تكتب شيفرة تخزين.
  • القيمة المشتقة (derived) تتبع ما تقرؤه: open هي دائمًا المهام التي لم تُنجز بعد.
  • الإجراء (action) هو المكان الوحيد الذي تتغيّر فيه الحالة. { ...todo, done: !todo.done } هي المهمة نفسها مع تغيير حقل واحد.
  • يغيّر rename وremove وclearDone القائمة بالطريقة نفسها.

ملاحظة

قادم من Vue؟ القيمة derived هي computed بلا دالة تكتبها ولا .value تقرؤه: Todos.open هي القائمة نفسها. انظر القادمون من Vue.

تحقّق: يطبع wf check سبعة تحذيرات U04، مثل `warning[U04]: Todos.open is declared but never read`. هذا متوقّع: لا شيء يقرأ المخزن بعد. الصفحة في الخطوة 6 تقرأ كل عضو فيه، فتزول التحذيرات.

الخطوة 5: ابنِ صفًا واحدًا

المكوّن عنصر من صنعك (المكوّنات). هذا المكوّن يرسم مهمة واحدة، ويتيح للقارئ إعادة تسميتها في مكانها:

wf

// src/components/TodoRow.wf /// One row of the list: a box to tick, the title, and buttons to rename and /// remove it. component TodoRow(_ todo: Todo) { use Todos state editing = false state draft = todo.title action save() { Todos.rename(todo.id, draft) editing = false } Row(class: ["todo", if todo.done { "is-done" }], align: .center, gap: .sm) { Checkbox(checked: todo.done, aria-label: "Done: {todo.title}") { on change { Todos.toggle(todo.id) } } if editing { // `mount:` runs when the input is made: the cursor goes straight in. Input(bind: draft, aria-label: "New title for {todo.title}", class: "todo__edit", mount: (n) => n.focus()) { on key("Enter") { save() } on key("Escape") { draft = todo.title editing = false } on blur { save() } } } else { Text(todo.title, class: "todo__title") IconButton(icon: "edit", label: "Rename {todo.title}", class: "todo__action").sm { on click { draft = todo.title editing = true } } } IconButton(icon: "trash", label: "Remove {todo.title}", class: "todo__action").sm { on click { Todos.remove(todo.id) } } } }
  • _ todo هي الخاصية (prop) الموضعية الوحيدة للمكوّن، فيُكتب الاستدعاء TodoRow(todo).
  • حالته (state) ملك لكل صف: إعادة تسمية صف لا تضع الصفوف الأخرى في وضع التحرير.
  • يضيف class: أصنافًا إلى أصناف العنصر نفسه. ويمكن لصيغة القائمة أن تحمل if، فلا تضيف is-done إلا ما دامت المهمة منجزة.
  • لكل عنصر تحكّم اسم يُتاح لتقنيات المساعدة. مربع الاختيار وأزرار الأيقونات تقول أي مهمة تعمل عليها، فيمكن لقارئ الشاشة — ولاختبارات الخطوة 7 — أن يميّز بينها (إمكانية الوصول).

تحقّق: يطبع wf check التحذير U03 لـTodoRow (لا شيء يضعه بعد) وأربعة تحذيرات U04. لم تعد toggle وrename وremove الخاصة بالمخزن تظهر: الصف يستدعيها.

الخطوة 6: اكتب الصفحة

تحمل الصفحة مربع المهمة الجديدة والمرشّحات والقائمة. هذا نصفها الأول:

wf

// src/pages/Home.wf page Home(path: "/", title: "Todos", description: "A small list of things to do, kept in your browser.") { use Todos state draft = "" // The filter lives in the address — `/?show=open` — so a reload or a // shared link keeps it. derived filter: Filter = if query.show == "open" { .open } else if query.show == "done" { .done } else { .all } derived shown = match filter { .open { Todos.open } .done { Todos.done } .all { Todos.items } } action add() { Todos.add(draft) draft = "" } Stack(class: "card", gap: .md) { Row(justify: .between, align: .baseline) { Heading("Todos").h1 Text("{Todos.open.length} left", class: "count") } Row(class: "new", gap: .sm) { Input(bind: draft, placeholder: "What needs doing?", aria-label: "New todo") { on key("Enter") { add() } } Button("Add", disabled: draft.trim() == "").primary { on click { add() } } }
  • bind: draft يربط حقل الإدخال بالحالة في الاتجاهين: الكتابة تغيّر draft، وdraft = "" تفرغ المربع.
  • query هي سلسلة الاستعلام في العنوان بوصفها قيمة، تبقى محدّثة. لذا يتبع filter العنوان، ويتبع shown المرشّح filter.
  • يجب أن يغطي match على enum كل حالة. إن أضفت حالة رابعة إلى Filter، يصبح هذا الـmatch خطأ حتى يعالجها.

يرسم النصف الثاني المرشّحات والقائمة، ويغلق الصفحة. أضفه تحت النصف الأول، بعد سطر فارغ:

wf

// src/pages/Home.wf Row(class: "filters", gap: .xs, align: .center) { Link("All", to: "/?show=all", class: { "is-on": filter == .all }) Link("Open", to: "/?show=open", class: { "is-on": filter == .open }) Link("Done", to: "/?show=done", class: { "is-on": filter == .done }) Spacer if Todos.done.length > 0 { Button("Clear done").sm { on click { Todos.clearDone() } } } } if shown.length == 0 { Text(if Todos.items.length == 0 { "Nothing yet — add your first todo above." } else { "Nothing here." }, class: "empty") } Stack(class: "list") { for todo in shown by todo.id { TodoRow(todo, animate: .fadeIn, exit: .fadeOut) } } } Text("Your list stays in this browser, and nowhere else.", class: "hint") }
  • for … by todo.id قائمة بمفاتيح. حين تُعاد تسمية مهمة، أو يخفيها المرشّح، لا يتغيّر إلا صفها؛ وتحتفظ الصفوف الأخرى بعناصرها، ويحتفظ الصف قيد التحرير بمؤشّره (التحكم في التدفق).
  • animate: وexit: يُظهران الصف ويُخفيانه بتلاشٍ.
  • خريطة الأصناف، { "is-on": filter == .all }، تفعّل الصنف ما دام شرطه قائمًا.

ملاحظة

قادم من React؟ يوضع المفتاح على الحلقة، by todo.id، لا بوصفه خاصية key على الصف. انظر القادمون من React.

أخيرًا، التصريح app هو الإطار الذي تجلس فيه كل صفحة. يحدّد Router موضع رسم الصفحة الحالية:

wf

// src/App.wf // The frame every page sits in: a narrow column, centred. app { Container(class: "shell") { Router } }

الآن شغّل خادم التطوير في طرفية ثانية، واتركه يعمل. كل حفظ يعيد بناء المشروع ويعيد تحميل الصفحة:

bash

$ wf serve

تحقّق: يطبع wf check الرسالة No problems in todos.، ويعرض <http://localhost:3000/> بطاقة عنوانها Todos فيها 0 left وNothing yet — add your first todo above. اكتب مهمة واضغط Enter: تظهر، ويصبح العدّاد 1 left. أعد تحميل الصفحة، فتجد المهمة ما زالت هناك. انقر Open، فيصبح العنوان /?show=open.

إن طبع الخادم `No theme Paper is declared in this project، فالأرجح أنك تخطّيت src/theme.wf في الخطوة 2. وإن ظهر عضو في المخزن بالتحذير U04` هنا، فالأرجح أنك أغفلت جزءًا من الصفحة.

الخطوة 7: اكتب الاختبارات

يرسم الاختبار ما يصرّح به، ثم ينفّذ خطواته بالترتيب. يكتب في عنصر التحكم المسمّى New todo وينقر الزر المسمّى Add، كما يفعل القارئ (الاختبار). أنشئ tests/todos.wf بهذا الاختبار:

wf

// tests/todos.wf test "adding a todo puts it in the list" { use Todos state draft = "" Input(bind: draft, aria-label: "New todo") Button("Add") { on click { Todos.add(draft) draft = "" } } for todo in Todos.items by todo.id { TodoRow(todo) } Text("{Todos.open.length} left") expect "0 left" type "Buy bread" into "New todo" click "Add" expect "Buy bread" expect "1 left" }

الاختبار الذي ينقر أو يكتب يعمل في Chrome بلا واجهة (headless). في المشروع المكتمل ستة اختبارات في tests/todos.wf: اثنان ينظران إلى صف فقط، وأربعة تنقر — إضافة مهمة، ورفض مهمة فارغة، والتعليم ثم المسح، وإعادة التسمية مع بقاء صف واحد لكل مهمة. انسخ الملف لتحصل عليها كلها، ثم شغّلها:

bash

$ wf test

تحقّق: مع الملف كاملًا، ينتهي wf test بـ6 passed, 0 failed, 2 snapshot(s) written. الاختباران اللذان ينظران فقط يكتبان لقطة (snapshot) لما رسماه تحت tests/__snapshots__/، وتُقارَن بها التشغيلات اللاحقة.

إن أفاد اختبار ينقر بأنه لم يجد متصفحًا، فإن Chrome ليس حيث يبحث wf: اضبط WF_CHROME على مساره.

الخطوة 8: ابنِه

افحص المشروع واختبره وابنِه:

bash

$ wf check $ wf test $ wf build

يبلّغ wf check عن كل نتيجة ولا يكتب شيئًا. ويكتب wf build المجلد build/، الذي يقدّمه أي مضيف ثابت: انظر وصفات GitHub Pages وNetlify وVercel وCloudflare Pages. لتحمّل الصفحة المبنية في متصفح حقيقي قبل النشر، شغّل wf verify: يفشل عند خطأ، أو ملف مفقود، أو صفحة لا ترسم شيئًا.

تحقّق: ينتهي wf build بـBuild complete.، ويحتوي build/ على index.html وapp.js وstyles.css.

ما بنيته

  • type وenum، يُلزَم بهما كل استعمال (الأنواع).
  • مخزن تبقى قائمته بعد إعادة التحميل بفضل persist، وقيم derived تتبعها (المخازن).
  • مكوّن له حالته الخاصة، وأسماء متاحة لتقنيات المساعدة على كل عنصر تحكم (المكوّنات).
  • قائمة بمفاتيح، ومرشّح محفوظ في العنوان بـquery (التحكم في التدفق).
  • سمة بنسخة داكنة، وورقة أنماط خاصة بالمشروع (التنسيق).
  • اختبارات تنظر واختبارات تنقر (الاختبار).

أخطاء شائعة

match يُغفل حالة. يجب أن يسمّي match على enum كل حالة، لذا فإن إغفال .all خطأ:

wf · draws T15

enum Filter { all, open, done } page Home(path: "/", title: "Todos", description: "A small list of things to do.") { state filter: Filter = .all derived label = match filter { .open { "Open" } .done { "Done" } } Heading("Todos").h1 Text(label) }

أضف الفرع الناقص، .all { "All" }، أو فرع else (T15).

قائمة بلا by. دون مفتاح، يُعاد رسم الصف الذي يحمل عنصر تحكم كلما تغيّرت القائمة، فيفقد المربع الذي كان القارئ يستعمله موضعه:

wf · draws U09

type Todo { id: String, title: String } page Home(path: "/", title: "Todos", description: "A small list of things to do.") { state items: [Todo] = [Todo(id: "1", title: "Buy bread")] Heading("Todos").h1 for todo in items { Checkbox(label: todo.title) } }

اجعل مفتاح القائمة ما يميّز كل عنصر: for todo in items by todo.id (U09).

عنصر تحكم مربوط بقيمة derived. يكتب bind: إلى ما يسمّيه، والقيمة المشتقة تُحسَب ولا يُسنَد إليها أبدًا:

wf · draws F01

store Todos { state items: [String] = [] derived open = items.length } page Home(path: "/", title: "Todos", description: "A small list of things to do.") { use Todos Heading("Todos").h1 Input(bind: Todos.open, label: "Open") }

اربط state، كما تربط الصفحة draft، وغيّر المخزن عبر إجراءاته (F01).

للمضيّ أبعد: يبني Field Notes موقعًا مولَّدًا بناءً ثابتًا على ما علّمه هذا الدرس.

التالي

ما تعلّمته

  • صِف البيانات بـtype وenum

  • احفظ قائمة عبر إعادة التحميل في مخزن بـpersist، لا تغيّرها إلا إجراءاته

  • أعطِ كل صف من القائمة state خاصة به في مكوّن

  • اربط القائمة بمفتاح بـfor … by، واحفظ المرشّح في العنوان بـquery

  • اختبر صفحة بالكتابة والنقر، بـwf test