의미론적 강조 표시 가이드

시맨틱 하이라이팅은 구문 하이라이팅 가이드에 설명된 구문 하이라이팅에 대한 추가 기능입니다. Visual Studio Code는 TextMate 문법을 주요 토큰화 엔진으로 사용합니다. TextMate 문법은 단일 파일을 입력으로 받아 정규 표현식으로 표현된 어휘 규칙에 따라 이를 분해합니다.

시맨틱 토큰화는 언어 서버가 프로젝트 컨텍스트에서 기호를 확인하는 방법에 대한 언어 서버의 지식을 기반으로 추가 토큰 정보를 제공할 수 있도록 합니다. 테마는 문법의 구문 하이라이팅을 개선하고 세분화하기 위해 시맨틱 토큰을 사용하도록 선택할 수 있습니다. 편집기는 문법의 하이라이팅 위에 시맨틱 토큰의 하이라이팅을 적용합니다.

시맨틱 하이라이팅이 추가할 수 있는 예시는 다음과 같습니다.

시맨틱 하이라이팅 없음

시맨틱 하이라이팅 적용

언어 서비스 기호 이해에 따른 색상 차이를 확인하세요.

• 10행: languageModes는 매개변수로 색칠됩니다.
• 11행: Range와 Position은 클래스로 색칠되고 document는 매개변수로 색칠됩니다.
• 13행: getFoldingRanges는 함수로 색칠됩니다.

시맨틱 토큰 공급자

시맨틱 하이라이팅을 구현하기 위해 언어 확장은 문서 언어 및/또는 파일 이름을 기준으로 semantic token provider를 등록할 수 있습니다. 시맨틱 토큰이 필요할 때 편집기는 공급자에게 요청합니다.

const tokenTypes = ['class', 'interface', 'enum', 'function', 'variable'];
const tokenModifiers = ['declaration', 'documentation'];
const legend = new vscode.SemanticTokensLegend(tokenTypes, tokenModifiers);

const provider: vscode.DocumentSemanticTokensProvider = {
  provideDocumentSemanticTokens(
    document: vscode.TextDocument
  ): vscode.ProviderResult<vscode.SemanticTokens> {
    // analyze the document and return semantic tokens

    const tokensBuilder = new vscode.SemanticTokensBuilder(legend);
    // on line 1, characters 1-5 are a class declaration
    tokensBuilder.push(
      new vscode.Range(new vscode.Position(1, 1), new vscode.Position(1, 5)),
      'class',
      ['declaration']
    );
    return tokensBuilder.build();
  }
};

const selector = { language: 'java', scheme: 'file' }; // register for all Java documents from the local file system

vscode.languages.registerDocumentSemanticTokensProvider(selector, provider, legend);

시맨틱 토큰 공급자 API는 언어 서버의 기능을 수용하기 위해 두 가지 형태로 제공됩니다.

• DocumentSemanticTokensProvider - 항상 전체 문서를 입력으로 사용합니다.

  • provideDocumentSemanticTokens - 문서의 모든 토큰을 제공합니다.
  • provideDocumentSemanticTokensEdits- 이전 응답에 대한 델타로 문서의 모든 토큰을 제공합니다.

• DocumentRangeSemanticTokensProvider - 범위에 대해서만 작동합니다.

  • provideDocumentRangeSemanticTokens - 문서 범위의 모든 토큰을 제공합니다.

공급자가 반환하는 각 토큰에는 토큰 유형, 임의 개수의 토큰 수정자 및 토큰 언어로 구성된 분류가 포함됩니다.

위의 예에서 볼 수 있듯이 공급자는 사용할 유형과 수정자를 SemanticTokensLegend에서 명명합니다. 이를 통해 provide API는 범례에 대한 인덱스로 토큰 유형과 수정자를 반환할 수 있습니다.

시맨틱 토큰 분류

시맨틱 토큰 공급자의 출력은 토큰으로 구성됩니다. 각 토큰에는 범위와 토큰이 나타내는 구문 요소의 종류를 설명하는 토큰 분류가 있습니다. 선택적으로 분류는 토큰이 포함된 언어의 일부인 경우 언어를 명명할 수도 있습니다.

구문 요소의 종류를 설명하기 위해 시맨틱 토큰 유형과 수정자가 사용됩니다. 이 정보는 구문 하이라이팅 가이드에 설명된 TextMate 범위와 유사하지만, 전용적이고 더 깔끔한 분류 시스템을 만들고 싶었습니다.

VS Code는 모든 시맨틱 토큰 공급자가 사용할 표준 시맨틱 토큰 유형 및 수정자 세트를 제공합니다. 그럼에도 불구하고 시맨틱 토큰 공급자는 새로운 유형과 수정자를 자유롭게 정의하고 표준 유형의 하위 유형을 만들 수 있습니다.

표준 토큰 유형 및 수정자

표준 유형 및 수정자는 여러 언어에서 사용되는 일반적인 개념을 다룹니다. 각 언어는 일부 유형 및 수정자에 대해 다른 용어를 사용할 수 있지만, 표준 분류를 준수함으로써 테마 작성자가 언어 전반에 걸쳐 작동하는 테마 규칙을 정의할 수 있게 됩니다.

다음은 VS Code에서 미리 정의된 표준 시맨틱 토큰 유형 및 시맨틱 토큰 수정자입니다.

표준 토큰 유형

표준 토큰 수정자

표준 유형 및 수정자 외에도 VS Code는 유사한 TextMate 범위에 대한 유형 및 수정자 매핑을 정의합니다. 이는 시맨틱 토큰 범위 맵 섹션에서 다룹니다.

사용자 정의 토큰 유형 및 수정자

필요한 경우 확장은 확장 package.json의 semanticTokenTypes 및 semanticTokenModifiers 기여 지점을 통해 새 유형 및 수정자를 선언하거나 기존 유형의 하위 유형을 만들 수 있습니다.

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "templateType",
        "superType": "type",
        "description": "A template type."
      }
    ],
    "semanticTokenModifiers": [
      {
        "id": "native",
        "description": "Annotates a symbol that is implemented natively"
      }
    ]
  }
}

위의 예에서 확장은 새 유형 templateType과 새 수정자 native를 선언합니다. type을 슈퍼 유형으로 명명함으로써 type에 대한 테마 스타일 규칙은 templateType에도 적용됩니다.

{
  "name": "Red Theme",
  "semanticTokenColors": {
    "type": "#ff0011"
  }
}

semanticTokenColors의 값 "#ff0011"은 type 및 templateType을 포함한 모든 하위 유형에도 적용됩니다.

사용자 정의 토큰 유형과 함께 확장은 이를 TextMate 범위에 매핑하는 방법을 정의할 수 있습니다. 이는 사용자 정의 매핑 섹션에서 설명합니다. 사용자 정의 매핑 규칙은 슈퍼 유형에서 자동으로 상속되지 않습니다. 대신 하위 유형은 매핑을 다시 정의해야 하며, 가급적 더 구체적인 범위로 정의해야 합니다.

시맨틱 하이라이팅 사용

시맨틱 토큰이 계산되고 강조 표시되는지는 editor.semanticHighlighting.enabled 설정에 의해 결정됩니다. 이 설정은 true, false 및 configuredByTheme 값을 가질 수 있습니다.

• true와 false는 모든 테마에 대해 시맨틱 하이라이팅을 켜거나 끕니다.
• configuredByTheme이 기본값이며 각 테마가 시맨틱 하이라이팅을 활성화할지 여부를 제어할 수 있도록 합니다. VS Code와 함께 제공되는 모든 테마(예: 기본 "Dark+")는 기본적으로 시맨틱 하이라이팅이 활성화되어 있습니다.

시맨틱 토큰에 의존하는 언어 확장은 package.json에서 해당 언어에 대한 기본값을 재정의할 수 있습니다.

{
  "configurationDefaults": {
    "[languageId]": {
      "editor.semanticHighlighting.enabled": true
    }
  }
}

테마

테마 지정은 토큰에 색상과 스타일을 할당하는 것입니다. 테마 규칙은 Color Theme 파일(JSON 형식)에 지정됩니다. 사용자는 사용자 설정에서 테마 규칙을 사용자 정의할 수도 있습니다.

Color Themes의 시맨틱 색상 지정

시맨틱 토큰 기반 하이라이팅을 지원하기 위해 Color Theme 파일 형식에 두 개의 새 속성이 추가되었습니다.

semanticHighlighting 속성은 테마가 시맨틱 토큰을 사용하여 하이라이팅할 준비가 되었는지 정의합니다. 기본적으로 false이지만 모든 테마가 이를 활성화하도록 권장합니다. 이 속성은 editor.semanticHighlighting.enabled 설정이 configuredByTheme으로 설정될 때 사용됩니다.

semanticTokenColors 속성을 통해 테마는 시맨틱 토큰 공급자가 발행하는 시맨틱 토큰 유형 및 수정자에 맞춰 새로운 색상 규칙을 정의할 수 있습니다.

{
  "name": "Red Theme",
  "tokenColors": [
    {
      "scope": "comment",
      "settings": {
        "foreground": "#dd0000",
        "fontStyle": "italic"
      }
    }
  ],
  "semanticHighlighting": true,
  "semanticTokenColors": {
    "variable.readonly:java": "#ff0011"
  }
}

variable.readonly:java는 선택자라고 하며, (*|tokenType)(.tokenModifier)*(:tokenLanguage)? 형식을 갖습니다.

값은 규칙이 일치할 경우 스타일을 설명합니다. 전경색을 나타내는 문자열이거나, { foreground: string, bold: boolean, italic: boolean, underline: boolean } 또는 tokenColors의 TextMate 테마 규칙에 사용되는 { foreground: string, fontStyle: string } 형식의 객체입니다.

전경색은 색상 형식에 설명된 색상 형식을 따라야 합니다. 투명도는 지원되지 않습니다.

다른 선택자와 스타일 예시는 다음과 같습니다.

• "*.declaration": { "bold": true } // 모든 선언은 굵게 표시됩니다.
• "class:java": { "foreground": "#0f0", "italic": true } // java의 클래스

규칙이 일치하지 않거나 테마에 semanticTokenColors 섹션이 없는 경우(semanticHighlighting이 활성화된 경우), VS Code는 시맨틱 토큰 범위 맵을 사용하여 주어진 시맨틱 토큰에 대한 TextMate 범위를 평가합니다. 해당 범위는 테마의 TextMate 테마 규칙과 tokenColors에서 일치합니다.

시맨틱 토큰 범위 맵

시맨틱 규칙을 정의하지 않은 테마에서도 시맨틱 하이라이팅이 작동하도록 하고 사용자 정의 토큰 유형 및 수정자에 대한 대체 역할을 하기 위해 VS Code는 시맨틱 토큰 선택자와 TextMate 범위 간의 맵을 유지 관리합니다.

테마에 시맨틱 하이라이팅이 활성화되어 있지만 주어진 시맨틱 토큰에 대한 규칙이 없는 경우, 대신 TextMate 테마 규칙을 찾기 위해 이러한 TextMate 범위가 사용됩니다.

미리 정의된 TextMate 범위 매핑

다음 표는 현재 미리 정의된 매핑을 나열합니다.

사용자 정의 TextMate 범위 매핑

이 맵은 package.json의 semanticTokenScopes 기여 지점을 통해 확장에서 확장할 수 있습니다.

확장이 이를 수행하는 두 가지 사용 사례가 있습니다.

• 사용자 정의 토큰 유형 및 토큰 수정자를 정의하는 확장 기능은 테마에 추가된 시맨틱 토큰 유형 또는 수정자에 대한 테마 규칙이 없는 경우 대체로 TextMate 범위를 제공합니다.

  {
    "contributes": {
      "semanticTokenScopes": [
        {
          "scopes": {
            "templateType": ["entity.name.type.template"]
          }
        }
      ]
    }
  }
  

• TextMate 문법 공급자는 언어별 범위를 설명할 수 있습니다. 이는 언어별 테마 규칙이 포함된 테마에 도움이 됩니다.

  {
    "contributes": {
      "semanticTokenScopes": [
        {
          "language": "typescript",
          "scopes": {
            "property.readonly": ["variable.other.constant.property.ts"]
          }
        }
      ]
    }
  }
  

직접 해보기

시맨틱 토큰 공급자를 만드는 방법을 보여주는 시맨틱 토큰 샘플이 있습니다.

범위 검사기 도구를 사용하면 소스 파일에 있는 시맨틱 토큰과 일치하는 테마 규칙을 탐색할 수 있습니다. 시맨틱 토큰을 보려면 TypeScript 파일에서 기본 제공 테마(예: Dark+)를 사용하십시오.