Source Editor
GitLab v19.6요약
Source Editor는 GitLab의 편집 환경을 제공합니다. 사용자가 파일 내용을 편집해야 할 때만 Source Editor를 사용합니다. 작업 중인 페이지가 이미 Source Editor를 불러오고 있다면 Source Editor에 읽기 전용 콘텐츠를 표시하는 것도 유효한 선택입니다.
Source Editor는 GitLab의 편집 환경을 제공합니다. 이 얇은 래퍼는 Monaco 에디터에 필요한 헬퍼와 추상화를 제공하고, 확장 기능을 사용해 Monaco를 확장합니다. 다음을 포함한 여러 GitLab 기능이 이를 사용합니다.
Source Editor를 사용하는 경우#
사용자가 파일 내용을 편집해야 할 때만 Source Editor를 사용합니다.
소스 코드를 표시하기만 하면 된다면 BlobContent 컴포넌트 사용을 고려합니다.
작업 중인 페이지가 이미 Source Editor를 불러오고 있다면 Source Editor에 읽기 전용 콘텐츠를 표시하는 것도 유효한 선택입니다.
Source Editor 사용 방법#
Source Editor는 프레임워크에 독립적이며 Rails와 Vue를 포함한 모든 애플리케이션에서 사용할 수 있습니다.
통합을 돕기 위해 전용 <source-editor> Vue 컴포넌트를 제공하지만,
Source Editor의 통합은 일반적으로 간단합니다.
-
Source Editor를 가져옵니다.
import SourceEditor from '~/editor/source_editor'; -
뷰에 사용할 전역 에디터를 초기화합니다.
const editor = new SourceEditor({ // Editor Options. // The list of all accepted options can be found at // https://microsoft.github.io/monaco-editor/docs.html }); -
에디터 인스턴스를 생성합니다.
editor.createInstance({ // Source Editor configuration options. })
Source Editor 인스턴스는 다음 구성 옵션을 받습니다.
| 옵션 | 필수 여부 | 설명 |
|---|---|---|
el |
true |
HTML Node: 에디터를 렌더링할 요소입니다. |
blobPath |
false |
String: 에디터에 렌더링할 파일 이름입니다. 해당 파일 또는 다른 파일 유형에 사용할 올바른 구문 강조 도구를 식별하는 데 사용합니다. 실제 파일 이름을 알 수 없거나 중요하지 않을 때는 *.js 같은 와일드카드를 사용할 수 있습니다. |
blobContent |
false |
String: 에디터에 렌더링할 초기 콘텐츠입니다. |
extensions |
false |
Array: 이 인스턴스에서 사용할 확장 기능입니다. |
blobGlobalId |
false |
String: 자동으로 생성되는 속성입니다. |
| Editor Options | false |
Object(s): 위 목록 밖의 모든 속성은 이 인스턴스의 Editor Option으로 처리됩니다. 이 필드를 사용해 인스턴스 수준에서 전역 Editor Option을 재정의합니다. 전체 Editor Option 색인을 확인할 수 있습니다. |
blobGlobalId 속성은 이후 릴리스에서 제거될 수 있습니다. blobGlobalId가 필요한 특정 사용 사례가 없다면
표준 blob 속성을 대신 사용합니다.
API#
에디터는 Monaco 에디터가 제공하는 공개 API를 그대로 사용하며, 인스턴스 수준에 다음 함수를 추가로 제공합니다.
| 함수 | 인수 | 설명 |
|---|---|---|
updateModelLanguage |
path: String |
전달한 path의 확장자에 맞게 인스턴스의 구문 강조를 업데이트합니다. 인스턴스 수준에서만 사용할 수 있습니다. |
use |
객체 배열 | 인스턴스에 적용할 확장 기능의 배열입니다. 객체 배열만 받습니다. 확장 기능의 ES6 모듈은 use에 전달하기 전에 뷰나 컴포넌트에서 가져오고 해석해 두어야 합니다. 인스턴스 수준과 전역 에디터(모든 인스턴스) 수준에서 사용할 수 있습니다. |
| Monaco Editor 옵션 | 문서를 참고합니다 | 기본 Monaco 에디터 옵션입니다. |
팁#
-
에디터의 로딩 상태입니다.
로딩 상태는 Source Editor에 내장되어 있어 HTML에서 스피너나 로더가 거의 필요하지 않습니다. 내장 로딩 상태를 활용하려면 에디터를 담을 HTML 요소에
data-editor-loading속성을 설정합니다. 부트스트랩할 때 Source Editor가 로더를 자동으로 표시합니다. -
파일 이름이 바뀌면 구문 강조를 업데이트합니다.
// fileNameEl here is the HTML input element that contains the filename fileNameEl.addEventListener('change', () => { this.editor.updateModelLanguage(fileNameEl.value); }); -
에디터의 콘텐츠를 가져옵니다.
변경될 때마다 에디터에 리스너를 설정할 수도 있지만 금세 비용이 큰 작업이 될 수 있습니다. 대신 필요할 때 에디터의 콘텐츠를 가져옵니다. 예를 들어 폼을 제출할 때 가져옵니다.
form.addEventListener('submit', () => { my_content_variable = this.editor.getValue(); }); -
성능
Source Editor 자체는 매우 가볍지만 여전히 무게를 더하는 Monaco 에디터에 의존합니다. 뷰에 Source Editor를 추가할 때마다 JavaScript 번들의 크기가 크게 늘어나 뷰의 로딩 성능에 영향을 줍니다. 다음 중 하나에 해당하면 에디터를 필요할 때 가져와야 합니다.
- 뷰에 에디터가 필요한지 확실하지 않은 경우
- 에디터가 뷰의 부차적인 요소인 경우
Source Editor를 필요할 때 불러오는 방법은 다른 모듈을 불러오는 것과 같습니다.
someActionFunction() { import(/* webpackChunkName: 'SourceEditor' */ '~/editor/source_editor'). then(({ default: SourceEditor }) => { const editor = new SourceEditor(); ... }); ... }
확장 기능#
Source Editor는 제품 전체에 범용적이고 확장 가능한 편집 도구를 제공하며 특정 그룹에 의존하지 않습니다. Source Editor의 코어는 Create::Editor FE Team이 소유하지만 확장 기능(주요 기능 요소)은 어떤 그룹이든 소유할 수 있습니다. Source Editor 확장 기능의 목표는 에디터의 코어를 얇고 안정적으로 유지하는 것입니다. 필요한 기능은 이 코어에 확장 기능으로 추가할 수 있습니다. 어떤 그룹이든 Source Editor의 변경으로 기능이 깨지거나 재정의될 걱정 없이 새로운 편집 기능을 만들고 소유할 수 있습니다.
확장 기능에서 다른 모듈에 의존할 수 있습니다. 이러한 구성은 필요할 때만 의존성을 가져오게 해 Source Editor 코어의 크기를 억제하는 데 도움이 됩니다.
구조적으로 Source Editor의 전체 구현은 다음 다이어그램으로 나타낼 수 있습니다.
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD;
B[Extension 1]---A[Source Editor]
C[Extension 2]---A[Source Editor]
D[Extension 3]---A[Source Editor]
E[...]---A[Source Editor]
F[Extension N]---A[Source Editor]
A[Source Editor]---Z[Monaco]확장 기능은 JavaScript 객체를 내보내는 ES6 모듈입니다.
import { Position } from 'monaco-editor';
export default {
navigateFileStart() {
this.setPosition(new Position(1, 1));
},
};
확장 기능의 함수에서 this는 현재 Source Editor 인스턴스를 가리킵니다.
this를 사용하면 이 경우의 setPosition() 메서드처럼
인스턴스의 전체 API에 접근할 수 있습니다.
기존 확장 기능 사용#
Source Editor 인스턴스에 확장 기능을 추가하려면 다음 단계가 필요합니다.
import SourceEditor from '~/editor/source_editor';
import MyExtension from '~/my_extension';
const editor = new SourceEditor().createInstance({
...
});
editor.use(MyExtension);
확장 기능 생성#
첫 번째 Source Editor 확장 기능을 만들어 보겠습니다. 확장 기능은
Source Editor의 기능을 확장하는 데 사용하는 기본 Object를 내보내는
ES6 모듈입니다. 테스트로
호출하면 에디터의 콘텐츠를 alert로 출력하는 새 함수를 Source Editor에 추가하는
확장 기능을 만들어 보겠습니다.
~/my_folder/my_fancy_extension.js:
export default {
throwContentAtMe() {
alert(this.getValue());
},
};
코드 예시에서 this는 인스턴스를 가리킵니다. 인스턴스를 참조하면
getValue() 같은 함수를 포함해 기반이 되는
Monaco 에디터 API 전체에
접근할 수 있습니다.
이제 확장 기능을 사용해 보겠습니다.
~/my_folder/component_bundle.js:
import SourceEditor from '~/editor/source_editor';
import MyFancyExtension from './my_fancy_extension';
const editor = new SourceEditor().createInstance({
...
});
editor.use(MyFancyExtension);
...
someButton.addEventListener('click', () => {
editor.throwContentAtMe();
});
먼저 Source Editor와 새 확장 기능을 가져옵니다. 그런 다음
에디터와 그 인스턴스를 생성합니다. 기본적으로 Source Editor에는 throwContentAtMe 메서드가 없습니다.
하지만 editor.use(MyFancyExtension) 줄이 그 메서드를 인스턴스에 추가합니다.
그 후에는 필요할 때 언제든 사용할 수 있습니다. 이 경우에는 가상의
버튼을 클릭했을 때 호출합니다.
이 스크립트는 someButton을 클릭하면 에디터의 콘텐츠가 담긴 알림을 표시합니다.
팁#
-
성능
Source Editor 자체와 마찬가지로 모든 확장 기능은 필요할 때 불러올 수 있으며, 뷰의 로딩 성능을 해치지 않습니다.
const EditorPromise = import( /* webpackChunkName: 'SourceEditor' */ '~/editor/source_editor' ); const MarkdownExtensionPromise = import('~/editor/source_editor_markdown_ext'); Promise.all([EditorPromise, MarkdownExtensionPromise]) .then(([{ default: SourceEditor }, { default: MarkdownExtension }]) => { const editor = new SourceEditor().createInstance({ ... }); editor.use(MarkdownExtension); }); -
여러 확장 기능 사용
확장 기능 배열을
use메서드에 전달하면 됩니다.editor.use([FileTemplateExtension, MyFancyExtension]);