kreftjs 0.0.17-beta → 0.0.20-beta
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -0
- package/bin/build.js +13 -2
- package/bin/electron.js +61 -2
- package/bin/kreftjs.js +5 -3
- package/book/ar/01-getting-started.md +169 -0
- package/book/ar/02-language.md +330 -0
- package/book/ar/03-components-and-state.md +258 -0
- package/book/ar/04-router-data-forms.md +333 -0
- package/book/ar/05-arabic-rtl.md +175 -0
- package/book/ar/06-backend.md +247 -0
- package/book/ar/07-auth-and-security.md +157 -0
- package/book/ar/08-background-work.md +250 -0
- package/book/ar/09-testing-and-deploy.md +234 -0
- package/book/ar/10-electron-desktop.md +258 -0
- package/book/ar/11-advanced-blog.md +370 -0
- package/book/ar/12-advanced-shop.md +426 -0
- package/book/ar/13-advanced-ui.md +440 -0
- package/book/ar/14-advanced-ops.md +167 -0
- package/book/ar/15-appendix.md +81 -0
- package/book/ar/README.md +62 -0
- package/book/kreft-book-ar.docx +0 -0
- package/docs/README.md +43 -8
- package/kreftjs.d.ts +1 -1
- package/kreftjs.js +436 -74
- package/package.json +4 -3
- package/templates/app/frontend/errors/ErrorMonitor.kreft +2 -2
- package/templates/app/frontend/kreftjs.d.ts +1 -1
- package/templates/app/frontend/kreftjs.js +436 -74
- package/templates/app/frontend/pages/Dashboard.kreft +1 -1
- package/templates/errors/ErrorMonitor.kreft +1 -1
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# الفصل التاسع: الاختبار والبناء والنشر
|
|
2
|
+
|
|
3
|
+
## اختبار الواجهة الخلفية
|
|
4
|
+
|
|
5
|
+
تُختبر شيفرة الخادم بمشغّل الاختبارات المدمج في Node وقاعدة SQLite في الذاكرة، فالاختبارات سريعة ولا تمس بياناتك الحقيقية.
|
|
6
|
+
|
|
7
|
+
```json
|
|
8
|
+
{
|
|
9
|
+
"scripts": { "test": "node --test \"tests/**/*.test.js\"" }
|
|
10
|
+
}
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
// tests/models/post.test.js
|
|
15
|
+
const test = require('node:test')
|
|
16
|
+
const assert = require('node:assert/strict')
|
|
17
|
+
const { createSchema, setConnection } = require('kreftjs/server')
|
|
18
|
+
const { connect } = require('kreft/bin/db.js')
|
|
19
|
+
const Post = require('../../backend/app/Models/Post')
|
|
20
|
+
|
|
21
|
+
test.before(async () => {
|
|
22
|
+
const db = await connect('sqlite::memory:') // قاعدة فارغة جديدة لهذا الملف
|
|
23
|
+
setConnection(db)
|
|
24
|
+
await createSchema(db).create('posts', (table) => {
|
|
25
|
+
table.id()
|
|
26
|
+
table.string('title')
|
|
27
|
+
table.timestamps()
|
|
28
|
+
})
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
test('a post can be created and found', async () => {
|
|
32
|
+
const post = await Post.create({ title: 'Hello' })
|
|
33
|
+
assert.equal((await Post.find(post.id)).title, 'Hello')
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
لاختبار جداول مشروع كامل شغّل ترحيلاته الحقيقية بدل بناء المخطط يدويًا: `migrator.migrate(db, 'backend/database/migrations')`.
|
|
38
|
+
|
|
39
|
+
اختبارات المكوّنات للمتصفح تعيش في `frontend/tests/` وتُفتح بـ `kreft dev`.
|
|
40
|
+
|
|
41
|
+
## الأدوات المرافقة للتطوير
|
|
42
|
+
|
|
43
|
+
كل ما هنا يأتي مع Kreft:
|
|
44
|
+
|
|
45
|
+
**إعادة التحميل الفورية.** أثناء `kreft dev` احفظ ملف `.kreft` فيُبدَّل ذلك المكوّن وحده وتبقى حالته. وملف `.css` يُعاد تحميله بلا تحديث للصفحة، والخطأ يعرض طبقة فيها الملف والسطر.
|
|
46
|
+
|
|
47
|
+
**أدوات Kreft (DevTools).** زر **S** في الزاوية (أو <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>) يفتح لوحة:
|
|
48
|
+
|
|
49
|
+
| التبويب | يعرض |
|
|
50
|
+
|---|---|
|
|
51
|
+
| Components | الشجرة الحية. اختر مكوّنًا لترى الخصائص والحالة والقيم المشتقة، وغيّر الحالة هناك. |
|
|
52
|
+
| Stores | قيم كل مخزن (قابلة للتغيير) و`$reset()`. |
|
|
53
|
+
| Route | المسار الحالي وكل المسارات، مع زر للذهاب إليها. |
|
|
54
|
+
| Timeline | أفعال المخازن ورسائل الـ bus حال وقوعها. |
|
|
55
|
+
|
|
56
|
+
الزر واللوحة موجودان تحت `kreft dev` فقط؛ التطبيقات المبنية لا تحتويهما أبدًا.
|
|
57
|
+
|
|
58
|
+
### مراقب الأخطاء
|
|
59
|
+
|
|
60
|
+
في التطوير، خطأ غير ملتقط على الخادم يعرض صفحة تفاعلية بدل رسالة مجردة: مستكشف مكدّس يخفي إطارات المكتبات ويبرز إطاراتك، ومعاينة للشيفرة حول السطر الفاشل، ومحرك اقتراحات للأخطاء الشائعة (خطأ إملائي في دالة نموذج، أو قراءة خاصية من `undefined`، أو جدول مفقود يحتاج `kreft migrate`)، والطلب كاملًا (مع إخفاء كلمات المرور والرموز والكوكيز). وتظهر الصفحة فقط حين `APP_ENV` ليس `production` و`APP_DEBUG` صحيح. **في الإنتاج الخطأ نفسه يجيب `Server error.` ببساطة**، بلا مكدّس أو أسماء ملفات.
|
|
61
|
+
|
|
62
|
+
## البناء (Build)
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npm run build # أو: kreft build
|
|
66
|
+
npm run preview # افحص النتيجة: kreft dev dist
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
| الملف | ما هو |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `index.html` | صفحتك، تحمّل الآن الملفات أدناه. |
|
|
72
|
+
| `kreftjs.js` | الإطار. |
|
|
73
|
+
| `app.js` | كل ملفات `.kreft`، مصرّفة. |
|
|
74
|
+
| `app.css` | كل كتل `<style>`؛ المحصورة محصورة فعلًا. |
|
|
75
|
+
| `main.js` | شيفرة `<script>` المضمنة في `index.html`. |
|
|
76
|
+
| `deps/` و`vendor/` | حزم npm وملفات CSS التي تستوردها ملفاتك، مصغّرة. |
|
|
77
|
+
|
|
78
|
+
ماذا تكسب:
|
|
79
|
+
|
|
80
|
+
- **أول تحميل أسرع:** يحمّل المتصفح `app.js` واحدًا ولا يصرّف شيئًا.
|
|
81
|
+
- **سياسة CSP صارمة تعمل:** كل تعبير يصير دالة حقيقية، فلا `eval` ولا `new Function` في التطبيق المبني.
|
|
82
|
+
- **أخطاء قبل النشر:** أي خطأ في أي ملف `.kreft` يوقف البناء ويسمي الملف والسطر.
|
|
83
|
+
|
|
84
|
+
خيارات: `kreft build ./site --out public` يبني مجلدًا آخر، و`--base /` يغيّر `<base href>`. و`--no-htaccess` يتخطى ملف `.htaccess`.
|
|
85
|
+
|
|
86
|
+
### القاعدة (base) الصحيحة: خطأ شائع جدًا
|
|
87
|
+
|
|
88
|
+
يحتفظ البناء بوسم `<base href="…">` المكتوب في `index.html` المصدر، ويضبط قواعد `.htaccess` عليه. **إن كان `index.html` المصدر يحمل قاعدة مجلد فرعي** (مثل `<base href="/demo/">` في مشروع `demo`) وأنت ترفع الموقع إلى الجذر، فالنتيجة **صفحة بيضاء**: المتصفح يطلب `/demo/app.js` فلا يجد شيئًا.
|
|
89
|
+
|
|
90
|
+
الحل: اذكر القاعدة صراحة عند البناء للنشر في الجذر:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
kreft build --out dist/site --base /
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
وافحص `index.html` المبني: يجب أن ترى `<base href="/">`. وإن كان موقعك في مجلد فرعي `/blog/` فابنِ بـ `--base /blog/`.
|
|
97
|
+
|
|
98
|
+
### الرفع إلى استضافة
|
|
99
|
+
|
|
100
|
+
**استضافة ثابتة: Hostinger وcPanel وأي استضافة Apache.** ارفع ما **داخل** `dist/` (لا المجلد نفسه) إلى المجلد الذي يخدم الموقع، وهو عادة `public_html`. في hPanel من Hostinger: **Files ← File Manager ← public_html ← Upload**، أو استعمل FTP. لا تستعمل مستورِدات "framework" أو "Node.js app" لهذا: فهي تبحث عن `package.json` وتقول *Unsupported framework or invalid project structure* لأن `dist/` فيه ملفات منتهية فقط.
|
|
101
|
+
|
|
102
|
+
ويكتب `kreft build` ملف `dist/.htaccess`:
|
|
103
|
+
|
|
104
|
+
```apache
|
|
105
|
+
RewriteEngine On
|
|
106
|
+
RewriteBase /
|
|
107
|
+
RewriteRule ^index\.html$ - [L]
|
|
108
|
+
RewriteCond %{REQUEST_FILENAME} !-f
|
|
109
|
+
RewriteCond %{REQUEST_FILENAME}/index.html !-f
|
|
110
|
+
RewriteCond %{REQUEST_URI} !^/api/
|
|
111
|
+
RewriteCond %{REQUEST_URI} !\.[A-Za-z0-9]+$
|
|
112
|
+
RewriteRule . /index.html [L]
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Apache لا يعرف إلا الملفات الموجودة على القرص، فبدون هذه القواعد يعطي `/docs` أو أي عنوان نظيف خطأ 404 عند فتحه أو إعادة تحميله. ومعها، كل عنوان صفحة (بلا امتداد وليس تحت `/api/`) ليس ملفًا حقيقيًا يفتح `index.html` ويتولى الموجِّه الباقي. ارفع الملف أيضًا (يبدأ بنقطة فبعض مديري الملفات يخفونه؛ فعّل "show hidden files").
|
|
116
|
+
|
|
117
|
+
ويضع `kreft build` أيضًا بصمة قصيرة في عنوان كل سكربت وملف أنماط (`app.js?v=28a965f6`)، ويطلب `.htaccess` من الاستضافة ألا تحتفظ بـ `index.html`. الاستضافات تخزّن `.js` و`.css` أيامًا، فبدون البصمة يظل الزوار يشغّلون الإطار والصفحات القديمة بعد رفع بناء جديد.
|
|
118
|
+
|
|
119
|
+
> **ملاحظة:** هذا يستضيف الواجهة الأمامية فقط. تسجيل الدخول وقاعدة البيانات وكل ما تحت `/api` يحتاج خادم Node.js الذي لا يشغّله Apache.
|
|
120
|
+
|
|
121
|
+
**خطة Node.js أو VPS.** ارفع المشروع كله (بلا `node_modules`)، لا `dist/`. أضف Kreft إلى اعتماداتك بـ `npm i kreftjs`، وابنِ بـ `npm run build`، وشغّل الخادم بـ `npm run serve` (يقرأ `PORT` الذي تضبطه استضافتك). سكربت `start` المولَّد يشغّل خادم التطوير فلا تستعمله في الإنتاج.
|
|
122
|
+
|
|
123
|
+
على VPS أبقِه يعمل بـ PM2 وضع nginx أمامه للنطاق وHTTPS:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npm install && npm run build
|
|
127
|
+
npm i -g pm2
|
|
128
|
+
pm2 start "npm run serve" --name my-app && pm2 save
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```nginx
|
|
132
|
+
server {
|
|
133
|
+
server_name example.com;
|
|
134
|
+
location / {
|
|
135
|
+
proxy_pass http://127.0.0.1:8000;
|
|
136
|
+
proxy_set_header Host $host;
|
|
137
|
+
proxy_set_header X-Forwarded-Proto $scheme;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
ثم `sudo certbot --nginx -d example.com` يضيف HTTPS. اضبط `APP_ENV=production` و`APP_KEY` حقيقيًا في `.env` أولًا، وراجع [قائمة الفحص](07-auth-and-security.md).
|
|
143
|
+
|
|
144
|
+
## تحسين محركات البحث (SEO)
|
|
145
|
+
|
|
146
|
+
### صفحات HTML جاهزة: `--prerender`
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
npm i -D jsdom # مرة لكل مشروع
|
|
150
|
+
kreft build --prerender # كل مسار بلا :params
|
|
151
|
+
kreft build --prerender /users/1,/users/2 # وهذه العناوين أيضًا
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
كل صفحة تُفتح في متصفح محاكى، وتُحمَّل بياناتها، وتُحفظ النتيجة في `dist/<page>/index.html`، فيحصل الزوار ومحركات البحث على HTML منتهٍ.
|
|
155
|
+
|
|
156
|
+
الوسوم التي تضعها الصفحة بـ `.seo({...})` أو `meta` (الوصف، وcanonical، وOpen Graph، وTwitter، وhreflang، وJSON-LD، و`lang` و`dir`) تُحفظ في HTML الصفحة أيضًا، فتراها معاينات الروابط والزواحف التي لا تشغّل JavaScript.
|
|
157
|
+
|
|
158
|
+
### SEO لصفحات تأتي من قاعدة بياناتك: `backend/routes/seo.js`
|
|
159
|
+
|
|
160
|
+
```js
|
|
161
|
+
// backend/routes/seo.js
|
|
162
|
+
const Post = require('../app/Models/Post')
|
|
163
|
+
|
|
164
|
+
module.exports = {
|
|
165
|
+
'/': { title: 'متجري', description: 'كل ما يحتاجه البيت' },
|
|
166
|
+
'/blog/:slug': async ({ slug }) => {
|
|
167
|
+
const post = await Post.query().published().where('slug', slug).first()
|
|
168
|
+
if (!post) return null // 404 حقيقي مع noindex
|
|
169
|
+
return {
|
|
170
|
+
title: post.title,
|
|
171
|
+
description: String(post.body || '').slice(0, 150),
|
|
172
|
+
schema: { '@type': 'Article', headline: post.title },
|
|
173
|
+
}
|
|
174
|
+
},
|
|
175
|
+
// عناوين صفحات بياناتك، لـ `kreft sitemap`
|
|
176
|
+
urls: async () => (await Post.query().published().get()).map((p) => ({ path: '/blog/' + p.slug, lastmod: p.updated_at })),
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
`kreft dev` و`kreft serve` يجيبان طلب الصفحة بـ `index.html` مع وسوم أول عنوان مطابق. واضبط `APP_URL` لتحصل كل صفحة على `canonical`.
|
|
181
|
+
|
|
182
|
+
### صفحات كاملة للزواحف
|
|
183
|
+
|
|
184
|
+
الزاحف أو معاينة الرابط (Googlebot وBingbot وWhatsApp وFacebook وX وTelegram …) الذي لا يشغّل JavaScript سيرى `<div id="app">` فارغًا. لهؤلاء يفتح `kreft dev` و`kreft serve` الصفحة في المتصفح المحاكى نفسه، وينتظر تحميل بياناتها، ويجيب بالصفحة مرسومة.
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
npm i -D jsdom # مرة لكل مشروع
|
|
188
|
+
KREFT_SSR=bots # الافتراضي: الزواحف ومعاينات الروابط فقط
|
|
189
|
+
KREFT_SSR=all # كل زائر
|
|
190
|
+
KREFT_SSR=off # أبدًا
|
|
191
|
+
KREFT_SSR_TTL=300 # ثوانٍ تحتفظ فيها بالصفحة المرسومة
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### خريطة الموقع وrobots.txt
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
kreft sitemap --url https://example.com # public/sitemap.xml و public/robots.txt
|
|
198
|
+
kreft sitemap --url https://example.com --urls urls.js # مع العناوين في ذلك الملف
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## نشر الواجهة الخلفية
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
NODE_ENV=production kreft serve dist
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
وقبلها أنجز [قائمة الفحص قبل الإنتاج](07-auth-and-security.md).
|
|
208
|
+
|
|
209
|
+
## TypeScript
|
|
210
|
+
|
|
211
|
+
يعمل TypeScript في المتصفح (ملفات `.kreft` ووحدات `.ts`) وعلى الخادم (`routes/api.ts` و`app/**/*.ts` والترحيلات والبذور).
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
kreft new my-app --ts
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
داخل ملف `.kreft` يمكنك كتابة `interface` و`type` و`enum` و`import type`، و`prop` و`state` و`derive` و`saved` بأنواعها. والتنفيذ لا يحتاج إعدادًا: يستعمل Kreft الأداة `esbuild` إن وُجدت، وإلا إزالة الأنواع المدمجة في Node (22.6+)، وإلا مزيله الخاص بلا اعتماديات.
|
|
218
|
+
|
|
219
|
+
## تصحيح المشاكل الشائعة
|
|
220
|
+
|
|
221
|
+
| العَرَض | السبب المرجح | الحل |
|
|
222
|
+
|---|---|---|
|
|
223
|
+
| صفحة بيضاء بعد الرفع | `<base href>` خاطئ في `index.html` | ابنِ بـ `--base /` وأعد الرفع |
|
|
224
|
+
| `/docs` يعطي 404 عند التحديث | ملف `.htaccess` لم يُرفع | ارفعه (أظهر الملفات المخفية) |
|
|
225
|
+
| بقاء النسخة القديمة بعد الرفع | تخزين المتصفح أو الاستضافة | تأكد من رفع كل الملفات الجديدة بالبصمات |
|
|
226
|
+
| `no such table: …` | ترحيل جديد لم يُنفَّذ | `kreft migrate` |
|
|
227
|
+
| لا شيء يتغير في الصفحة | سطر `const` في السكربت | استعمل `state` أو `derive` |
|
|
228
|
+
| الإرسال لا يعمل مع `type="email"` | تحقق المتصفح الأصلي يسبق Kreft | أضف `novalidate` إلى `<form>` |
|
|
229
|
+
|
|
230
|
+
## تمارين
|
|
231
|
+
|
|
232
|
+
1. ابنِ تطبيقك بـ `--base /` وافتح `dist/index.html` وتحقق من وسم `<base>`.
|
|
233
|
+
2. أضف `backend/routes/seo.js` لمدونتك وافتح صفحة مقال بمتصفح يحاكي زاحفًا: `curl -A Googlebot …`.
|
|
234
|
+
3. اكتب اختبار نموذج لـ `Product` يتحقق من أن `scopeInStock` يستثني المنتجات التي مخزونها صفر.
|
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
# الفصل العاشر: تطبيقات سطح المكتب مع Electron
|
|
2
|
+
|
|
3
|
+
يمكن لـ Kreft أن يحزم تطبيقك كبرنامج سطح مكتب لـ Windows وmacOS وLinux. الصفحات هي ملفات `.kreft` نفسها؛ وElectron يقدّم النافذة فقط.
|
|
4
|
+
|
|
5
|
+
## البداية السريعة
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
kreft new my-app --electron # تطبيق جديد بدعم سطح المكتب
|
|
9
|
+
# أو في تطبيق موجود:
|
|
10
|
+
kreft electron:init # اسم بديل: kreft make:electron
|
|
11
|
+
npm install # يثبّت electron و electron-builder
|
|
12
|
+
kreft electron # يفتح التطبيق في نافذته: بلا متصفح وبلا عنوان
|
|
13
|
+
kreft electron:build # مثبّت في dist-electron/
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
للمساعدة في الطرفية في أي وقت:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
kreft electron:help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## الأوامر
|
|
23
|
+
|
|
24
|
+
| الأمر | ماذا يفعل |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `kreft electron:init` | يكتب `electron/main.js` و`electron/preload.js` وأيقونة التطبيق `build/icon.png`، ويضيف السكربتات واعتماديات `electron` و`electron-builder` وكتلة `build` إلى `package.json`. الملفات الموجودة لا تُستبدل أبدًا. ويزيل أيضًا روابط Google Fonts من `index.html` ليبدأ التطبيق بلا شبكة. |
|
|
27
|
+
| `kreft electron` | يفتح التطبيق في نافذة سطح مكتب فقط: لا متصفح ولا عنوان يُطبع. خادم التطوير يعمل مخفيًا على منفذ خاص بحاسوبك لا تستعمله إلا النافذة (إعادة التحميل الفورية تعمل). إغلاق النافذة يوقف الخادم. |
|
|
28
|
+
| `kreft electron:build` | يشغّل `kreft build --base ./` ثم `electron-builder`. |
|
|
29
|
+
| `npm run electron:build:mac` | `.dmg` و`.zip`. |
|
|
30
|
+
| `npm run electron:build:win` | مثبّت NSIS و`.exe` محمول. |
|
|
31
|
+
| `npm run electron:build:linux` | AppImage و`.deb` و`.rpm`. |
|
|
32
|
+
| `npm run electron:build:all` | الثلاثة. |
|
|
33
|
+
| `kreft electron:help` | دليل مختصر في الطرفية. |
|
|
34
|
+
|
|
35
|
+
## مرجع سريع
|
|
36
|
+
|
|
37
|
+
| أريد أن… | افعل هذا |
|
|
38
|
+
|---|---|
|
|
39
|
+
| أضيف دعم سطح المكتب | `kreft new my-app --electron`، أو `kreft electron:init` ثم `npm install` |
|
|
40
|
+
| أفتح التطبيق في نافذته | `kreft electron` |
|
|
41
|
+
| أفتح DevTools | `kreft electron --devtools=bottom` أو `ELECTRON_DEVTOOLS=right` أو F12 |
|
|
42
|
+
| أظهر القائمة أو أخفيها | `ELECTRON_MENU=show` أو `auto` أو `hide`؛ و`kreftDesktop.setMenu('hide')` |
|
|
43
|
+
| أغيّر الأيقونة | استبدل `build/icon.png` (PNG مربعة 512×512 أو أكبر) |
|
|
44
|
+
| أغيّر اسم التطبيق | `build.productName` و`build.appId` في `package.json` |
|
|
45
|
+
| أصنع مثبّتًا | `npm run electron:build:mac` أو `:win` أو `:linux` أو `:all` |
|
|
46
|
+
|
|
47
|
+
## بنية المشروع
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
my-app/
|
|
51
|
+
├── electron/
|
|
52
|
+
│ ├── main.js النافذة والقائمة وجسر النظام
|
|
53
|
+
│ └── preload.js ما تراه صفحاتك من النظام (window.kreftDesktop)
|
|
54
|
+
├── build/icon.png أيقونة التطبيق
|
|
55
|
+
├── dist/ البناء الثابت (kreft build --base ./)
|
|
56
|
+
├── dist-electron/ المثبّتات التي يكتبها electron-builder
|
|
57
|
+
└── package.json "main": "electron/main.js" وكتلة "build"
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## كيف يعمل
|
|
61
|
+
|
|
62
|
+
- أثناء التطوير: خادم Kreft المخفي يخدّم الصفحات، والنافذة تفتحه. لا متصفح يُفتح ولا عنوان يُطبع.
|
|
63
|
+
- في التطبيق المحزوم: النافذة تحمّل `dist/index.html` مباشرة من الملفات، بلا خادم.
|
|
64
|
+
|
|
65
|
+
## اكتشاف تطبيق سطح المكتب
|
|
66
|
+
|
|
67
|
+
```js
|
|
68
|
+
if (Kreftjs.isElectron) {
|
|
69
|
+
const info = await kreftDesktop.getInfo() // { name, version, platform, arch, isPackaged }
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```html
|
|
74
|
+
<!-- components/Titlebar.kreft -->
|
|
75
|
+
state info = null
|
|
76
|
+
on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
|
|
77
|
+
|
|
78
|
+
<view>
|
|
79
|
+
<footer k-if="info">{info.name} v{info.version} · {info.platform}</footer>
|
|
80
|
+
</view>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## جسر سطح المكتب
|
|
84
|
+
|
|
85
|
+
`window.kreftDesktop` (وكذلك `Kreftjs.desktop`) هو الطريقة الوحيدة التي تصل بها صفحاتك إلى النظام. لا شيء آخر من Node.js أو Electron مكشوف.
|
|
86
|
+
|
|
87
|
+
| الدالة | ماذا تفعل |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `getInfo()` | اسم التطبيق والإصدار والنظام. |
|
|
90
|
+
| `minimize()` و`maximize()` و`close()` | التحكم بالنافذة. |
|
|
91
|
+
| `getMenu()` و`setMenu('show' \| 'auto' \| 'hide')` | قائمة النافذة. |
|
|
92
|
+
| `openDevTools(mode)` و`closeDevTools()` و`toggleDevTools()` | أدوات المطوّر. |
|
|
93
|
+
| `showMessageBox(options)` | مربع رسالة أصلي. |
|
|
94
|
+
| `showOpenDialog(options)` و`showSaveDialog(options)` | نوافذ اختيار الملفات. |
|
|
95
|
+
|
|
96
|
+
```html
|
|
97
|
+
action confirmDelete() {
|
|
98
|
+
const r = await kreftDesktop.showMessageBox({
|
|
99
|
+
type: 'warning',
|
|
100
|
+
buttons: ['حذف', 'إلغاء'],
|
|
101
|
+
defaultId: 1,
|
|
102
|
+
cancelId: 1,
|
|
103
|
+
title: 'تأكيد',
|
|
104
|
+
message: 'هل تريد حذف هذا العنصر؟',
|
|
105
|
+
})
|
|
106
|
+
if (r.response === 0) await remove()
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## إضافة دالة سطح مكتب خاصة بك
|
|
111
|
+
|
|
112
|
+
1. في `electron/main.js` أضف معالجًا: `ipcMain.handle('app:ping', () => 'pong')`.
|
|
113
|
+
2. في `electron/preload.js` أضفه إلى كائن `desktop`: `ping: () => ipcRenderer.invoke('app:ping')`.
|
|
114
|
+
3. استعمله من الصفحة: `await kreftDesktop.ping()`.
|
|
115
|
+
|
|
116
|
+
> **تنبيه أمني:** مرّر الحد الأدنى من البيانات، وتحقق منها في `main.js`. هذا جسر بين صفحة (قد تُحقن فيها شيفرة) ونظام التشغيل.
|
|
117
|
+
|
|
118
|
+
## أدوات المطوّر
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
kreft electron --devtools # على اليمين
|
|
122
|
+
kreft electron --devtools=bottom # أسفل أو left أو detach
|
|
123
|
+
kreft electron --no-devtools
|
|
124
|
+
ELECTRON_DEVTOOLS=bottom kreft electron
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
والمفتاح F12 (أو Ctrl+Shift+I) يبدّل اللوحة.
|
|
128
|
+
|
|
129
|
+
## قائمة النافذة
|
|
130
|
+
|
|
131
|
+
اضبط شريط القائمة عند بدء التطبيق:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
ELECTRON_MENU=show kreft electron # الافتراضي: الشريط ظاهر
|
|
135
|
+
ELECTRON_MENU=auto kreft electron # مخفي، اضغط Alt لإظهاره (Windows وLinux)
|
|
136
|
+
ELECTRON_MENU=hide kreft electron # بلا قائمة
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
أو غيّرها والتطبيق يعمل من صفحة:
|
|
140
|
+
|
|
141
|
+
```js
|
|
142
|
+
window.kreftDesktop.setMenu('hide') // 'show' | 'auto' | 'hide'
|
|
143
|
+
window.kreftDesktop.getMenu() // الوضع الحالي
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
على macOS تعيش القائمة في الشريط العلوي للشاشة، فـ `show` و`auto` متشابهان، و`hide` يُبقي قائمة اسم التطبيق (فيها Quit) لأن macOS يحتاج واحدة. ولقائمتك الخاصة (File, Edit…) استعمل `Menu.buildFromTemplate([...])` و`Menu.setApplicationMenu(...)` في `electron/main.js`.
|
|
147
|
+
|
|
148
|
+
> **للتطبيقات التي أُنشئت قبل 0.0.18:** ملف `electron/main.js` القديم بلا هذه الميزة. انسخ تعديلاتك احتياطيًا، واحذف الملف، وشغّل `kreft electron:init`.
|
|
149
|
+
|
|
150
|
+
## أيقونة التطبيق
|
|
151
|
+
|
|
152
|
+
يضع `kreft electron:init` شعار Kreft في `build/icon.png`. استبدله بأيقونتك: PNG مربعة 512×512 أو أكبر. تستعملها النافذة، ويصنع electron-builder منها `.icns` (macOS) و`.ico` (Windows). واسم التطبيق في `build.productName` و`build.appId` داخل `package.json`.
|
|
153
|
+
|
|
154
|
+
يحتاج electron-builder أيضًا إلى `description` و`homepage` و`author` (مع بريد) و`build.linux.maintainer` (لـ `.deb` و`.rpm`). الأمران `kreft electron:init` و`kreft electron:build` يملآن الناقص منها من اسمك وبريدك في git؛ راجعها قبل الإصدار.
|
|
155
|
+
|
|
156
|
+
## المثبّتات
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
npm run electron:build:mac # .dmg و .zip
|
|
160
|
+
npm run electron:build:win # مثبّت NSIS و .exe محمول
|
|
161
|
+
npm run electron:build:linux # AppImage و .deb و .rpm
|
|
162
|
+
npm run electron:build:all # الثلاثة
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
تُكتب في `dist-electron/`. والوسائط تذهب إلى electron-builder، مثل `kreft electron:build --mac --arm64`. الإعدادات الافتراضية في كتلة `build` من `package.json`:
|
|
166
|
+
|
|
167
|
+
| النظام | الأهداف |
|
|
168
|
+
|---|---|
|
|
169
|
+
| Windows | مثبّت `nsis` (تختار المجلد) و`portable` |
|
|
170
|
+
| macOS | `dmg` و`zip` |
|
|
171
|
+
| Linux | `AppImage` و`deb` و`rpm` |
|
|
172
|
+
|
|
173
|
+
- ابنِ كل نظام على نظامه. على Mac تُبنى AppImage ومثبّتات Windows، لكن `.deb` و`.rpm` تفشل: ابنهما على Linux، أو احذفهما من `build.linux.target`.
|
|
174
|
+
- توقيع الشيفرة (code signing) يُضبط عبر electron-builder (electron.build/code-signing) ولازم قبل تسليم التطبيق للناس؛ تطبيقات macOS غير الموقّعة تعرض تحذير Gatekeeper.
|
|
175
|
+
- **التطبيق المحزوم لا يشغّل واجهة خلفية.** يحمّل `dist/index.html` فقط. تطبيق الواجهة وحدها يعمل كما هو؛ أما التطبيق المتكامل (تسجيل دخول وقاعدة بيانات) فلا يعمل بعد التثبيت ما لم تشغّل خادمًا في مكان ما وتوجّه `api.setup({ base })` إليه.
|
|
176
|
+
|
|
177
|
+
## `npm run build` أم `electron:build`؟
|
|
178
|
+
|
|
179
|
+
إضافة Electron لا تغيّر `npm run build`. الأمران يصنعان شيئين مختلفين:
|
|
180
|
+
|
|
181
|
+
| الأمر | ماذا يصنع | استعمله لـ |
|
|
182
|
+
|---|---|---|
|
|
183
|
+
| `npm run build` | الموقع في `dist/`، بمسارات تبدأ بـ `/` (ومجلد `docs/` مضمَّن). | نشر التطبيق على خادم ويب. |
|
|
184
|
+
| `npm run electron:build` | الموقع نفسه مبنيًا بـ `--base ./` ليُفتح من ملف، ثم مثبّت في `dist-electron/`. | تسليم التطبيق كبرنامج سطح مكتب. |
|
|
185
|
+
|
|
186
|
+
`dist/` الناتج عن `npm run build` يعرض نافذة بيضاء إن فتحته في Electron لأن مساراته تبدأ بـ `/`. شغّل `electron:build` (أو `kreft build --base ./`) أولًا. ولا مانع من الاثنين: `electron:build` يعيد كتابة `dist/`، فشغّل `npm run build` من جديد قبل نشر الموقع.
|
|
187
|
+
|
|
188
|
+
## الأمان
|
|
189
|
+
|
|
190
|
+
النافذة تتبع إرشادات Electron الأمنية:
|
|
191
|
+
|
|
192
|
+
- `contextIsolation: true` و`nodeIntegration: false` و`sandbox: true`: صفحتك لا ترى Node.js.
|
|
193
|
+
- الروابط الخارجية تُفتح في المتصفح الافتراضي للنظام، لا داخل النافذة.
|
|
194
|
+
- التنقل بعيدًا عن أصل التطبيق ممنوع.
|
|
195
|
+
- الجسر يمرر حقولًا مسموحة فقط إلى نوافذ الحوار.
|
|
196
|
+
|
|
197
|
+
## استكشاف الأخطاء
|
|
198
|
+
|
|
199
|
+
| الرسالة أو العَرَض | الحل |
|
|
200
|
+
|---|---|
|
|
201
|
+
| `Electron is not installed locally` | `kreft add -D electron` |
|
|
202
|
+
| `electron-builder is not installed` | `kreft add -D electron-builder` |
|
|
203
|
+
| نافذة بيضاء في التطبيق المحزوم | أعد تشغيل `electron:build` (يلزمه `--base ./`) وتأكد من وجود `dist/index.html` |
|
|
204
|
+
| `.deb` أو `.rpm` تفشل على Mac | ابنهما على Linux أو احذفهما من `build.linux.target` |
|
|
205
|
+
| خطأ author/maintainer/homepage عند بناء Linux | أضف `author` ببريد و`homepage` و`build.linux.maintainer` في `package.json` |
|
|
206
|
+
| لا أستطيع إخفاء القائمة | استعمل `ELECTRON_MENU=hide`؛ وللتطبيقات القديمة أعد توليد `electron/main.js` |
|
|
207
|
+
|
|
208
|
+
## مثال: تطبيق ملاحظات لسطح المكتب (واجهة فقط)
|
|
209
|
+
|
|
210
|
+
تطبيق لا يحتاج خادمًا: الملاحظات تُحفظ بـ `saved` في الجهاز، وأوامر النظام عبر الجسر.
|
|
211
|
+
|
|
212
|
+
```html
|
|
213
|
+
<!-- pages/Notes.kreft -->
|
|
214
|
+
saved notes = [] // تبقى بعد إغلاق التطبيق
|
|
215
|
+
state text = ''
|
|
216
|
+
state info = null
|
|
217
|
+
|
|
218
|
+
on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
|
|
219
|
+
|
|
220
|
+
action add() {
|
|
221
|
+
if (!text.trim()) return
|
|
222
|
+
notes.unshift({ id: Date.now(), text: text.trim() })
|
|
223
|
+
text = ''
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
action removeNote(n) {
|
|
227
|
+
if (Kreftjs.isElectron) {
|
|
228
|
+
const r = await kreftDesktop.showMessageBox({
|
|
229
|
+
type: 'question', buttons: ['حذف', 'إلغاء'], defaultId: 1, cancelId: 1,
|
|
230
|
+
message: 'حذف هذه الملاحظة؟',
|
|
231
|
+
})
|
|
232
|
+
if (r.response !== 0) return
|
|
233
|
+
}
|
|
234
|
+
notes = notes.filter((x) => x.id !== n.id)
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
action hideMenu() { kreftDesktop.setMenu('hide') }
|
|
238
|
+
|
|
239
|
+
<view>
|
|
240
|
+
<h1>ملاحظاتي</h1>
|
|
241
|
+
<form novalidate @submit.prevent={add}>
|
|
242
|
+
<input k-model="text" placeholder="اكتب ملاحظة…">
|
|
243
|
+
</form>
|
|
244
|
+
|
|
245
|
+
<ul>
|
|
246
|
+
<li k-each="n in notes" k-key="n.id">{n.text} <button @click="removeNote(n)">✕</button></li>
|
|
247
|
+
</ul>
|
|
248
|
+
|
|
249
|
+
<p k-if="info">{info.name} {info.version} · {info.platform}</p>
|
|
250
|
+
<button k-if="Kreftjs.isElectron" @click="hideMenu">أخفِ القائمة</button>
|
|
251
|
+
</view>
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
## تمارين
|
|
255
|
+
|
|
256
|
+
1. أنشئ تطبيق سطح مكتب بـ `kreft new notes --electron`، وغيّر الأيقونة، وابنِ `.dmg` أو `.exe`.
|
|
257
|
+
2. أضف دالة `ping` خاصة بك عبر `ipcMain` و`preload.js`.
|
|
258
|
+
3. ابنِ للنظامين وقارن حجم المثبّتين.
|