이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Blockly API 사용

소개

이 페이지에서는 함수를 호출하고 핵심 Blockly의 속성에 액세스하기 위한 권장사항을 설명합니다. 이러한 원칙은 Blockly용 플러그인을 만들거나 Blockly를 독립형 애플리케이션에 통합하는 데 적용됩니다.

서브클래스화 및 확장

Blockly에는 다음과 같은 기능을 추가하는 여러 패러다임이 있습니다.

서브클래스 (예: 새 렌더기 만들기)
믹스 (예: 차단 확장 프로그램 또는 뮤테이터 추가)
블록 정의 (예: 프러시저 블록 정의)

이 문서의 목적상 세 가지 사례는 모두 서브클래스와 같습니다.

서브클래스 삽입

Blockly.inject 메서드를 통해 특정 클래스 교체를 지원합니다. 이러한 서브클래스는 기본 클래스를 확장하거나 상응하는 인터페이스를 구현해야 합니다.

서브클래스를 삽입 메서드에 전달할 수 있습니다.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

또는 Blockly.registry를 사용하여 클래스를 등록하고 레지스트리 이름을 사용하여 클래스를 삽입할 수 있습니다. 이는 삽입 옵션을 순수 JSON으로 저장하는 경우에 유용합니다.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

다음 클래스는 교체할 수 있습니다.

등록 이름	인터페이스/기본 클래스
`blockDragger`	Blockly.IBlockDragger
`connectionChecker`	Blockly.IConnectionChecker
`connectionPreviewer`	Blockly.IConnectionPreviewer
`flyoutsVerticalToolbox`	Blockly.IFlyout
`flyoutsHorizontalToolbox`	Blockly.IFlyout
`metricsManager`	Blockly.IMetricsManager
`renderer`	Blockly.blockRendering.Renderer
`toolbox`	Blockly.IToolbox

인터페이스 사용에 관한 자세한 내용은 문서의 인터페이스 섹션을 참고하세요.

공개 상태

TypeScript 액세스 수정자를 사용하여 핵심 라이브러리의 공개 상태를 public, private 또는 protected로 표시합니다. 일부 속성은 TsDoc 주석에 @internal로 주석을 달 수 있습니다.

모든 public 및 protected 속성은 Blockly 웹사이트의 참조 섹션에 나와 있습니다. 코드를 읽어 공개 상태를 확인할 수도 있습니다.

공개

public로 표시된 모든 항목은 공개 API의 일부입니다. 공개 상태 수정자가 없는 모듈의 모든 속성은 공개로 간주됩니다.

Google은 합당한 이유와 경고 없이 공개 API를 자주 변경하지 않으려고 합니다. 예외: 한 버전에서 새 API를 공개하고 초기 의견에 따라 다음 버전에서 수정할 수 있습니다. 그 후에는 공개 함수 또는 속성이 안정적인 것으로 간주할 수 있습니다.

공개 함수는 어디서나 호출할 수 있으며 서명이 변경되지 않는 한 서브클래스에서 재정의될 수 있습니다.

protected

보호된 함수 및 속성은 정의하는 클래스 또는 서브클래스에서만 액세스할 수 있습니다.

서브클래스는 유형 서명을 변경하지 않고도 보호된 함수와 속성을 재정의할 수 있습니다.

예를 들어 기본 렌더기 클래스를 확장하는 맞춤 렌더기는 보호된 속성에 액세스할 수 있습니다.

각각의 경우 코드의 나머지 부분에서 함수나 속성이 어떻게 사용되는지 이해해야 합니다.

private

이는 정의와 동일한 파일에 있는 코드를 통해서만 액세스할 수 있습니다. 이러한 속성에 직접 액세스하면 정의되지 않은 동작이 발생할 수 있습니다.

서브클래스는 비공개 함수와 속성을 재정의할 수 없습니다.

비공개 속성은 Blockly의 공개 API의 일부로 간주되지 않으므로 경고 없이 변경될 수 있습니다.

Blockly의 일부 함수에는 공개 상태 주석이 없습니다. 모듈에서 내보내지 않기 때문입니다. 이러한 함수는 본질적으로 로컬 변수이며 정의하는 모듈 외부에서 사용할 수 없습니다. 이들은 사유지와 같은 것으로 간주되어야 합니다.

내부

내부 함수와 속성은 핵심 라이브러리 내에서 사용하기 위한 것이며 외부에서는 사용되지 않습니다. 이러한 태그는 TsDoc @internal 주석으로 지정됩니다.

내부 속성은 Blockly의 공개 API의 일부로 간주되지 않으므로 경고 없이 변경될 수 있습니다.

내부 속성은 코어 내의 어디에서나 액세스할 수 있으며 서명이 변경되지 않는 한 코어의 서브클래스에서 재정의될 수 있습니다. 핵심 라이브러리 외부에서 액세스해서는 안 됩니다.

지원 중단됨

@deprecated로 표시된 항목은 사용해서는 안 됩니다. 대부분의 지원 중단에는 콘솔 경고 또는 TSDoc에 선호 코드에 대한 지침이 포함되어 있습니다.

가능한 경우 지원 중단된 함수는 의도한 삭제 날짜와 대체 함수 호출 권장사항이 포함된 경고를 로깅합니다.

FAQ

사용하려는 함수가 공개가 아닌 경우 어떻게 해야 하나요?

Core Blockly에서 기능 요청을 제출하세요. 사용 사례에 대한 설명과 공개했으면 하는 설명을 포함하세요.

Google은 이 기능을 사용하여 정보를 공개할지 여부 또는 동일한 정보를 얻을 수 있는 다른 방법이 있는지 논의하도록 요청합니다.

공개 상태로 결정되면 귀하 또는 Blockly팀이 적절하게 변경하고, 다음 Blockly 출시에 게시됩니다.

플러그인에서 비공개 멤버를 사용하는 경우 플러그인을 베타로 표시하고 README에 정보를 포함하는 것이 좋습니다.

몽키패칭은 어떨까요?

원숭이 패치에 관해 읽어보세요.

Monkeypatch는 안전하지 않습니다. Blockly API의 비공개 부분을 사용하기 때문에 패치가 예고 없이 작동을 멈출 수 있기 때문입니다. 플러그인에서 패치하는 것은 특히 위험합니다. 코드가 동일한 코드에 monkeypatch를 보내는 다른 플러그인과 제대로 상호작용하지 않을 수 있기 때문입니다. 이러한 이유로 애플리케이션과 서드 파티 플러그인에서는 몽키패치를 적극 권장하며 퍼스트 파티 플러그인에서는 허용하지 않습니다.

공개 함수를 재정의할 수 있나요?

서브클래스로 분류할 때: 예. 그렇지 않으면 원숭이 패치입니다.

보호된 함수를 재정의할 수 있나요?

서브클래스로 분류할 때: 예. 그렇지 않으면 원숭이 패치입니다.

내부 함수 또는 비공개 함수를 재정의할 수 있나요?

아니, 원숭이 패치입니다.

숙박 시설에 직접 액세스할 수 있는 시기는 언제인가요? getter와 setter는 언제 사용해야 하나요?

getter 또는 setter를 게시하는 경우 속성에 직접 액세스하는 대신 사용하세요. 속성이 공개 상태가 아닌 경우 getter와 setter를 사용해야 합니다.

속성에 주석이 없으면 어떻게 되나요?

기본적으로 공개되어 있지만, getter/setter 쌍을 배치하려는 경우에 대비해 한 줄을 드롭하세요.

함수에 주석이 없으면 어떻게 될까요?

기본적으로 공개 상태입니다.

그래도 확실하지 않으면 어떻게 해야 하나요?

포럼에 질문하면 보통 영업일 기준 1일 이내에 답변을 드립니다.