API 공개 상태

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

공개 상태

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

모든 publicprotected 속성은 Blockly 웹사이트의 참조 섹션에 설명되어 있습니다. 코드를 읽어서 공개 상태를 확인할 수도 있습니다.

공개

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

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

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

protected

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

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

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

각 경우 함수 또는 속성이 나머지 코드에서 사용되는 방식을 이해해야 합니다.

비공개

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

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

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

Blockly의 일부 함수는 모듈에서 내보내지 않으므로 공개 범위 주석이 없습니다. 이러한 함수는 본질적으로 로컬 변수이며 정의 모듈 외부에서 사용할 수 없습니다. 비공개 속성과 동일한 것으로 간주해야 합니다.

내부

내부 함수와 속성은 핵심 라이브러리 내에서 사용하도록 설계되었으며 외부에서는 사용할 수 없습니다. TsDoc @internal 주석으로 지정됩니다.

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

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

지원 중단됨

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

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

FAQ

다음은 Blockly팀에서 자주 접하는 질문입니다.

사용하려는 함수가 공개가 아니면 어떻게 해야 하나요?

핵심 Blockly에서 기능 요청을 제출합니다. 사용 사례에 관한 설명과 공개하고자 하는 내용을 명시하세요.

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

공개하기로 결정되면 개발자 또는 Blockly팀에서 적절하게 변경하고 다음 Blockly 출시에서 적용됩니다.

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

원숭이 패칭은 어떨까요?

문치 패치에 대해 알아보세요.

Monkeypatching은 안전하지 않습니다. Blockly API의 비공개 부분을 사용하면 패치가 예고 없이 작동을 중지할 수 있기 때문입니다. 플러그인에서 패치하는 것은 특히 위험합니다. 코드가 동일한 코드를 원숭이 패치하는 다른 플러그인과 제대로 상호작용하지 않을 수 있기 때문입니다. 따라서 애플리케이션 및 서드 파티 플러그인에서는 몬키패칭을 하지 않는 것이 좋습니다. 퍼스트 파티 플러그인에서는 몬키패칭을 허용하지 않습니다.

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

서브클래스화하는 경우: 예. 그 외의 경우: 아니요. 이는 원숭이 패치입니다.

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

서브클래스화하는 경우: 예. 그 외의 경우: 아니요. 이는 원숭이 패치입니다.

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

아니요. 이는 원숭이 패치입니다.

언제 속성에 직접 액세스할 수 있나요? getter 또는 setter는 언제 사용해야 하나요?

getter 또는 setter를 게시하는 경우 속성에 직접 액세스하는 대신 이를 사용하세요. 속성이 공개가 아닌 경우 반드시 getter와 setter를 사용하세요.

속성에 주석이 없는 경우 어떻게 해야 하나요?

기본적으로 공개이지만 getter/setter 쌍을 설정하려면 문의해 주세요.

함수에 주석이 없는 경우 어떻게 하나요?

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

여전히 확실하지 않은 경우 어떻게 해야 하나요?

포럼에서 질문해 주시면 며칠 이내에 연락드리겠습니다.