كيفية بناء محرر Excel تعاوني باستخدام GridJs

دليل المحرر التعاوني لإكسل

نظرة عامة على الهندسة المعمارية

يوضح الرسم التالي كيف يمكّن GridJs من التحرير التعاوني بمشاركة عدة مستخدمين، خلفية Spring Boot، اتصال عبر WebSocket، و قاعدة بيانات MySQL لإدارة الحالة.

هيكلية التعاونية لـ GridJs

متطلبات قبلية

قبل البدء، تأكد من أن لديك الملفات التالية مثبتة:

Java 8+
Maven
MySQL (أو قاعدة بيانات SQL مدعومة أخرى)
(اختياري) Docker إذا فضلت التشغيل في حاويات
ترخيص Aspose.Cells صالح (أو ترخيص مؤقت)

Step 1: Clone the Demo Project

Clone the official Aspose.Cells GridJs demo repository:

git clone https://github.com/aspose-cells/Aspose.Cells.Grid-for-Java.git
cd Aspose.Cells-for-Java/Examples.GridJs.Collaborative

Step 2: Configure Collaborative Mode

Open the src/main/resources/application.properties file and adjust the settings:

# Directory containing spreadsheet files
testconfig.ListDir=/app/wb

# Directory for storing cache files
testconfig.CachePath=/app/grid_cache

# Aspose.Cells license file
testconfig.AsposeLicensePath=/app/license

# Enable collaborative mode
gridjs.iscollabrative=true

# Database connection (example: MySQL)
spring.datasource.url=jdbc:mysql://localhost:3306/gridjsdemodb?createDatabaseIfNotExist=true&useUnicode=true&serverTimezone=UTC&useSSL=false
spring.datasource.username=root
spring.datasource.password=root
spring.sql.init.platform=mysql

هذا يسمح لمستخدمين متعددين بتحرير نفس جدول البيانات في الوقت ذاته.
يتم تخزين التغييرات في قاعدة البيانات ومزامنتها بين العملاء في الوقت الحقيقي.

Step 3: Run the Application

Run with Maven:

mvn spring-boot:run

أو مباشرة من الفئة الرئيسية:

src/main/java/com/aspose/gridjsdemo/usermanagement/UserManagementApplication.java

Step 4: Test Collaborative Editing

Open your browser and navigate to:
👉 http://localhost:8080/gridjsdemo/list

Steps:

A login page appears. Click Create User to register User1 and log in. You will then see the file list.
Open a file from the list. The spreadsheet editor will load.
Copy the same URL into another browser window. It will redirect to the login page. Create User2 and log in.
Both users now see the same spreadsheet.
If User1 edits the spreadsheet, User2 will see the changes in real time.
If User2 edits, User1 will see the changes as well.
Users can also download and save the file.

الخطوة 5: التشغيل في دوكر (اختياري)

إذا كنت تعمل في دوكر، قم بتحرير السطر 10 من docker-compose.yml لتهيئة ملف الترخيص.

على سبيل المثال، إذا كان ملف الترخيص الخاص بك في C:/license/aspose.lic:

volumes:
  - C:/license/aspose.lic:/app/license  # optional: set Aspose license file

يقوم هذا بربط الملف المحلي داخل الحاوية.

ثم بناء وتشغيل:

docker-compose up --build

الوصول إلى التطبيق عبر:
👉 http://localhost:8080/gridjsdemo/list

Key Configuration Details

1. Enable Collaborative Mode

In /src/main/resources/application.properties:

gridjs.iscollabrative=true

في إعدادات الخادم /src/main/java/com/aspose/gridjsdemo/filemanagement/FileConfig.java:

@Bean
public GridJsOptions gridJsOptions() {
    //..... other options
    //here we shall set true for collaborative mode
    options.setCollaborative(true);
    return options;
}

أو بشكل عام:

Config.setCollaborative(true);

في خيارات تحميل العميل /src/main/resources/templates/file/index.html:

const option = {
    //..... other options
    //here we shall set true for collaborative mode
    isCollaborative: true
    //..... other options
};

2. User System Integration

The demo uses Spring Security for a simple user system.

You must provide a CoWorkUserProvider implementation to connect GridJs with your user system:

In server-side config /src/main/java/com/aspose/gridjsdemo/filemanagement/FileConfig.java:

For example: here we defined MyCustomUser to implement all the interfaces in CoWorkUserProvider.

@Bean
public CoWorkUserProvider currentUserProvider() {
    return new MyCustomUser();
}

في /src/main/java/com/aspose/gridjsdemo/filemanagement/MyCustomUser.java:

public class MyCustomUser implements CoWorkUserProvider {
    //Get the current login user name
    @Override
    public String getCurrentUserName() {
        return getCurrentUser().getUsername();
    }

    //Get the current login user Id
    @Override
    public Long getCurrentUserId() {
        return getCurrentUser().getUserId();
    }

    //Get the current login user permission
    @Override
    public CoWorkUserPermission getPermission() {
        return CoWorkUserPermission.EDITABLE;
    }

    private static CustomUserDetails getCurrentUser() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication != null && authentication.getPrincipal() instanceof CustomUserDetails) {
            return (CustomUserDetails) authentication.getPrincipal();
        }
        throw new IllegalStateException("User not authenticated");
    }
}

3. WebSocket Configuration

The demo uses Spring WebSocket with STOMP.

Example config:

In /src/main/java/com/aspose/gridjsdemo/messages/WebSocketConfig.java:

public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic");
        config.setApplicationDestinationPrefixes("/app");
        config.setUserDestinationPrefix("/user");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws")
                .setAllowedOrigins("http://localhost:8080")
                .withSockJS();
    }
}

يتوقع GridJs أن يطابق messageTopic مع “/topic/opr” وهو الافتراضي:

com.aspose.gridjs.Config.setMessageTopic("/topic/opr");

أو:

@Bean
    public GridJsOptions gridJsOptions() {
	//.... other options
    	options.setMessageTopic("/topic/opr");
    	//.... other options
        return options;
    }

على جانب العميل:

xs.setCollaborativeSetting('/GridJs2/msg','/ws','/app/opr','/user/queue','/topic/opr');

هنا، /GridJs2/msg يتوافق مع مسار الطريق المحدد في
src/main/java/com/aspose/gridjsdemo/filemanagement/controller/GridJsOprController.java:

@RequestMapping("/GridJs2/msg")

مثال مع مسارات ويب سوكيت مخصصة

إذا كان سيرفرك يستخدم إعدادات مختلفة:

public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic_gridjs");
        config.setApplicationDestinationPrefixes("/app_gridjs");
        config.setUserDestinationPrefix("/user_gridjs");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws_gridjs")
                .setAllowedOrigins("http://localhost:8080")
                .withSockJS();
    }
}

ثم يجب عليك تعيين:

جانب الخادم:

com.aspose.gridjs.Config.setMessageTopic("/topic_gridjs/opr");

أو

    @Bean
    public GridJsOptions gridJsOptions() {
	//.... other option
    	options.setMessageTopic("/topic_gridjs/opr");
    	//.... other option
        return options;
    }

جانب العميل:

xs.setCollaborativeSetting('/GridJs2/msg','/ws_gridjs','/app_gridjs/opr','/user_gridjs/queue','/topic_gridjs/opr');

يمكن العثور على وثيقة التفاصيل لإعدادCollaborativeSetting هنا

⚠️ ملاحظة: بشكل افتراضي، يعمل تكوين العرض التوضيحي مباشرة بدون تعديلات.
يُطلب تكوين إضافي فقط إذا كانت تطبيقك تخصص نقاط نهاية WebSocket.

وتذكّر أيضًا: وضع التعاون لا يدعم التحميل الكسول.
لا تفعّل Config.setLazyLoading(true).

Additional Notes

We can add file uploads to load and edit spreadsheet file from upload directory.
Integrate with cloud storage like AWS S3 or Azure Blob.

الخاتمة

مع Aspose.Cells.GridJs، يمكنك بسرعة بناء محرر Excel التعاوني قوي.
يكفل دمج خلفية جافا، واجهة GridJs، تخزين SQL، ورسائل WebSocket تحرير جداول بيانات موثوق في الوقت الحقيقي.

Resources

كيفية عمل التحميل الكسول في GridJs