ONLYOFFICE 데스크톱 플러그인 개발 및 디버깅 활성화

ONLYOFFICE 데스크톱 에디터에서는 별도의 플러그인 개발 스위치를 켤 필요가 없습니다. 플러그인을 생성하고 .plugin플러그인 관리자를 통해 패키지를 설치한 다음, 디버깅 도구가 필요할 때 데스크톱 앱을 실행하면 됩니다 --ascdesktop-support-debug-info. 데스크톱 에디터와 웹 에디터는 로딩 절차가 다르므로 아래의 데스크톱 전용 워크플로부터 시작하십시오.

간단한 플러그인 프로젝트를 준비하세요

이 지침은 Windows, macOS 및 Linux용 ONLYOFFICE 데스크톱 편집기에 적용됩니다. 최신 버전의 데스크톱 설치와 일반 텍스트 파일용 코드 편집기를 사용하십시오. 공식 문서에서는 수동 플러그인 설치와 개발자 디버깅을 별개의 기능으로 취급합니다. 로컬 플러그인을 개발하고 테스트하는 데 플러그인 마켓플레이스가 필수적인 것은 아닙니다. "Hello World" 예제는 플러그인 로딩을 더 복잡한 서비스와 분리하여 확인할 수 있으므로 유용한 첫 번째 점검 방법입니다.

1. 소스 폴더를 생성합니다.

`.` 이라는 이름의 폴더를 만드세요 hello-world-plugin. config.json매니페스트 파일과 index.html진입점을 추가하세요. icon.png매니페스트 파일에서 이미지를 참조하는 경우 선택적으로 이미지 파일도 추가하세요. 소프트웨어 업데이트로 인해 작업 파일이 덮어쓰여지지 않도록 해당 폴더는 설치된 애플리케이션 디렉토리 외부에 있어야 합니다.

2. 매니페스트를 정의하고 자체 GUID를 생성합니다.

매니페스트는 ONLYOFFICE에 로드할 HTML 파일과 플러그인을 실행할 수 있는 편집기를 알려줍니다. 다음 예는 문서 편집기를 지원합니다. 설치하기 전에 샘플 GUID를 새로 생성된 UUID로 바꾸십시오. New-GuidWindows PowerShell 또는 uuidgenmacOS/Linux에서 실행한 다음 값을 asc.{YOUR-UUID}. 형식으로 지정하십시오. 각 플러그인에는 고유한 식별자가 필요합니다.

{
  "name": "Hello World",
  "guid": "asc.{12345678-1234-1234-1234-1234567890AB}",
  "version": "1.0.0",
  "variations": [{
    "url": "index.html",
    "icons": ["icon.png"],
    "isViewer": false,
    "EditorsSupport": ["word"]
  }]
}

유효한 JSON 형식을 사용하세요. 끝에 쉼표가 없어야 하고, 중괄호가 일치해야 하며, 참조되는 모든 진입점 또는 아이콘에 대해 실제 파일이 있어야 합니다. 스프레드시트 또는 프레젠테이션 플러그인의 경우, EditorsSupport문서 전용 플러그인이 모든 곳에 나타난다고 가정하지 말고 적절한 값을 사용하세요. 공식 Hello World 빠른 시작 가이드의 구조와 비교해 보세요 .

3. 진입점을 구현합니다.

해당 파일에 index.htmlONLYOFFICE 플러그인 API 라이브러리를 로드하고 버튼을 추가한 다음, 버튼이 해당 함수를 호출하도록 하세요 window.Asc.plugin.executeMethod("PasteText", ["Hello World!"]). 제조사에서 제공하는 빠른 시작 예제 에는 완전한 HTML 코드와 라이브러리 URL이 포함되어 있으므로, 초기화 또는 API 구문을 추측하는 것보다 해당 예제를 복사하는 것이 더 안전합니다. 파일을 UTF-8 형식으로 저장하세요. 오프라인에서 작업할 계획이라면, 온라인 URL에서 플러그인 라이브러리나 기타 자산을 가져오는 페이지는 해당 리소스를 로드해야 한다는 점을 기억하세요.

개발 플러그인을 설치하고 실행하세요.

4. .plugin 아카이브를 빌드합니다.

원본 폴더 안의 파일들을 선택하여 ZIP 파일로 압축한 후, ZIP 파일의 확장자를 .zip에서 로 변경하세요 .plugin. 압축 파일의 루트 디렉터리에는 config.json와 가 포함되어야 하며 index.html, 두 번째 하위 hello-world-plugin디렉터리가 있으면 안 됩니다. Windows에서는 파일 탐색기에서 파일 확장자 표시를 활성화하여 실수로 를 생성하는 것을 방지하세요 hello-world.plugin.zip. 공식 Desktop Editors 설치 지침에서는 마켓플레이스 연결 없이 수동 설치를 명시적으로 지원합니다.

5. 플러그인 관리자에서 패키지를 가져옵니다.

ONLYOFFICE 데스크톱 편집기에서 편집 가능한 문서를 엽니다. 플러그인 > 플러그인 관리자 > 내 플러그인 > 플러그인 수동 설치를 선택합니다 . 관리자의 정확한 화면은 버전에 따라 다를 수 있지만, 이 경로는 수동 설치에 대한 공식적인 방법입니다. 이는 마켓플레이스의 별도 개발자 URL 설정과는 다릅니다.

6. 파일을 선택하고 해당 메뉴 항목을 확인하세요.

파일 대화 상자에서 아카이브를 선택 hello-world.plugin하고 엽니다. 설치된 플러그인이 플러그인 탭에서 사용 가능해집니다. 플러그인이 보이지 않으면 애플리케이션 설정을 변경하기 전에 매니페스트, GUID, 지원되는 편집기 유형 및 아카이브 루트를 확인하십시오. 설치 후 메뉴가 즉시 새로 고쳐지지 않으면 문서를 다시 열어보세요.

7. 임시 문서에서 플러그인을 테스트하십시오.

빈 테스트 문서를 열고 플러그인 탭에서 Hello World 플러그인을 실행한 다음 버튼을 클릭하세요. 문서에 "Hello World!" 라는 문구가 나타나는지 확인하세요. 이는 설치만 확인하는 것이 아니라 플러그인 인터페이스가 제대로 로드되고 편집기 API 호출이 문서에 도달했는지도 확인하는 것입니다. 내용이 변경되는 플러그인은 대체 불가능한 파일에서 테스트하지 마세요.

플러그인 개발을 위한 디버깅을 활성화합니다.

8. 디버그 플래그를 사용하여 데스크톱 편집기를 다시 시작합니다.

ONLYOFFICE Desktop Editors를 완전히 종료한 다음, 공식 디버그 플래그를 사용하여 터미널에서 애플리케이션을 실행하십시오. 운영 체제 및 설치 위치에 따라 다음 명령어를 사용하십시오.

• Windows 명령 프롬프트: "%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info
• 리눅스(표준 패키지 위치): "/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info
• macOS: "/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

위의 Windows 명령은 PowerShell 구문이 아닌 명령 프롬프트 변수 확장을 사용합니다. PowerShell에서는 확인된 전체 경로를 사용하여 실행 파일을 호출해야 합니다. 앱이 표준 위치가 아닌 다른 위치에 설치된 경우 실제 실행 파일 경로를 입력하세요. Windows 바탕 화면 바로 가기의 대상 필드에 플래그를 추가할 수도 있습니다. 플랫폼별 자세한 내용은 ONLYOFFICE의 데스크톱 디버그 모드 명령을 참조하세요 .

문서가 열리면 편집 영역을 클릭하고 F1 키를 누르 거나, 편집 가능한 도구 모음 필드를 마우스 오른쪽 버튼으로 클릭하고 [요소 검사]를 선택합니다 . 개발자 도구에서 플러그인 iframe을 선택하여 플러그인 인터페이스 코드와 로그를 검사합니다. 전달된 코드는 컨텍스트 callCommand내에서 실행 되므로 frameEditor필요에 따라 프레임을 전환해야 합니다. 플러그인 디버깅 참조에서 이러한 차이점과 중단점 사용 방법을 설명합니다. 디버깅을 통해 문서 내용과 런타임 세부 정보가 노출될 수 있으므로, 확인하지 않고는 원시 로그를 공유하지 마십시오.

내장 플러그인을 수정하지 않고 편집-테스트 주기를 단축하세요.

수동 설치 후, ONLYOFFICE는 플러그인을 사용자 프로필 아래의 GUID로 명명된 디렉터리에 복사합니다. 문서화된 위치는 %LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\Windows, ~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/macOS 및 Linux에서 확인할 수 있습니다. GUID로 명명된 폴더는 매니페스트에 사용된 ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/접두사를 생략합니다 .asc.

개발자는 변경 사항마다 새 아카이브를 생성하는 것을 방지하기 위해 앱을 닫고, 설치된 플러그인 폴더를 작업 소스 폴더에 대한 심볼릭 링크로 교체한 다음, 편집 후 문서를 다시 열 수 있습니다. 이 작업은 선택 사항이며, 정확한 링크 명령은 운영 체제에 따라 다릅니다. 작업을 수행하기 전에 공식 데스크톱 개발 지침을 따르 십시오. 번들로 제공되는 기본 플러그인 폴더를 교체하거나 macOS 앱 패키지를 수정하지 마십시오. 공급업체는 기본 플러그인을 제거하면 패키지 무결성이 손상되어 충돌이 발생할 수 있다고 경고합니다.

개발 환경을 확인하십시오

워크플로가 준비되었는지 확인하려면 다음 세 가지 사항을 확인하십시오. 사용자 지정 플러그인이 플러그인 목록 에 나타나고 , Hello World 테스트가 새 문서에 텍스트를 삽입하며, 디버그 플래그를 사용하여 실행했을 때 개발자 도구가 열리는지 확인합니다. 인터페이스가 비어 있거나 설치에 실패하는 경우, 매니페스트가 JSON 형식으로 파싱되는지, GUID가 로 시작하는지 asc., index.html선언된 상대 경로에 존재하는지, 그리고 필요한 모든 리소스가 있는지 확인하십시오. 공식 플러그인 오류 가이드에서 이러한 일반적인 오류에 대해 자세히 설명합니다. 플러그인이 설치되었다고 해서 모든 기능이 제대로 작동하는 것은 아니므로 코드 변경 후에는 동일한 검사를 반복하십시오.