بالتفصيل
كيف تبني لوحة أوامر Ctrl+K (command palette) تعمل دون اتصال
نُشر في · قراءة في 8 دقائق· Anton Shubin
ميزة في Seed: اختصارات لوحة المفاتيح ←
متوفرة أيضًا باللغات: Deutsch وEnglish وEspañol وFrançais و日本語 وPortuguês (Brasil) وРусский و简体中文

باختصار
- لوحة الأوامر يجب أن تشغّل التطبيق لا أن تبحث فيه فقط. الصفحات وأوامر الإنشاء والإعدادات كلها أوامر، والإعداد يتغيّر لحظة الضغط على Enter.
- طابِق بدايات الكلمات، واسمح بخطأ إملائي واحد في كل كلمة، واقرأ الاستعلام بتخطيط لوحة المفاتيح الآخر. عندها يجد «notse» صفحة Notes ويجد «ntvf» إعداد Theme.
- لا تنتهِ أبدًا عند «No results». اعرض إنشاء ما كُتب، وابحث في النسخة المحفوظة على الجهاز حين يتعذّر الوصول إلى الخادم، وخفّت ما يحتاج إلى اتصال.
- اجعلها قائمة نقية واحدة: حالة التطبيق تدخل والأوامر تخرج. والمفاتيح تأتي من قائمة الاختصارات الوحيدة في التطبيق، فلا تختلف اللوحة ونافذة الاختصارات أبدًا.
لتبني لوحة أوامر Ctrl+K (command palette) تعمل دون اتصال ويعود إليها الناس فعلًا، اجعلها تفعل ثلاثة أشياء. أن تشغّل التطبيق: كل صفحة، وكل «New…» وكل إعداد هو أمر. وأن تسامح طريقة الكتابة الحقيقية: خطأ إملائي، نصف كلمة، تخطيط لوحة مفاتيح خاطئ. وألّا تتركك أبدًا في طريق مسدود: حين لا يطابق شيء تعرض عليك إنشاء ما كتبت، وبلا شبكة تبحث في النسخة المحفوظة على جهازك. في Seed يأتي كل ذلك من قائمة أوامر واحدة في ملف واحد.
هذا المقال للمطوّرين الذين يضيفون Ctrl+K إلى تطبيق الويب الخاص بهم. سأعرض أولًا ما تفعله اللوحة، ثم الملف الذي بُنيت منه، بالكود الحقيقي.

ماذا يجب أن تفعل Ctrl+K غير البحث؟
افتح اللوحة ولا تكتب شيئًا. هي مفيدة من الآن: آخر خمسة اختيارات لك تحت Recent (الأخيرة)، وأوامر الصفحة التي أنت فيها، وأحدث ملاحظاتك، وCreate (إنشاء). معظم زياراتي أنا للوحة إما «أعدني إلى ذلك الشيء» أو «افعل الشيء البديهي هنا»، ولا يجب أن يحتاج أيٌّ منهما إلى كتابة.
اكتب > وحدها فتسرد كل ما يستطيع التطبيق فعله، تحت خمسة عناوين: This page (هذه الصفحة)، وGo to
(انتقال إلى)، وCreate، وSettings (الإعدادات) وAccount (الحساب). واكتب أي شيء آخر فتجتمع الأوامر
المطابقة تحت عنوان واحد هو Commands (الأوامر)، وكل صف يذكر قسمه، وتحتها Create. الأمثلة هنا تستخدم
التطبيق بالإنجليزية، فالأسماء كما تظهر على الشاشة. بعض الاختيارات التي أثبتت جدواها:
- الإعدادات تعمل فورًا. اكتب
lightواضغط Enter: تصبح الصفحة فاتحة وتبقى اللوحة مفتوحة. اكتبdarkثم Enter، فتعود. لا حاجة إلى زيارة صفحة الإعدادات لترى إن كان يعجبك. - المفاتيح بجانب الأوامر. New note يُظهر مفتاحه، N، في صفّه. والاختصار المكوّن من مفتاحين، مثل G ثم N لصفحة Notes، مذكور في نافذة Keyboard shortcuts (اختصارات لوحة المفاتيح)، التي تقرأ قائمة الأوامر نفسها. ورقة الغش موجودة في التطبيق نفسه.
>تعني الأوامر فقط. ابدأ الاستعلام بـ>وتابع الكتابة: تبتعد الملاحظات والمجموعات عن طريقك.- Enter ينتظر الإجابة. تعطي اللوحة إجابة واحدة لكل استعلام، بما في ذلك الملاحظات. إن ضغطت Enter قبل أن يرد الخادم فإنها تنتظر، فلا تفتح أبدًا الصف الذي صادف أنه كان الأول قبل نصف ثانية.
مربع بحث لا يجد إلا الملاحظات هو نصف لوحة. النصف الآخر هو السبب الذي يجعل الناس يُبقون أيديهم على لوحة المفاتيح.
كيف تجد الأشياء رغم الأخطاء الإملائية وتخطيط لوحة المفاتيح الخاطئ؟
اكتب notse فيكون الصف الأول صفحة Notes. اكتب ntvf فتحصل على Theme، كما في الصورة أعلاه. الثانية
تبدو وكأن قطة مشت على لوحة المفاتيح. إنها «тема»، الكلمة الروسية للسمة (theme)، مكتوبة والتخطيط
الإنجليزي ما زال مفعّلًا. للوحة مفاتيحي تخطيطان، وأكون في الخاطئ منهما كثيرًا لدرجة أن ntvf صارت
حالة اختبار.
يتبع المطابِق بضع قواعد بسيطة:
- حالة الأحرف وعلامات التشكيل تُتجاهل.
- يمكن أن تأتي الكلمات بأي ترتيب، ويكفي أن تبدأ كل كلمة تكتبها كلمةً من اسم الأمر أو من أحد أسمائه
الأخرى.
no allتكفي لـ«all notes». - الكلمة المكوّنة من أربعة أحرف أو أكثر يمكن أن تحمل خطأ إملائيًا واحدًا: حرف زائد أو ناقص أو خاطئ، أو حرفان متبادلان.
- يُقرأ الاستعلام أيضًا كأن تخطيط لوحة المفاتيح الآخر مفعّل، وعبر الأبجديات، فتستطيع الأحرف اللاتينية أن تجد كلمة روسية والعكس. اليوم يعني ذلك التخطيطين الإنجليزي والروسي. وأي زوج آخر يحتاج إلى خريطة مفاتيح خاصة به.
حين تطابق عدة صفوف، يفوز التطابق الأنظف: الاسم المطابق تمامًا أولًا، ثم اسم يبدأ بالاستعلام، ثم الكلمات المطابقة، ثم اسم بديل، ثم التخطيط الآخر، والخطأ الإملائي أخيرًا. لذلك لا تدفع مسامحةُ الخطأ الإملائي إجابةً صحيحة إلى الأسفل أبدًا.
ويحمل كل أمر أيضًا الكلمات التي يجرّبها الناس، بالإنجليزية والروسية. Notes تستجيب لـ«all notes» و«заметки»، وActivity (النشاط) لـ«history» و«log» و«audit». لا أحد يتذكر ماذا سمّيتَ الصفحة. يتذكرون ماذا كانوا هم سيسمّونها.
البديل المعتاد هو مطابِق تقريبي (fuzzy)، من النوع الذي يقبل أي أحرف ما دامت تظهر بالترتيب. هو الخيار
الأفضل لمنتقي الملفات، حيث يجب أن تجد gtn الملف go-to-notes.ts. أما لقائمة أوامر فهو متساهل أكثر
من اللازم: بضعة أحرف قد تطابق صفوفًا لا علاقة لها بما قصدت، ومع ذلك لا يعرف أن ntvf كلمة. بدايات
الكلمات مع خطأ إملائي واحد أكثر صرامة، وهذا يناسب الأسماء البشرية القصيرة.
خطأ إملائي واحد لكل كلمة هو الحد. خطآن في كلمة واحدة لا يجدان شيئًا: إنه مطابِق، لا قارئ أفكار. يعيش
المطابِق في مكتبة مشتركة برخصة MIT، @spy4x/platform، يمكنك
استيرادها دون بقية Seed. وهو يجهّز أسماء كل أمر مرة واحدة، فلا تدفع ضغطة المفتاح إلا ثمن الترتيب.
ماذا تعرض حين لا يطابق شيء؟
«No results» (لا نتائج) هي اللوحة تقول لك: اذهب بعيدًا. لوحة Seed لا تقولها أبدًا، لأن أي شيء كتبته هو عنوان جيد تمامًا للشيء التالي.
اكتب Palette demo. لا شيء بهذا الاسم، فيعرض قسم Create الصف New note: “Palette demo”. يفتح Enter
نموذج الملاحظة الجديدة والعنوان معبّأ. ويتخطى Ctrl+Enter النموذج: تُنشأ الملاحظة وتُفتح.
هذه الصفوف تُبنى من الاستعلام، ولا تُطابَق معه أبدًا، فأي نص يحصل عليها:
export function quickCreateRows(context: PaletteContext, query: string): PaletteOption[] {
const { t, currentGroup } = context
const title = query.trim()
if (title === "") return []
const writable = currentGroup?.canWrite && context.notes !== false ? currentGroup : null
const row = (entity: QuickCreateEntity, key: string): PaletteOption => ({
id: `quick-create-${entity}`,
label: t.t(`Search.withText`, { label: t.t(key), text: isolate(quoted(title)) }),
group: t.t(`Search.create`),
choice: { kind: "quick-create", entity, title },
})
// …ملاحظة ووسم حين يحق للشخص الكتابة هنا، ومجموعة
}
المشاهد الذي لا يحق له الكتابة لا يحصل على صف «New note». اللوحة لا تعرض إلا ما كانت أزرار الصفحة ستعرضه.
كيف تبقى تعمل دون اتصال؟
شيئان قد يتعطلان بلا شبكة: البحث لا يجد من يسأله، وبعض الأوامر لا تجد من ينفّذها. تتعامل اللوحة مع كلٍّ منهما على حدة.
البحث يرجع إلى الجهاز. تطبيق Seed يحتفظ أصلًا بنسخة من ملاحظاتك في قاعدة البيانات المحلية للمتصفح (هذه هي طبقة offline-first، بالإنجليزية). تسأل اللوحة الخادم أولًا، وحين يتعذّر الوصول إليه تبحث في تلك النسخة بدلًا منه:
return async (query, signal) => {
if (query === "") return { notes: await recentNotes(sources), onDevice: !sources.canCall() }
if (sources.canCall()) {
try {
const answer = await sources.server(query, signal)
return { notes: answer.notes.map(fromWire), onDevice: false }
} catch (error) {
if (signal.aborted || !(isUnreachable(error) || isProxyAnswer(error))) throw error
}
}
return { notes: await notesOnDevice(sources, indexOf, query), onDevice: true }
}
هذا هو
apps/spa/src/state/search.ts.
ثلاثة تفاصيل فيه مهمة:
- يتغيّر العنوان إلى «Notes on this device» (ملاحظات على هذا الجهاز)، فتعرف أن الإجابة قد تكون أقدم من إجابة الخادم.
- لا يُطلق الرجوع إلى الجهاز إلا خادم يتعذّر الوصول إليه. الرفض، مثل حد معدّل الطلبات، يُعرض كخطأ. إخفاؤه خلف نتائج محلية سيكون كذبًا مهذبًا.
- قد يحتفظ الجهاز بملاحظات مجموعة غادرتها. البحث لا ينظر إلا في المجموعات التي تنتمي إليها الآن.
البحث المحلي فهرس صغير على الجهاز، ومحرّك غير مطابِق الأوامر، وهو يسامح الهفوات نفسها. افصل الشبكة
في النسخة التجريبية، واكتب pallette بحرفي l، فتُوجد ملاحظة «Palette demo» التي أنشأتها أعلاه
بـCtrl+Enter. وكذلك зфдуееу، الكلمة نفسها مكتوبة على التخطيط الروسي.
الأوامر التي تحتاج إلى الخادم تبقى في القائمة. دون اتصال، كان يمكن لـ«New group» أو «Delete my account» أن تختفي بهدوء من القائمة. عندها ستتساءل إن كانت الميزة موجودة أصلًا. بدلًا من ذلك تبقى في مكانها، باهتة، وبجانبها «Needs a connection» (تحتاج إلى اتصال):
const SERVER_ONLY = new Set(
[
`import-notes`,
`new-group`,
`keep`,
`download-data`,
`change-picture`,
`delete-account`,
`turn-off-two-factor`,
`end-other-sessions`,
].map((id) => `action-${id}`),
)
function needsServer(context: PaletteContext, option: PaletteOption): PaletteOption {
return {
...option,
disabledReason: context.online ? undefined : context.t.t(`Search.needsConnection`),
}
}
New note وNew tag ليسا في تلك القائمة. هما يعملان دون اتصال: الكتابة تنتظر في طابور وتخرج حين يعود الاتصال.
كيف بُنيت؟ قائمة أوامر واحدة
السجل كله هو
libs/ui/palette-commands.ts.
إنه دالة نقية: حالة التطبيق تدخل (من أنت، وأي مجموعة، ومتصل أم لا)، وقائمة خيارات تخرج. لا store، ولا
fetch، ولا router. الأمر مدخل واحد:
{
id: "notes",
key: `Frame.notes`,
href: (context) => context.notes === false ? null : NOTE_PATHS.list,
aliases: [`notes list`, `all notes`, `заметки`, `список заметок`],
},
مفتاح ترجمة الاسم، وإلى أين يذهب، والكلمات التي تجده. تعيد href القيمة null حين لا يستطيع الشخص
الذهاب إلى هناك، فيُستبعد الأمر.
انظر إلى ما ليس في المدخل: مفاتيحه. G ثم N غير مكتوبة في أي مكان من هذا الملف. للتطبيق قائمة اختصارات واحدة، واللوحة تبحث فيها عن المفاتيح بمفتاح الترجمة نفسه:
function kbdOf(shortcuts: readonly ShortcutRow[], key: string): string | undefined {
return shortcuts.find((row) => row.description === key)?.keys
}
لذلك لا يمكن أن تختلف اللوحة ونافذة Keyboard shortcuts. النسخة الأخرى، بمفاتيح مكتوبة في مكانين، تعمل حتى اليوم الذي يتغيّر فيه أحدهما. والنافذة تقرأ السجل نفسه أيضًا، وتسرد كل أمر مع الكلمات التي تجده.
يحمل كل خيار اختيارًا (choice)، كائنًا صغيرًا مثل { kind: "quick-create", entity, title }. ينفّذه
التطبيق عبر الدالة نفسها التي تستدعيها أزراره. فلا تنمو في اللوحة أبدًا نسخة ثانية من «أنشئ ملاحظة»
تبتعد عن النسخة الحقيقية.
ولأنها نقية فاختبارها رخيص: لا متصفح، فقط حالة تدخل وصفوف تخرج. الاختبارات تُقرأ كقائمة الميزات، مثل
«put Go to Notes first for notse and заметки» و«keep each command the server must run listed offline,
dimmed with why, and dim none online». تجدها في
palette-commands.test.ts.
وفي لوحة الإدارة لوحة الأوامر نفسها. أوامرها قائمة ثانية من 268 سطرًا، وكل ما عدا ذلك مشترك.
كيف يضيف المنتج سجلاته الخاصة؟
Seed قالب انطلاق، لذا على اللوحة أن تجد أشياء لم أسمع بها قط: فواتيرك، وجهات اتصالك، ومشاريعك. يسلّمها المنتج على شكل سجلات:
export interface PaletteRecord {
/** Unique within its source. */
id: string
/** What the palette lists and matches, in the person's language. */
label: string
/** The row's second line, such as an amount or a date. It is shown, not matched. */
detail?: string
/** Other words that find it, such as a number or an old name. */
aliases?: readonly string[]
/** The page a pick opens, as a page command does. */
href: string
}
المصدر عنوان ودالة تعيد السجلات التي يحتفظ بها الجهاز الآن
(search-palette.tsx). تُطابَق
على الجهاز بالمطابِق نفسه الذي يطابق الأوامر، فتحصل الفاتورة على مسامحة الأخطاء الإملائية والتخطيط
مجانًا، متصلًا كنت أم لا. فخ واحد: الدالة تُستدعى مع كل ضغطة مفتاح، لذا يجب أن تجيب من الذاكرة، وأن تعيد
الكائنات نفسها ما دام لم يتغيّر شيء. يجهّز المطابِق كل كائن مرة واحدة ويعيد استخدام ذلك العمل.
حاول أن تكسرها
افتح النسخة التجريبية واضغط «Try it now» (جرّبه الآن). تحصل على حساب ضيف فيه ملاحظات نموذجية. ثم:
- اضغط Ctrl+K (⌘K على Mac) واكتب
notse، ثمntvf. - اكتب
lightواضغط Enter، ثمdarkوEnter. - اكتب عنوانًا لم يستخدمه أحد واضغط Ctrl+Enter.
- افصل الشبكة في أدوات المطوّر في متصفحك وابحث عن تلك الملاحظة بخطأ إملائي فيها.
كل ذلك برخصة MIT في المستودع، والمفاتيح مذكورة في صفحة الاختصارات. إن وجدت خطأً إملائيًا كان يجب أن تسامحه ولم تفعل، فهذا اختبار لم أكتبه بعد.


