توثيق Nexamas.UI

نظرة عامة

Nexamas.UI هي حزمة SDK مغلقة المصدر لواجهات Windows Forms، وتقدم نموذج MAS API عامًا واحدًا على .NET Framework 4.8 و.NET 10 for Windows.

اسم المنتج وحزمة NuGet والتجميعة وجذر مساحات الأسماء هو Nexamas.UI. تستخدم الواجهة العامة للمستهلك عائلة MAS* المستقرة، ومنها MASApplication وMASApplicationWindow وMASButton وMASDataGrid والأنواع المرتبطة بها.

• تكوين التطبيق والنوافذ عبر واجهات التطبيق العامة.
• مصانع Controls typed، وبناة Layout، والثيمات والمواد، وأساس الترجمة وRTL.
• واجهات عرض البيانات وسير العمل، مع بنية قياس الجودة والتحقق البصري.
• نموذج منتج موحد على كلا إطاري العمل المدعومين.

متطلبات النظام

مسار الإثبات الموثق هو Windows Desktop وWindows Forms وبنية Release|x64 مع إطاري عمل مدعومين.

التثبيت عبر NuGet وZIP

يستخدم الإصدار التجريبي هوية الحزمة Nexamas.UI ورقم 1.0.0-preview.1. يبقى التوزيع العام محجوبًا عمدًا حتى Phase 40.9.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
    <EnableWindowsTargeting>true</EnableWindowsTargeting>
    <PlatformTarget>x64</PlatformTarget>
    <Prefer32Bit>false</Prefer32Bit>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Nexamas.UI" Version="1.0.0-preview.1" />
  </ItemGroup>
</Project>

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="NexamasPreview" value="PATH_OR_FEED_PROVIDED_BY_NEXAMAS" />
    <add key="NuGetOfficial" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

• يجب أن يحتوي ZIP على الحزمة المعتمدة نفسها، والترخيص، وملاحظات الإصدار، وبيان SHA-256.
• لا تنسخ التجميعات يدويًا بين مجلدات إطارات العمل عندما تكون NuGet متاحة.
• يمكن حفظ Community في مستودع داخلي خاص بالشركة، لكن لا يجوز نسخها إلى Feed عام.

بداية سريعة

أنشئ تطبيق Windows Forms، وأضف مرجع Nexamas.UI، ثم اربط أو أنشئ نافذة MAS.

Option Strict On
Option Explicit On

Imports System
Imports System.Windows.Forms
Imports Nexamas.UI.Application
Imports Nexamas.UI.Controls
Imports Nexamas.UI.Layout

Public NotInheritable Class MainForm
    Inherits Form

    Private ReadOnly _window As MASApplicationWindow

    Public Sub New()
        Text = "Nexamas UI Quickstart"
        Width = 1000
        Height = 700
        StartPosition = FormStartPosition.CenterScreen

        _window = MASApplication.AttachWindow(
            owner:=Me,
            configure:=Sub(window As MASApplicationWindow)
                Dim title As MASTitle = window.Controls.AddTitle("Nexamas UI")
                Dim message As MASLabel = window.Controls.AddLabel("One MAS API on net48 and .NET 10.")
                Dim action As MASButton = window.Controls.AddButton("Ready")

                AddHandler action.Click,
                    Sub(sender As Object, e As EventArgs)
                        window.Services.Toasts.Success("The package consumer is alive.", "Quickstart")
                    End Sub

                window.Controls.LayoutPage(
                    Sub(page As MASApplicationLayoutPageBuilder)
                        page.Padding(MASLayoutSpacing.Spacious)
                        page.Spacing(MASLayoutSpacing.Medium)
                        page.FullWidth(title, MASSize.FillWidth)
                        page.FullWidth(message, MASSize.FillWidth)
                        page.ActionGroup(
                            Sub(actions As MASApplicationActionGroupLayoutBuilder)
                                actions.AlignCenter().EqualItemWidth().Add(action, MASSize.Default)
                            End Sub)
                    End Sub)
            End Sub)
    End Sub

    Protected Overrides Sub OnFormClosed(e As FormClosedEventArgs)
        If _window IsNot Nothing Then _window.Dispose()
        MyBase.OnFormClosed(e)
    End Sub
End Class

using System;
using System.Windows.Forms;
using Nexamas.UI.Application;
using Nexamas.UI.Controls;
using Nexamas.UI.Layout;

internal sealed class MainForm : Form
{
    private readonly MASApplication _application;
    private readonly MASApplicationWindow _window;

    internal MainForm()
    {
        Text = "Nexamas UI Quickstart";
        Width = 1000;
        Height = 700;

        _application = MASApplication.Create();
        _window = _application.CreateWindow(this);

        MASTitle title = _window.Controls.AddTitle("Nexamas UI");
        MASLabel message = _window.Controls.AddLabel("One MAS API on net48 and .NET 10.");
        MASButton action = _window.Controls.AddButton("Ready");

        _window.Controls.LayoutPage(page =>
        {
            page.Padding(MASLayoutSpacing.Spacious);
            page.Spacing(MASLayoutSpacing.Medium);
            page.FullWidth(title, MASSize.FillWidth);
            page.FullWidth(message, MASSize.FillWidth);
            page.ActionGroup(actions => actions.AlignCenter().EqualItemWidth().Add(action, MASSize.Default));
        });
    }

    protected override void OnFormClosed(FormClosedEventArgs e)
    {
        _window?.Dispose();
        _application?.Dispose();
        base.OnFormClosed(e);
    }
}

قائمة أول تطبيق

ابدأ بشريحة صغيرة قبل نقل شاشة إنتاجية: نافذة واحدة، عنوان، Label، إجراء واحد وLayout بسيط.

• اختر net48 أو net10.0-windows10.0.19041.0 وبنية x64.
• أضف الإصدار التجريبي المحدد من Feed أو ZIP المعتمد.
• أنشئ Form عاديًا في WinForms واربط MASApplicationWindow.
• أضف عناصر التحكم عبر مصانع window.Controls typed.
• كوّن الصفحة عبر LayoutPage وMASSize بدل تثبيت المواقع بالبكسل.
• تخلص من النافذة وواجهة التطبيق بصورة صحيحة.
• اختبر تركيز لوحة المفاتيح وDPI وتغيير الحجم واتجاه الترجمة وبيانات واقعية.

هيكل التطبيق

صُممت طبقة التطبيق العامة لتنسيق النوافذ والتنقل والتخطيط والأوامر والـOverlays والتغذية الراجعة والخدمات التي يملكها التطبيق.

استخدم MASApplication.AttachWindow(...) لتطبيق صغير بنافذة واحدة. واستخدم MASApplication.Create() وCreateWindow(...) عندما تملك نسخة تطبيق واحدة عدة نوافذ.

Dim application As MASApplication = MASApplication.Create()
Dim window As MASApplicationWindow = application.CreateWindow(owner:=Me)

Dim navigation = window.Controls.AddNavigationRail()
Dim title = window.Controls.AddTitle("Operations")
Dim content = window.Controls.AddPanel()

window.Controls.LayoutPage(
    Sub(page)
        page.Padding(MASLayoutSpacing.Spacious)
        page.Spacing(MASLayoutSpacing.Medium)
        page.FullWidth(title, MASSize.FillWidth)
        page.FullWidth(content, MASSize.Fill)
    End Sub)

• اجعل دورة حياة النوافذ صريحة.
• استخدم بوابات الخدمات التي يملكها التطبيق بدل Global singletons.
• عامل تكوين Showcase كمثال، لا كمصدر سلطة للادعاءات العامة.
• لا تستدع أنظمة Friend/internal مباشرة من تطبيقات العملاء.

الثيمات والأسطح

توفر Nexamas.UI بوابات عامة للثيمات والأسطح، بينما تبقى بنية التصميم والتحقق والاستوديو الأعمق داخلية ما لم تُكشف بعقد مستقل.

Dim app As MASApplication = MASApplication.Create()
Dim window As MASApplicationWindow = app.CreateWindow(owner:=Me)

' Use the public application/window theme gateway.
' Keep theme selection at the application boundary rather than styling each control independently.
Dim themeGateway = window.Theme

• اختر الثيم على مستوى التطبيق أو النافذة.
• استخدم وصفات مشتركة للمسافات والأحجام والمواد والحالات للحفاظ على الاتساق.
• تحقق من التباين وحالات التركيز في الثيمين الفاتح والداكن.
• لا يُدعى أن Theme Studio وSurface Designer واجهات SDK عامة في هذا الإصدار.

نظرة على عناصر التحكم

يحتوي المخزون المعتمد على 80 عنصر تحكم مصنفًا بين Community ومسارات Community + Pro المشتركة وProfessional.

• التطبيق والتنقل: العناوين والأسطح الأمرية والتنقل واللوحات والـOverlays والتغذية الراجعة.
• الإدخال والاختيار: الأزرار والنصوص والمحددات والقوائم والأشجار والمحررات وسلوك التركيز.
• البيانات وسير العمل: Grids وViews وMaster-detail والتخطيط ولوحات المعلومات والفلاتر والرسوم والملفات.
• تُباع عناصر Professional المتقدمة حسب سياسة الإصدارات فقط عندما يكون المصدر والـPublic API والإثبات موجودًا.

التخطيط والأحجام

استخدم بناة Layout العامة وMASSize وMASLayoutSpacing للتعبير عن المقصود بدل تحديد موقع كل عنصر يدويًا.

window.Controls.LayoutPage(
    Sub(page As MASApplicationLayoutPageBuilder)
        page.Padding(MASLayoutSpacing.Spacious)
        page.Spacing(MASLayoutSpacing.Medium)
        page.FullWidth(header, MASSize.FillWidth)
        page.FullWidth(dataGrid, MASSize.Fill)
        page.ActionGroup(
            Sub(actions)
                actions.AlignEnd().EqualItemWidth()
                actions.Add(cancelButton, MASSize.Default)
                actions.Add(saveButton, MASSize.Default)
            End Sub)
    End Sub)

• استخدم FillWidth أو Fill للأسطح التي يجب أن تتغير مع حجم النافذة.
• استخدم Action Groups لصفوف الأوامر المحاذاة.
• اختبر الأحجام الدنيا وDPI والنصوص المترجمة الطويلة واتجاه RTL.
• لا تعتمد على أصناف responsive أو virtualization الداخلية كواجهات عامة.

واجهات البيانات

يمتلك DataGrid وDataView واجهات عامة موثقة للمستهلك، بينما تخضع عناصر سير العمل الاحترافية الأخرى لمخزون الإصدارات المعتمد.

Dim grid As MASDataGrid = window.Controls.AddDataGrid()
Dim view As MASDataView = window.Controls.AddDataView()

' Bind through the documented public consumer surface for your release.
' Validate large-data behavior with representative customer data before shipping.

• ابدأ بعدد صفوف واقعي وأشكال أعمدة ممثلة لحالتك.
• تحقق من الاختيار والتحرير والتنقل بلوحة المفاتيح والفرز والتصفية وتغيير الحجم المطلوب لسير العمل.
• عامل محركات virtualization الداخلية كتفاصيل تنفيذ ما لم تكشف بوابة عامة عقدًا صريحًا.
• لا يجوز نسخ عناصر Professional أو الوصول إليها بالانعكاس أو استدعاؤها من Community عبر واجهات داخلية.

دليل Showcase

يعرض Showcase تكوينات ورحلات عميل مثبتة، لكنه لا يعيد تعريف حقيقة الحزمة أو الإصدار أو الترخيص أو الـAPI.

• استخدم صورًا ومصدر مثال يستهلك واجهات Nexamas.UI العامة فقط.
• يمكن نشر تطبيق المثال لأنه يستهلك SDK، بينما يبقى مصدر SDK المغلق خاصًا.
• يجب أن تعمل عروض Professional عبر الحدود البعيدة أو المرخصة المعتمدة، وألا ترسل ملفات Nexamas.UI.Pro إلى المتصفح.
• تحقق من المثال على Windows وWindows Forms وx64 وإطار العمل الموثق قبل ربطه بإصدار.

ترخيص Community

Community مجانية للاستخدام الشخصي والتعليمي وغير التجاري والتجاري وSaaS والأنظمة الداخلية والتطبيقات المدفوعة ومنتجات الاشتراك.

• لا رسوم Runtime ولا مفتاح ترخيص ولا حد للمقاعد أو المستخدمين أو المشاريع.
• يمكن تضمين DLL غير المعدلة داخل تطبيق نهائي يحتاجها.
• يمكن بيع تطبيقات وقوالب وإضافات وعناصر تحكم ومكتبات أصلية تضيف قيمة مستقلة.
• يمكن حفظ نسخة مطابقة وغير معدلة في مستودع خاص بمؤسسة واحدة.

• لا تبع Nexamas.UI منفردة ولا تغير اسمها ولا تعيد تغليفها ولا تنشر Mirror أوFeed عامًا.
• لا تزل إشعارات الملكية ولا تنشئ SDK مشتقة منافسة.
• تُمنع الهندسة العكسية والتعديلات الداخلية إلا حيث يفرض القانون استثناءً.
• لا يُلزم إظهار النسبة. نقدر توصية ودية بالمشروع عندما تساعدك Nexamas.UI.

مقارنة الإصدار المجاني والاحترافي

صُممت Community لتكون مفيدة دون حدود Runtime مصطنعة، بينما تضيف Professional عناصر متقدمة وحقوق تطوير مرخصة ودعمًا مباشرًا وقناة تسليم خاصة.

إدارة الإصدارات

تستخدم Nexamas.UI Semantic Versioning. أول Community Preview عام هو 1.0.0-preview.1، بينما يبقى AssemblyVersion وFileVersion عند 1.0.0.0 لخط الأساس المعتمد.

• تحمل Community وProfessional رقم إصدار المنتج نفسه.
• إصدار الحزمة المنشور غير قابل للتغيير؛ أي Bytes مختلفة تتطلب إصدارًا جديدًا.
• لا تستخدم عبارة Lifetime Updates. الرخصة الدائمة تعني استخدامًا دائمًا للإصدارات المؤهلة، لا تحديثات مستقبلية غير محدودة.
• تحدد أهلية التحديث عبر وقت الإصدار الموثوق واستحقاق العميل.

استكشاف الأخطاء

تحقق أولًا من إطار العمل والمنصة ومصدر الحزمة واستخدام الـPublic API ونمط التخلص قبل البحث في سلوك أعمق.

• سجل رقم الحزمة وإطار العمل وإصدار Windows والمعمارية ومثالًا مصغرًا يعيد المشكلة.
• بالنسبة إلى Community استخدم التوثيق والتحديثات العامة؛ الدعم المباشر غير مضمون.
• بالنسبة إلى Professional أرفق تفاصيل الاستحقاق دون نشر مادة الترخيص الخاصة علنًا.

ملاحظات الإصدار

1.0.0-preview.1 هي هوية أول Community Preview عام معتمد، ولا تعيد كتابة خط الأساس الهندسي الداخلي المغلق 1.0.0.

• نموذج منتج موحد لـnet48 وnet10.0-windows10.0.19041.0.
• هوية حزمة Nexamas.UI مستقرة وعائلة MAS* عامة للمستهلك.
• تصنيف معتمد لعناصر Community وCommunity + Pro وProfessional.
• توثيق موقع وملفات PDF بالعربية والإنجليزية من عقد محتوى واحد.
• لا يوجد ملف Professional عام أو Checkout أو تسليم Trial إنتاجي في Website Phase 40.

سياسة الدعم

تعتمد Community على التوثيق والتحديثات العامة. تتضمن Professional هدف رد أولي غير تعاقدي، بينما تتطلب خدمات Enterprise اتفاقًا مستقلًا.

• هدف Professional هو رد أولي بنهاية يوم عمل Nexamas التالي.
• هذا الهدف ليس SLA تعاقديًا ولا يضمن مدة حل المشكلة.
• حقوق الاستخدام الدائم منفصلة عن أهلية التحديث والدعم.
• يضيف التجديد السنوي الاختياري €199 مدة 12 شهرًا من التحديثات والدعم؛ ولا يجدد حق الاستخدام الدائم أو يمدده لأنه لا ينتهي.