QML Language Server

QML Language Server 은 Qt와 함께 제공되는 도구로, 자주 사용하는 (LSP를 지원하는) 에디터에서 코드를 작성할 수 있도록 도와줍니다. 자세한 내용은 언어 서버 프로토콜을 참조하십시오.

현재 이 도구를 사용하면 편집기에서 다음을 수행할 수 있습니다:

• 코드 자동 완성
• qmllint 경고 표시
• QML 파일의 정의로 이동
• JavaScript 변수 및 QML 객체의 사용 위치 찾기
• JavaScript 변수 및 QML 객체 이름 바꾸기
• QML 파일 포맷하기
• Qt 문서에서 도움말 얻기

지원되는 기능

Linting

QML Language Server 은 열린 QML 파일을 자동으로 린팅하고 편집기에서 바로 경고 또는 오류를 표시할 수 있습니다. 린팅 프로세스에 대한 자세한 내용은 qmllint를, 경고 및 오류를 수정하는 방법은 QML 린트 경고 및 오류를 참조하세요.

서식 지정

QML Language Server 은 편집기 내부에서 전체 파일의 서식을 지정할 수 있습니다. 서식 지정 프로세스에 대한 자세한 내용은 qmlformat을 참조하세요.

정의 찾기

QML Language Server JavaScript 변수, 함수, QML 객체 ID 및 QML 프로퍼티의 정의를 해당 용도로부터 찾을 수 있습니다.

QML Language Server JavaScript 함수, QML 객체 속성 및 QML 객체 인스턴스화에 대한 유형 주석에 사용된 유형의 정의도 찾을 수 있습니다.

사용법 찾기

QML Language Server JavaScript 변수, QML 객체 속성, JavaScript 함수, QML 객체 메서드 및 QML 객체 ID의 사용법을 찾을 수 있습니다.

이름 바꾸기

QML Language Server 은 QML 파일에 정의되어 있는 한 JavaScript 변수와 함수, QML 객체 속성, 메서드 및 ID의 이름을 바꿀 수 있습니다.

자동 완성 항목 제안하기

QML Language Server 은 JavaScript 변수, 표현식, 문은 물론 QML 객체 속성, 메서드, ID에 대한 자동 완성 제안을 제공합니다.

C++ 파일의 변경 사항 추적

QML Language Server 는 QML 유형을 정의하는 C++ 파일의 변경 사항을 추적할 수 있습니다. 이 기능은 CMake QML 모듈을 자동으로 리빌드하여 C++로 정의된 QML 유형에 대한 정확한 최신 경고 및 완료 항목을 제공합니다.

이 기능은 비활성화할 수 있습니다.

문서 힌트

QML Language Server 에는 프로그래머가 키워드 위로 마우스를 가져가면 Qt의 문서에 빠르게 액세스할 수 있는 문서 힌트 기능이 포함되어 있습니다. 이 기능을 사용하려면 Qt 키트에 Qt 문서가 포함되어 있어야 하고 프로젝트가 QT_QML_GENERATE_QMLLS_INI 변수를 사용하여 빌드되어야 합니다.

에디터에서 QML Language Server 설정하기

이 섹션에서는 QML Language Server 클라이언트를 개발하는 방법 또는 자체 QML Language Server 클라이언트를 사용하는 방법을 설명합니다.

QML Language Server 바이너리는 Qt Online Installer 로 만든 Qt 설치에서 <Qt installation folder>/bin/qmlls 에서 찾을 수 있습니다. QML Language Server 클라이언트가 직접 바이너리를 다운로드하도록 하려면 https://github.com/TheQtCompanyRnD/qmlls-workflow/releases 또는 https://qtccache.qt.io/QMLLS/LatestRelease 을 통해 github에서 독립 실행형 버전을 다운로드할 수 있습니다.

빌드 디렉토리 설정

QML Language Server 는 프로젝트 빌드 폴더의 위치를 알아야 합니다. 다음과 같은 방법으로 빌드 폴더를 전달할 수 있습니다.

AddBuildDirs LSP 확장자 사용

LSP 확장을 통해 빌드 디렉터리를 전달하려면 $/addBuildDirs 방법의 경우 QML Language Server 으로 알림을 보내세요. $/addBuildDirs 은 하나의 매개변수 형식을 허용합니다:

interface AddBuildDirsParams {
    buildDirsToSet: UriToBuildDirs[];
}

여기서 UriToBuildDirs 에는 작업 영역 URI와 빌드 디렉터리 목록이 포함됩니다. 작업 영역 URI는 workspaceFolders 또는 didChangeWorkspaceFolders를 통해 QML Language Server 에 알린 작업 영역을 지정해야 합니다. 빌드 디렉터리는 URI가 아닌 파일 경로입니다.

interface UriToBuildDirs {
    baseUri: URI;
    buildDirs: string[];
}

-build-dir 명령줄 옵션

여러 워크스페이스를 지원할 필요가 없는 경우 --build-dir 명령줄 옵션을 통해 빌드 디렉터리를 전달할 수 있습니다. 이 경우 에디터는 다음과 같이 qmlls 을 호출해야 합니다:

<path/to/qmlls> ... --build-dir <path/to/build-directory> ...

동일한 QML Language Server 에서 여러 워크스페이스를 사용하는 경우 빌드 디렉터리가 모든 워크스페이스에 적용됩니다. addBuildDirsMethod 의 값은 명령줄 옵션보다 우선순위가 높습니다.

QMLLS_BUILD_DIRS 환경 변수

QMLLS_BUILD_DIRS 환경 변수를 통해 빌드 디렉터리를 전달할 수도 있습니다. 동일한 QML Language Server 에서 여러 워크스페이스를 사용하는 경우 빌드 디렉터리는 모든 워크스페이스에 적용됩니다. --build-dir 의 값은 환경 변수보다 우선순위가 높습니다.

.qmlls.ini 설정 파일

이전 옵션 중 하나를 사용하여 빌드 디렉터리를 전달할 수 없는 경우 구성 파일을 통해 QML Language Server 에 빌드 디렉터리를 전달해 볼 수 있습니다. 설정 파일도 참조하세요. 설정 파일의 값은 --build-dir, QMLLS_BUILD_DIRS, addBuildDirsMethod 보다 우선 순위가 낮습니다.

자동 CMake 빌드 구성

QML Language Server 는 C++로 정의된 QML 유형의 소스 코드가 수정된 것을 감지하면 CMake 리빌드를 트리거하려고 시도합니다.

이 기능을 비활성화하려면 다음 방법을 사용하세요:

• --no-cmake-calls 명령줄 옵션. 이 경우 편집기에서 다음과 같이 qmlls 을 호출해야 합니다:

  <path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls

• QMLLS_NO_CMAKE_CALLS 환경 변수.
• .qmlls.ini 설정 파일( 구성 파일 참조).
• QT_QML_GENERATE_QMLLS_INI가 활성화된 경우 QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS CMake 변수.

CMake에서 사용하는 작업 수를 제어하려면 다음을 사용합니다.

• --cmake-jobs 명령줄 옵션을 사용합니다. 이 경우 편집기는 다음과 같이 qmlls 을 호출해야 합니다:

  <path/to/qmlls> --build-dir <path/to/build-directory> --cmake-jobs <jobs>

• QMLLS_CMAKE_JOBS 환경 변수.
• .qmlls.ini 설정 파일은 구성 파일을 참조하십시오.

허용되는 값은 0보다 큰 정수와 사용 가능한 모든 코어를 사용하려면 max 입니다.

검색할 최대 파일 수 수정하기

QML Language Server 는 소스 폴더에서 헤더를 검색할 때(예: C++ 헤더에 정의된 QML 컴포넌트의 정의로 이동할 때) 검색할 파일 수 제한을 준수합니다.

검색할 최대 파일 수를 설정하려면 QMLLS_MAX_FILES_TO_SEARCH 환경 변수에 숫자 값을 입력합니다. 0은 파일 검색 기능을 비활성화하고 기본값은 20000입니다.

구성 파일

QML Language Server 은 구성 파일 .qmlls.ini 을 통해 구성할 수 있습니다. 이 파일은 프로젝트의 루트 소스 디렉토리에 있어야 합니다. ini-형식의 텍스트 파일이어야 합니다.

구성 파일에는 다음과 같은 항목을 포함할 수 있습니다:

// .qmlls.ini
[General]
no-cmake-calls=<true-or-false>
CMakeJobs=<some integer value>

buildDir=<path/to/build-directory> # not required in Qt 6.10 and later
docDir=<path/to/qt-documentation>  # not required in Qt 6.10 and later
importPaths=<path/to/imports>      # not required in Qt 6.10 and later

구성 파일을 사용하여 자동 CMake 리빌드 기능을 비활성화하려면 no-cmake-calls 을 true 으로 설정합니다.

자동 CMake 리빌드에 사용되는 작업 수를 제어하려면 CMakeJobs 값을 설정합니다.

빌드 디렉터리 설정에 설명된 대로 빌드 디렉터리를 QML Language Server 으로 전달할 수 없는 클라이언트를 지원하려면 buildDir 값을 설정하거나 QT_QML_GENERATE_QMLLS_INI를 통해 CMake가 .qmlls.ini를 생성하도록 합니다.

알려진 제한 사항

QML Language Server 은 많은 일반적인 QML 기능을 다루고 있지만 아직 일부 기능이 지원되지 않는 개발 중입니다:

• 잘못된 QML 파일에 대한 자동 완성 제안.
• C++로 정의된 객체의 정의로 이동하기.
• 컨텍스트 속성 자동 완성

QML Language Server 는 프로젝트에서 오탐 경고를 표시할 수 있습니다.

• QMake 또는 명령형 등록을 사용하는 경우 - QML 모듈을 CMake로 포팅하기 참조.
• 빌드되지 않은 QML 모듈 포팅 -QML Language Server 빌드 정보를 사용하여 QML 모듈을 찾습니다.
• 의 지침을 따르지 않는 QML 모듈을 찾기 위해 빌드 정보를 사용합니다.