webview

عرض ويب

مكتبة عرض ويب صغيرة عبر الأنظمة الأساسية لـ C/C++ لإنشاء واجهات المستخدم الرسومية الحديثة عبر الأنظمة الأساسية.

الهدف من المشروع هو إنشاء طبقة تجريد واجهة مستخدم HTML5 مشتركة للأنظمة الأساسية الأكثر استخدامًا.

وهو يدعم روابط JavaScript ثنائية الاتجاه (لاستدعاء JavaScript من C/C++ ولاستدعاء C/C++ من JavaScript).

ملحوظة

تم نقل ربط اللغة لـ Go. الإصدارات <= 0.1.1 متوفرة في هذا المستودع.

دعم المنصة

منصة	التقنيات
لينكس	جي تي كيه، ويب كيت جي تي كيه
ماك	الكاكاو، ويب كيت
ويندوز	واجهة برمجة تطبيقات Windows، WebView2

التوثيق

أحدث الوثائق موجودة مباشرة في الكود المصدري. يعد تحسين التوثيق جهدًا مستمرًا وأنت مرحب بك للمساهمة فيه.

المتطلبات الأساسية

يجب أن يدعم برنامج التحويل البرمجي الخاص بك الحد الأدنى من C++ 11 باستثناء الأنظمة الأساسية التي تتطلب إصدارًا أكثر حداثة.

يستخدم هذا المشروع CMake وNinja، وعلى الرغم من أنه يوصى باستخدام هذه الأدوات لراحتك، إلا أنها ليست مطلوبة لاستخدام المكتبة.

لينكس و بي إس دي

مكتبات GTK وWebKitGTK مطلوبة للتطوير والتوزيع. تحتاج إلى التحقق من مستودعات الحزم الخاصة بك فيما يتعلق بالحزم التي سيتم تثبيتها.

الحزم

• ديبيان:
  • ويبكيتGTK 6.0، GTK 4:
    • التطوير: apt install libgtk-4-dev libwebkitgtk-6.0-dev
    • الإنتاج: apt install libgtk-4-1 libwebkitgtk-6.0-4
  • WebKitGTK 4.1، GTK 3، libsoup 3:
    • التطوير: apt install libgtk-3-dev libwebkit2gtk-4.1-dev
    • الإنتاج: apt install libgtk-3-0 libwebkit2gtk-4.1-0
  • ويبكيتGTK 4.0، GTK 3، ليبسوب 2:
    • التطوير: apt install libgtk-3-dev libwebkit2gtk-4.0-dev
    • الإنتاج: apt install libgtk-3-0 libwebkit2gtk-4.0-37
• فيدورا:
  • ويبكيتGTK 6.0، GTK 4:
    • التطوير: dnf install gtk4-devel webkitgtk6.0-devel
    • الإنتاج: dnf install gtk4 webkitgtk6.0
  • WebKitGTK 4.1، GTK 3، libsoup 3:
    • التطوير: dnf install gtk3-devel webkit2gtk4.1-devel
    • الإنتاج: dnf install gtk3 webkit2gtk4.1
  • ويبكيتGTK 4.0، GTK 3، ليبسوب 2:
    • التطوير: dnf install gtk3-devel webkit2gtk4.0-devel
    • الإنتاج: dnf install gtk3 webkit2gtk4.0
• فري بي إس دي:
  • GTK 4: pkg install webkit2-gtk4
  • GTK 3: pkg install webkit2-gtk3

تبعيات المكتبة

• لينكس:
  • استخدم pkg-config مع --cflags و --libs للحصول على خيارات المترجم/الرابط لإحدى مجموعات الوحدات هذه:
    • gtk4 webkitgtk-6.0
    • gtk+-3.0 webkit2gtk-4.1
    • gtk+-3.0 webkit2gtk-4.0
  • مكتبات الارتباط: dl
• ماك:
  • أطر الارتباط: WebKit
  • مكتبات الارتباط: dl
• ويندوز:
  • WebView2 من NuGet.
  • مكتبات Windows: advapi32 ole32 shell32 shlwapi user32 version

بي إس دي

• قد يتطلب التنفيذ على الأنظمة المستندة إلى BSD إضافة الخيار wxallowed (راجع التثبيت (8)) إلى fstab الخاص بك لتجاوز حماية ذاكرة W^X للملف القابل للتنفيذ. يرجى معرفة ما إذا كان يعمل دون تعطيل ميزة الأمان هذه أولاً.

ويندوز

يجب أن يدعم برنامج التحويل البرمجي الخاص بك C++ 14 ونوصي بإقرانه مع Windows 10 SDK محدث.

بالنسبة لـ Visual C++، نوصي باستخدام Visual Studio 2022 أو إصدار أحدث. هناك بعض المتطلبات عند استخدام MinGW-w64.

يجب أن يكون لدى المطورين والمستخدمين النهائيين وقت تشغيل WebView2 مثبتًا على أنظمتهم لأي إصدار من Windows قبل Windows 11.

ابدء

إذا كنت مطورًا لهذا المشروع، فيرجى الانتقال إلى قسم التطوير.

سيكون لديك تطبيق يعمل، ولكن ننصحك باستكشاف الأمثلة المتاحة.

قم بإنشاء الملفات التالية في دليل جديد:

.gitignore :

 # Build artifacts
/build

مثال C++

CMakeLists.txt :

 cmake_minimum_required ( VERSION 3.16)
project (example LANGUAGES CXX)

set ( CMAKE_RUNTIME_OUTPUT_DIRECTORY " ${CMAKE_BINARY_DIR} /bin" )
set ( CMAKE_LIBRARY_OUTPUT_DIRECTORY " ${CMAKE_BINARY_DIR} /lib" )
set ( CMAKE_ARCHIVE_OUTPUT_DIRECTORY " ${CMAKE_BINARY_DIR} /lib" )

include (FetchContent)

FetchContent_Declare(
    webview
    GIT_REPOSITORY https://github.com/webview/webview
    GIT_TAG 0.12.0)
FetchContent_MakeAvailable(webview)

add_executable (example WIN32 )
target_sources (example PRIVATE main.cc)
target_link_libraries (example PRIVATE webview::core)

main.cc :

# include " webview/webview.h "

# include < iostream >

# ifdef _WIN32
int WINAPI WinMain (HINSTANCE /* hInst */ , HINSTANCE /* hPrevInst */ ,
                   LPSTR /* lpCmdLine */ , int /* nCmdShow */ ) {
# else
int main () {
#endif
  try {
    webview::webview w ( false , nullptr );
    w. set_title ( " Basic Example " );
    w. set_size ( 480 , 320 , WEBVIEW_HINT_NONE);
    w. set_html ( " Thanks for using webview! " );
    w. run ();
  } catch ( const webview:: exception &e) {
    std::cerr << e. what () << ' n ' ;
    return 1 ;
  }

  return 0 ;
}

ج مثال

CMakeLists.txt :

 cmake_minimum_required ( VERSION 3.16)
project (example LANGUAGES C CXX)

set ( CMAKE_RUNTIME_OUTPUT_DIRECTORY " ${CMAKE_BINARY_DIR} /bin" )
set ( CMAKE_LIBRARY_OUTPUT_DIRECTORY " ${CMAKE_BINARY_DIR} /lib" )
set ( CMAKE_ARCHIVE_OUTPUT_DIRECTORY " ${CMAKE_BINARY_DIR} /lib" )

include (FetchContent)

FetchContent_Declare(
    webview
    GIT_REPOSITORY https://github.com/webview/webview
    GIT_TAG 0.12.0)
FetchContent_MakeAvailable(webview)

add_executable (example WIN32 )
target_sources (example PRIVATE main.c)
target_link_libraries (example PRIVATE webview::core_static)

main.c :

# include " webview/webview.h "
# include < stddef.h >

# ifdef _WIN32
# include < windows.h >
# endif

# ifdef _WIN32
int WINAPI WinMain (HINSTANCE hInst, HINSTANCE hPrevInst, LPSTR lpCmdLine,
                   int nCmdShow) {
  ( void )hInst;
  ( void )hPrevInst;
  ( void )lpCmdLine;
  ( void )nCmdShow;
# else
int main ( void ) {
#endif
  webview_t w = webview_create ( 0 , NULL );
  webview_set_title (w, " Basic Example " );
  webview_set_size (w, 480 , 320 , WEBVIEW_HINT_NONE);
  webview_set_html (w, " Thanks for using webview! " );
  webview_run (w);
  webview_destroy (w);
  return 0 ;
}

بناء المثال

بناء المشروع:

cmake -G Ninja -B build -S . -D CMAKE_BUILD_TYPE=Release
cmake --build build

ابحث عن الملف القابل للتنفيذ في دليل build/bin .

بناء المكتبة المدمجة

يمكن إنشاء مكتبة مدمجة عند إنشاء المشروع باستخدام CMake، أو يمكن استدعاء البرنامج النصي amalgamate.py مباشرة.

هذا الأخير موصوف أدناه.

python3 scripts/amalgamate.py --output webview_amalgamation.h core/include/webview/webview.h

راجع python3 scripts/amalgamate.py --help لاستخدام البرنامج النصي.

الاستخدام غير CMake

فيما يلي مثال لاستدعاء المترجمين المشابهين لـGC/Clang مباشرةً. استخدم ملف main.cc من المثال السابق.

ضع إما رأس webview.h المدمج أو كافة الملفات الفردية في libs/webview ، و WebView2.h من MS WebView2 في libs .

قم ببناء المشروع على النظام الأساسي الذي اخترته.

ماك

 c++ main.cc -O2 --std=c++11 -Ilibs -framework WebKit -ldl -o example

لينكس

 c++ main.cc -O2 --std=c++11 -Ilibs $(pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.1) -ldl -o example

ويندوز

 c++ main.cc -O2 --std=c++14 -static -mwindows -Ilibs -ladvapi32 -lole32 -lshell32 -lshlwapi -luser32 -lversion -o example 

التخصيص

أهداف CMake

تتوفر أهداف CMake التالية:

اسم	وصف
webview::core	رؤوس لـ C++.
webview::core_shared	المكتبة المشتركة لـ C.
webview::core_static	المكتبة الثابتة لـ C.

أهداف خاصة للفحوصات عند الطلب والمهام ذات الصلة:

اسم	وصف
webview_format_check	التحقق من الملفات بتنسيق clang.
webview_reformat	إعادة تنسيق الملفات بتنسيق clang.

خيارات كميك

يمكن استخدام الخيارات المنطقية التالية عند إنشاء مشروع عرض ويب مستقل أو عند إنشائه كجزء من مشروعك (على سبيل المثال مع FetchContent).

خيار	وصف
WEBVIEW_BUILD	تمكين البناء
WEBVIEW_BUILD_AMALGAMATION	بناء مكتبة مدمجة
WEBVIEW_BUILD_DOCS	بناء الوثائق
WEBVIEW_BUILD_EXAMPLES	بناء الأمثلة
WEBVIEW_BUILD_SHARED_LIBRARY	بناء المكتبات المشتركة
WEBVIEW_BUILD_STATIC_LIBRARY	بناء مكتبات ثابتة
WEBVIEW_BUILD_TESTS	بناء الاختبارات
WEBVIEW_ENABLE_CHECKS	تمكين الشيكات
WEBVIEW_ENABLE_CLANG_FORMAT	تمكين تنسيق clang
WEBVIEW_ENABLE_CLANG_TIDY	تمكين رنة مرتبة
WEBVIEW_ENABLE_PACKAGING	تمكين التعبئة والتغليف
WEBVIEW_INSTALL_DOCS	تثبيت الوثائق
WEBVIEW_INSTALL_TARGETS	تثبيت الأهداف
WEBVIEW_IS_CI	تتم التهيئة بواسطة متغير بيئة CI
WEBVIEW_PACKAGE_AMALGAMATION	مكتبة الحزمة المدمجة
WEBVIEW_PACKAGE_DOCS	وثائق الحزمة
WEBVIEW_PACKAGE_HEADERS	رؤوس الحزمة
WEBVIEW_PACKAGE_LIB	المكتبات المترجمة الحزمة
WEBVIEW_STRICT_CHECKS	جعل الشيكات صارمة
WEBVIEW_STRICT_CLANG_FORMAT	اجعل فحص تنسيق clang صارمًا
WEBVIEW_STRICT_CLANG_TIDY	اجعل فحص الرنة مرتبًا صارمًا
WEBVIEW_USE_COMPAT_MINGW	استخدم مساعد التوافق لـ MinGW
WEBVIEW_USE_STATIC_MSVC_RUNTIME	استخدم مكتبة وقت التشغيل الثابتة (MSVC)

ملحوظة

يتم تمكين عمليات التحقق افتراضيًا، ولكن لا يتم فرضها افتراضيًا للتطوير المحلي (يتم التحكم فيها بواسطة خيار WEBVIEW_IS_CI ).

الخيارات غير المنطقية:

خيار	وصف
WEBVIEW_CLANG_FORMAT_EXE	مسار clang-format القابل للتنفيذ.
WEBVIEW_CLANG_TIDY_EXE	مسار الملف القابل للتنفيذ clang-tidy .

خيارات المستهلك الحزمة

يمكن استخدام هذه الخيارات عند استخدام حزمة webview CMake.

خيارات خاصة بنظام التشغيل Linux

خيار

وصف

WEBVIEW_WEBKITGTK_API

واجهة برمجة تطبيقات WebKitGTK للتفاعل معها، على سبيل المثال 6.0 أو 4.1 (مستحسن) أو 4.0 . سيؤدي هذا أيضًا إلى تحديد إصدار GTK تلقائيًا. يستخدم أحدث واجهة برمجة تطبيقات موصى بها بشكل افتراضي إذا كانت متوفرة، أو أحدث واجهة برمجة تطبيقات معروفة ومتاحة. لاحظ أنه قد تكون هناك اختلافات كبيرة بين إصدارات واجهة برمجة التطبيقات (API) والتي يمكن أن تؤثر على توفر الميزات. راجع وثائق Webview API للحصول على تفاصيل حول توفر الميزات.

خيارات خاصة بنظام التشغيل Windows

خيار	وصف
WEBVIEW_MSWEBVIEW2_VERSION	إصدار MS WebView2، على سبيل المثال 1.0.1150.38 .
WEBVIEW_USE_BUILTIN_MSWEBVIEW2	استخدم MS WebView2 المدمج.

خيارات وقت الترجمة

يمكن تحديد هذه الخيارات كوحدات ماكرو للمعالج المسبق لتعديل البنية، ولكن ليست هناك حاجة إليها عند استخدام CMake.

ربط واجهة برمجة التطبيقات C

اسم	وصف
WEBVIEW_API	يتحكم في رابط C API ورؤية الرمز وما إذا كانت مكتبة مشتركة. بشكل افتراضي، يكون هذا inline لـ C++ و extern لـ C.
WEBVIEW_BUILD_SHARED	يعدل WEBVIEW_API لبناء مكتبة مشتركة.
WEBVIEW_SHARED	يعدل WEBVIEW_API لاستخدام مكتبة مشتركة.
WEBVIEW_STATIC	يعدل WEBVIEW_API لإنشاء مكتبة ثابتة أو استخدامها.

اختيار الواجهة الخلفية

اسم	وصف
WEBVIEW_GTK	قم بتجميع الواجهة الخلفية لـ GTK/WebKitGTK.
WEBVIEW_COCOA	قم بتجميع الواجهة الخلفية Cocoa/WebKit.
WEBVIEW_EDGE	ترجمة الواجهة الخلفية Win32/WebView2.

خيارات خاصة بنظام التشغيل Windows

خيار	وصف
WEBVIEW_MSWEBVIEW2_BUILTIN_IMPL	تمكين ( 1 ) أو تعطيل ( 0 ) التنفيذ المدمج لمحمل WebView2. يؤدي تمكين هذا إلى تجنب الحاجة إلى WebView2Loader.dll ولكن في حالة وجود ملف DLL، فإن ملف DLL يأخذ الأولوية. يتم تمكين هذا الخيار بشكل افتراضي.
WEBVIEW_MSWEBVIEW2_EXPLICIT_LINK	تمكين ( 1 ) أو تعطيل ( 0 ) الارتباط الصريح لـ WebView2Loader.dll . يؤدي تمكين هذا إلى تجنب الحاجة إلى استيراد المكتبات ( *.lib ). يتم تمكين هذا الخيار بشكل افتراضي إذا تم تمكين WEBVIEW_MSWEBVIEW2_BUILTIN_IMPL .

متطلبات MinGW-w64

من أجل إنشاء هذه المكتبة باستخدام MinGW-w64 على Windows، يجب أن تدعم C++ 14 وأن تحتوي على Windows SDK محدث.

التوزيعات المعروفة بأنها متوافقة:

• LLVM MinGW
• MSYS2
• WinLibs

محمل MS WebView2

لا يعد ربط جزء أداة تحميل WebView2 من Microsoft WebView2 SDK متطلبًا صعبًا عند استخدام مكتبة عرض الويب الخاصة بنا، ولا يتم توزيع WebView2Loader.dll مع تطبيقك.

ومع ذلك، إذا كان WebView2Loader.dll قابلاً للتحميل في وقت التشغيل، على سبيل المثال من دليل الملف القابل للتنفيذ، فسيتم استخدامه؛ وإلا فسيتم استخدام تطبيقنا البسيط بدلاً من ذلك.

إذا كنت ترغب في استخدام المُحمل الرسمي، فتذكر توزيعه مع تطبيقك ما لم تقم بربطه بشكل ثابت. يمكن ربطه بشكل ثابت باستخدام Visual C++ ولكن ليس MinGW-w64.

فيما يلي بعض الطرق الجديرة بالملاحظة التي يختلف بها تنفيذنا للمحمل عن التنفيذ الرسمي:

• لا يدعم تكوين WebView2 باستخدام متغيرات البيئة مثل WEBVIEW2_BROWSER_EXECUTABLE_FOLDER .
• قنوات Microsoft Edge Insider (المعاينة) غير مدعومة.

يمكن استخدام خيارات التخصيص لتغيير كيفية دمج المكتبة لمحمل WebView2.

تطوير

يستخدم هذا المشروع نظام البناء CMake.

تبعيات التنمية

بالإضافة إلى التبعيات المذكورة سابقًا في هذا المستند للتطوير باستخدام مكتبة عرض الويب، يتم استخدام ما يلي أثناء تطوير مكتبة عرض الويب.

• الاندماج:
  • بايثون >= 3.9
• الشيكات:
  • clang-format
  • clang-tidy
• التوثيق:
  • دوكسيجين
  • جراففيس

مبنى

cmake -G " Ninja Multi-Config " -B build -S .
cmake --build build --config CONFIG

استبدل CONFIG بواحد من Debug أو Release أو Profile . استخدم Profile لتمكين تغطية التعليمات البرمجية (GCC/Clang).

تشغيل الاختبارات:

ctest --test-dir build --build-config CONFIG

إنشاء تقرير تغطية الاختبار:

gcovr

ابحث عن تقرير التغطية في build/coverage .

التعبئة والتغليف

قم بتشغيل هذا بعد إنشاء تكوينات Debug Release للمشروع:

 cd build
cpack -G External -C " Debug;Release " --config CPackConfig.cmake

التجميع المتقاطع

راجع ملفات CMake Toolchain في دليل cmake/toolchains .

على سبيل المثال، يستهدف هذا Windows x64 على Linux مع سلاسل POSIX:

cmake -G " Ninja Multi-Config " -B build -S . -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/x86_64-w64-mingw32.cmake -D WEBVIEW_TOOLCHAIN_EXECUTABLE_SUFFIX=-posix
cmake --build build --config CONFIG

القيود

مميزات المتصفح

نظرًا لأن محرك المتصفح ليس متصفح ويب كاملاً، فقد لا يدعم كل الميزات التي قد تتوقعها من المتصفح. إذا وجدت أن إحدى الميزات لا تعمل كما هو متوقع، فيرجى الرجوع إلى وثائق محرك المتصفح وفتح مشكلة إذا كنت تعتقد أن المكتبة يجب أن تدعمها.

على سبيل المثال، لا تحاول المكتبة دعم ميزات تفاعل المستخدم مثل alert() confirm() prompt() وغيرها من الميزات غير الأساسية مثل console.log() .

الارتباطات

لغة	مشروع
آدا	thechampagne/webview-ada
كعكة	tr1ckydev/webview-bun
ج #	webview/webview_csharp
ج3	thechampagne/webview-c3
كريستال	naqvis/webview
د	thechampagne/webview-d، ronnie-w/webviewd
دينو	webview/webview_deno
يذهب	webview/webview_go
هاربور	إريك ليندفاي/Harbour_WebView
هاسكل	Lettier/webviewhs
جانيت	جانيت لانج/عرض الويب
جافا	webview/webview_java
كوتلين	وينترريسندر/webviewko
نيم	oskca/webview، neroist/webview
Node.js	Winterreisender/webview-nodejs
أودين	thechampagne/webview-odin
باسكال	بيرسنج/fpwebview
بايثون	congzhangzh/webview_python,zserge/webview-python
PHP	0hr/php-عرض الويب
روبي	Maaarcocr/webview_ruby
الصدأ	بوسكوب/عرض الويب
سويفت	jakenvac/SwiftWebview
V	malisipi/mui، ttytm/webview
منعرج	thechampagne/webview-zig

إذا كنت ترغب في إضافة روابط إلى القائمة، فلا تتردد في إرسال طلب سحب أو فتح مشكلة.

توليد الارتباطات

يمكنك إنشاء روابط للمكتبة بنفسك باستخدام واجهة SWIG المضمنة ( webview.i ).

فيما يلي بعض الأمثلة لتبدأ. يتم استخدام أسطر الأوامر بنمط Unix للإيجاز.

mkdir -p build/bindings/{python,csharp,java,ruby}
swig -c++ -python -outdir build/bindings/python -o build/bindings/python/python_wrap.cpp webview.i
swig -c++ -csharp -outdir build/bindings/csharp -o build/bindings/csharp/csharp_wrap.cpp webview.i
swig -c++ -java -outdir build/bindings/java -o build/bindings/java/java_wrap.cpp webview.i
swig -c++ -ruby -outdir build/bindings/ruby -o build/bindings/ruby/ruby_wrap.cpp webview.i

رخصة

يتم توزيع الكود بموجب ترخيص MIT، فلا تتردد في استخدامه في مشاريعك الخاصة أيضًا.