مكون Convex Create

# مكون Convex Create

أنشئ مكونات Convex قابلة لإعادة الاستخدام بحدود واضحة وواجهة API صغيرة موجهة للتطبيق.

## متى تستخدمه

- إنشاء مكون Convex جديد في تطبيق موجود - استخلاص منطق خلفي قابل لإعادة الاستخدام في مكون - بناء تكامل طرف ثالث يجب أن يمتلك جداوله وسير عمله الخاص - تجميع وظائف Convex لإعادة الاستخدام عبر تطبيقات متعددة

## متى لا تستخدمه

- منطق عمل لمرة واحدة ينتمي إلى التطبيق الرئيسي - أدوات بسيطة لا تحتاج إلى جداول أو وظائف Convex - تنسيق على مستوى التطبيق يجب أن يبقى في `convex/` - الحالات التي تكون فيها مكتبة TypeScript عادية كافية

## سير العمل

1. اسأل المستخدم عما يبنيه وما هو الهدف النهائي. إذا كان المستودع يوضح الإجابة بالفعل، فاذكر ذلك وقم بالتأكيد قبل المتابعة. 2. اختر الشكل باستخدام شجرة القرار أدناه واقرأ الملف المرجعي المطابق. 3. قرر ما إذا كان المكون مبررا. فضل كود التطبيق العادي أو مكتبة عادية إذا كانت الميزة لا تحتاج إلى جداول معزولة، أو وظائف خلفية، أو حالة مستمرة قابلة لإعادة الاستخدام. 4. ضع خطة قصيرة ل: - الجداول التي يمتلكها المكون - الوظائف العامة التي يكشفها - البيانات التي يجب تمريرها من التطبيق (المصادقة، متغيرات البيئة، معرفات الأصل) - ما يبقى في التطبيق كأغلفة أو نقاط تحميل HTTP 5. أنشئ هيكل المكون باستخدام `convex.config.ts` و `schema.ts` وملفات الوظائف. 6. نفذ الوظائف باستخدام استيرادات `_generated/server` الخاصة بالمكون، وليس الملفات المولدة للتطبيق. 7. اربط المكون بالتطبيق باستخدام `app.use(...)`. إذا لم يكن للتطبيق `convex/convex.config.ts` بالفعل، فأنشئه. 8. استدع المكون من التطبيق عبر `components.<name>` باستخدام `ctx.runQuery` أو `ctx.runMutation` أو `ctx.runAction`. 9. إذا كانت عملاء React أو مستدعي HTTP أو واجهات API العامة تحتاج إلى الوصول، فأنشئ وظائف تغليف في التطبيق بدلا من كشف وظائف المكون مباشرة. 10. قم بتشغيل `npx convex dev` وأصلح مشكلات توليد الكود أو النوع أو الحدود قبل الانتهاء.

## اختر الشكل

اسأل المستخدم، ثم اختر مسارا واحدا:

| الهدف | الشكل | المرجع | | :------------------------------------------------ | :--------------- | :---------------------------------- | | مكون لهذا التطبيق فقط | محلي | `references/local-components.md` | | النشر أو المشاركة عبر التطبيقات | مجمع | `references/packaged-components.md` | | يحتاج المستخدم صراحة إلى كود مكتبة محلي + مشترك | هجين | `references/hybrid-components.md` | | غير متأكد | الافتراضي محلي | `references/local-components.md` |

اقرأ ملفا مرجعيا واحدا بالضبط قبل المتابعة.

## النهج الافتراضي

ما لم يرغب المستخدم صراحة في حزمة npm، يكون الافتراضي هو مكون محلي:

- ضعه تحت `convex/components/<componentName>/` - عرفه باستخدام `defineComponent(...)` في ملف `convex.config.ts` الخاص به - ثبته من ملف `convex/convex.config.ts` الخاص بالتطبيق باستخدام `app.use(...)` - دع `npx convex dev` يولد ملفات `_generated/` الخاصة بالمكون

## هيكل المكون

مكون محلي بسيط مع جدول ووظيفتين، بالإضافة إلى ربط التطبيق.

```ts // convex/components/notifications/convex.config.ts import { defineComponent } from "convex/server";

export default defineComponent("notifications"); ```

```ts // convex/components/notifications/schema.ts import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values";

export default defineSchema({ notifications: defineTable({ userId: v.string(), message: v.string(), read: v.boolean(), }).index("by_user_read", ["userId", "read"]), }); ```

```ts // convex/components/notifications/lib.ts import { v } from "convex/values"; import { mutation, query } from "./_generated/server.js";

export const send = mutation({ args: { userId: v.string(), message: v.string() }, returns: v.id("notifications"), handler: async (ctx, args) => { return await ctx.db.insert("notifications", { userId: args.userId, message: args.message, read: false, }); }, });

export const listUnread = query({ args: { userId: v.string() }, returns: v.array( v.object({ _id: v.id("notifications"), _creationTime: v.number(), userId: v.string(), message: v.string(), read: v.boolean(), }), ), handler: async (ctx, args) => { return await ctx.db .query("notifications") .withIndex("by_user_read", (q) => q.eq("userId", args.userId).eq("read", false), ) .collect(); }, }); ```

```ts // convex/convex.config.ts import { defineApp } from "convex/server"; import notifications from "./components/notifications/convex.config.js";

const app = defineApp(); app.use(notifications);

export default app; ```

```ts // convex/notifications.ts (app-side wrapper) import { v } from "convex/values"; import { mut ```