BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/client-sync-internals.mdx
View on GitHub---
title: "آليات المزامنة الداخلية"
description: "آلية إصدار التغيير خلف useDbSync: useChangeVersion/useChangeVersions لمزامنة useQuery خام، والمساران اللذان يمكن أن تسلكهما إعادة الجلب."
---
# آليات المزامنة الداخلية
تغطي [المزامنة المباشرة](/docs/key-concepts#polling-sync) النموذج المفهومي: تصبح كتابة الوكيل حدث تغيير، ويلتقطها `useDbSync()`، وتُعاد جلب الاستعلامات المتأثرة. تغطي هذه الصفحة الآلية التي تقف تحتها والتي لا تلمسها معظم التطبيقات مباشرة أبدًا: عدّادات إصدار التغيير التي تُصعِّدها `useDbSync()`، وكيفية دمجها في استدعاء `useQuery()` خام لا يمر عبر `useActionQuery()`.
تُعيد `useActionQuery()` الجلب تلقائيًا بالفعل عندما تكتمل action تُغيِّر البيانات (راجع [البيانات والمزامنة](/docs/client-data#fetching-mutating)). استخدم `useChangeVersion()`/`useChangeVersions()` فقط عندما تُزامن استدعاء `useQuery()` خام خارج ذلك المسار، مثل أداة مساعدة عميل ذات مستوى منخفض تقرأ حالة تكامل.
## كيف تعمل إصدارات التغيير {#how-it-works}
عندما تحدث طفرة قاعدة بيانات من جانب الخادم، يسجل الخادم حدث تغيير مُعلَّمًا بمفتاح `source`. تستقبل `useDbSync()` ذلك الحدث وتُصعِّد عدادًا محليًا لذلك المصدر. يجعل دمج العداد في مفتاح استعلام React الاستعلام يُعيد الجلب تلقائيًا كل مرة يُعلن فيها الواجهة الخلفية عن نشاط جديد لذلك المصدر.
## useChangeVersion / useChangeVersions {#use-change-version}
<Signature
id="doc-block-client-sync-internals-1"
name="useChangeVersion"
params={[
{
name: "source",
type: "string",
description: 'مصدر حدث التغيير المطلوب مراقبته، مثل `"dashboards"`.',
},
]}
returns={{
type: "number",
description: "عدّاد يتصاعد كل مرة يتم تغيير المصدر المحدد.",
}}
/>
<Signature
id="doc-block-client-sync-internals-2"
name="useChangeVersions"
params={[
{
name: "sources",
type: "readonly string[]",
description: "مصادر حدث تغيير متعددة لمراقبتها في آنٍ واحد.",
},
]}
returns={{
type: "number",
description: "مجموع عدادات الإصدار لكل مصدر مُعطى.",
}}
/>
في المثال أدناه، يقرأ استدعاء `useQuery()` خام لوحة معلومات مباشرة، مع دمج عداد إصدار مصدر `"dashboards"` في مفتاح استعلامه حتى يُعيد الجلب كل مرة يتغير ذلك المصدر:
```tsx
import { useQuery } from "@tanstack/react-query";
import { useChangeVersion } from "@agent-native/core/client/hooks";
function DashboardView({ id }) {
const version = useChangeVersion("dashboards");
const { data } = useQuery({
queryKey: ["dashboard", id, version],
queryFn: () => fetchDashboard(id),
placeholderData: (prev) => prev,
});
return <div>{data?.title}</div>;
}
```
يحافظ `placeholderData: (prev) => prev` على البيانات السابقة على الشاشة أثناء إعادة الجلب، لذا لا يرمش العرض إلى حالة تحميل.
## مساران لإعادة الجلب {#latency-models}
تصل الطفرة إلى واجهة المستخدم بأحد طريقين، ولهما زمن انتقال مختلف.
الطفرة المحلية، وهي طفرة أجراها استدعاء `useActionMutation()` الخاص بك للتو، تُصدر حدث `source: "action"` بمجرد نجاحها. تُعيد كل استعلام يعتمد على تلك action الجلب فورًا. لا يوجد تأخير في الرحلة ذهابًا وعودة، لأن علامة التبويب التي أجرت الكتابة تعرف بها بالفعل.
الطفرة البعيدة، من الوكيل، أو خطاف ويب، أو علامة تبويب أخرى، أو مستخدم آخر، يجب أن تصل إلى علامة التبويب هذه أولًا. تلتقطها `useDbSync()` عبر SSE على الفور تقريبًا على مضيف طويل الأمد، أو عبر الرجوع إلى الاستقصاء غير ذلك. فقط بعد وصول ذلك الحدث يتصاعد عداد الإصدار ذو الصلة ويُعاد جلب الاستعلام في الخلفية. في عمليات النشر بدون خادم في بيئة الإنتاج، لا يُعد تدفق SSE الخاص بالتطبيق نفسه مسارًا أبطأ يُرجَع إليه — بل هو مُعطَّل بحكم التصميم (راجع [Live Sync](/docs/key-concepts#polling-sync))، لذا تنتقل كل طفرة بعيدة هناك عبر الاستقصاء، ما لم يكن التطبيق قد اشترك في [بوابة المزامنة الفورية المستضافة](/docs/real-time-collaboration#hosted-gateway).
<Diagram id="doc-block-client-sync-internals-3" title="مساران لإعادة الجلب" summary="تُبطل الطفرة المحلية ذاكرتها التخزينية فورًا. تصل الكتابة البعيدة إلى علامة التبويب هذه عبر SSE، أو دورة الاستقصاء كنسخة احتياطية.">
```html
<div class="diagram-latency">
<div class="diagram-col">
<div class="diagram-card" data-rough>
<span class="diagram-pill ok">علامة التبويب هذه</span
><strong>useActionMutation</strong
><small class="diagram-muted"
>تُصدر source: "action" عند النجاح → إعادة جلب محلية فورية</small
>
</div>
<div class="diagram-card" data-rough>
<span class="diagram-pill accent"
>الوكيل · خطاف ويب · علامة تبويب أخرى</span
><strong>كتابة بعيدة</strong
><small class="diagram-muted"
>دفع SSE، أو دورة الاستقصاء كل ~2 ثانية كنسخة احتياطية → يتصاعد
الإصدار → إعادة جلب في الخلفية</small
>
</div>
</div>
</div>
```
```css
.diagram-latency .diagram-col {
display: flex;
flex-direction: column;
gap: 12px;
}
.diagram-latency .diagram-card {
display: flex;
flex-direction: column;
gap: 4px;
padding: 14px 16px;
}
```
</Diagram>
## ما هي الخطوة التالية
- [**المزامنة المباشرة**](/docs/key-concepts#polling-sync) — النموذج المفهومي الذي تقف هذه الصفحة تحته
- [**البيانات والمزامنة**](/docs/client-data) — `useActionQuery`/`useDbSync`، التي ينبغي أن تستخدمها معظم الصفحات بدلًا من هذه البدائيات
- [**متقدم**](/docs/client-advanced) — البدائيات الأخرى ذات المستوى الأدنى ومخارج الطوارئ الخاصة بالعميل
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |