연구 설문조사: Blockly 사용 경험을 알려주세요

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

컨텍스트 메뉴

컨텍스트 메뉴에는 작업 공간, 블록, 작업 공간 댓글과 같은 구성요소에서 사용자가 실행할 수 있는 작업 목록이 포함됩니다. 컨텍스트 메뉴는 터치 기기에서 마우스 오른쪽 버튼 클릭 또는 길게 누르기에 대한 응답으로 표시됩니다. @blockly/keyboard-navigation 플러그인을 사용하는 경우 단축키와 함께 표시되며, 기본값은 Windows의 경우 Ctrl+Enter, Mac의 경우 Command+Enter입니다.

컨텍스트 메뉴는 스크린샷 다운로드와 같이 사용자가 자주 실행하지 않는 작업을 추가하기에 적합합니다. 작업이 더 일반적으로 사용될 것이라고 생각되면 더 쉽게 찾을 수 있는 방법으로 호출하는 것이 좋습니다.

컨텍스트 메뉴는 작업공간, 블록, 작업공간 댓글, 풍선, 연결에서 지원됩니다. 자체 맞춤 구성요소에 구현할 수도 있습니다. Blockly는 맞춤설정할 수 있는 표준 컨텍스트 메뉴를 제공합니다. 작업공간 및 블록의 컨텍스트 메뉴를 작업공간별 또는 블록별로 맞춤설정할 수도 있습니다.

컨텍스트 메뉴 작동 방식

Blockly에는 가능한 모든 메뉴 항목의 템플릿이 포함된 레지스트리가 있습니다. 각 템플릿은 컨텍스트 메뉴에서 단일 항목을 구성하는 방법을 설명합니다. 사용자가 구성요소에서 컨텍스트 메뉴를 호출하면 구성요소는 다음을 충족해야 합니다.

레지스트리에 구성요소에 적용되는 메뉴 항목 배열을 구성하도록 요청합니다. 레지스트리는 각 템플릿에 구성요소에 적용되는지 묻고, 적용되는 경우 해당 메뉴 항목을 배열에 추가합니다.
구성요소가 작업공간 또는 블록인 경우 메뉴가 호출된 특정 작업공간 또는 블록에 컨텍스트 메뉴를 맞춤설정하는 기능이 있는지 확인합니다. 이 경우 배열을 함수에 전달하여 배열의 요소를 추가, 삭제 또는 수정할 수 있습니다.
컨텍스트 메뉴 항목의 (수정되었을 수 있는) 배열을 사용하여 컨텍스트 메뉴를 표시합니다.

Blockly는 작업공간, 블록, 작업공간 주석의 컨텍스트 메뉴에 대한 표준 템플릿 집합을 정의합니다. 작업 공간 및 블록의 템플릿을 레지스트리에 미리 로드합니다. 워크스페이스 댓글 템플릿을 사용하려면 레지스트리에 직접 로드해야 합니다.

레지스트리에서 템플릿을 추가, 삭제, 수정하는 방법에 대한 자세한 내용은 레지스트리 맞춤설정을 참고하세요.

범위

컨텍스트 메뉴는 작업공간, 작업공간 댓글, 연결, 블록, 풍선, 자체 맞춤 구성요소 등 다양한 유형의 구성요소에 의해 구현됩니다. 이러한 각 구성요소 유형의 컨텍스트 메뉴에는 서로 다른 항목이 포함될 수 있으며 항목은 구성요소 유형에 따라 다르게 동작할 수 있습니다. 따라서 컨텍스트 메뉴 시스템은 컨텍스트 메뉴가 호출된 구성요소를 알아야 합니다.

이 문제를 해결하기 위해 레지스트리에서는 Scope 객체를 사용합니다. 컨텍스트 메뉴가 호출된 구성요소는 IFocusableNode를 구현하는 객체로 focusedNode 속성에 저장됩니다. (IFocusableNode는 사용자가 포커스를 둘 수 있는 모든 구성요소에 의해 구현됩니다. 여기에는 컨텍스트 메뉴를 구현하는 구성요소도 포함됩니다. 자세한 내용은 포커스 시스템을 참고하세요.)

Scope 객체는 템플릿의 여러 함수에 전달됩니다. Scope 객체를 가져오는 함수에서 focusedNode 속성의 객체 유형에 따라 수행할 작업을 결정할 수 있습니다. 예를 들어 다음과 같이 구성요소가 블록인지 확인할 수 있습니다.

if (scope.focusedNode instanceof Blockly.BlockSvg) {
  // do something with the block
}

Scope 객체에는 더 이상 사용이 권장되지 않지만 여전히 설정할 수 있는 다른 선택적 속성이 있습니다.

block은 메뉴가 표시된 구성요소가 BlockSvg인 경우에만 설정됩니다.
workspace은 구성요소가 WorkspaceSvg인 경우에만 설정됩니다.
comment은 구성요소가 RenderedWorkspaceComment인 경우에만 설정됩니다.

이러한 속성은 컨텍스트 메뉴가 있을 수 있는 모든 유형의 구성요소를 다루지 않으므로 focusedNode 속성을 사용하는 것이 좋습니다.

RegistryItem 유형

템플릿의 유형은 ContextMenuRegistry.RegistryItem이며 다음 속성이 포함됩니다. preconditionFn, displayText, callback 속성은 separator 속성과 상호 배타적입니다.

ID

id 속성은 컨텍스트 메뉴 항목이 수행하는 작업을 나타내는 고유한 문자열이어야 합니다.

const collapseTemplate = {
  id: 'collapseBlock',
  // ...
};

전제 조건 함수

preconditionFn를 사용하여 컨텍스트 메뉴 항목이 표시되는 시기와 방법을 제한할 수 있습니다.

'enabled', 'disabled' 또는 'hidden' 문자열 중 하나를 반환해야 합니다.

값	설명	이미지
사용 설정됨	상품이 활성 상태임을 나타냅니다.
사용 중지됨	상품이 활성 상태가 아님을 보여줍니다.
히든	항목을 숨깁니다.

preconditionFn에는 Scope도 전달됩니다. 이를 사용하여 메뉴가 열린 구성요소의 유형과 해당 구성요소의 상태를 확인할 수 있습니다.

예를 들어 블록에만 항목이 표시되고 해당 블록이 특정 상태에 있을 때만 표시되도록 할 수 있습니다.

const collapseTemplate = {
  // ...
  preconditionFn: (scope) => {
    if (scope.focusedNode instanceof Blockly.BlockSvg) {
      if (!scope.focusedNode.isCollapsed()) {
        // The component is a block and it is not already collapsed
        return 'enabled';
      } else {
        // The block is already collapsed
        return 'disabled';
      }
    }
    // The component is not a block
    return 'hidden';
  },
  // ...
}

표시 텍스트

displayText는 메뉴 항목의 일부로 사용자에게 표시되어야 합니다. 표시 텍스트는 문자열, HTML 또는 문자열이나 HTML을 반환하는 함수일 수 있습니다.

const collapseTemplate = {
  // ...
  displayText: 'Collapse block',
  // ...
};

Blockly.Msg의 번역을 표시하려면 함수를 사용해야 합니다. 값을 직접 할당하려고 하면 메시지가 로드되지 않고 대신 undefined 값이 표시될 수 있습니다.

const collapseTemplate = {
  // ...
  displayText: () => Blockly.Msg['MY_COLLAPSE_BLOCK_TEXT'],
  // ...
};

함수를 사용하는 경우 Scope 값도 전달됩니다. 이를 사용하여 요소에 관한 정보를 표시 텍스트에 추가할 수 있습니다.

const collapseTemplate = {
  // ...
  displayText: (scope) => {
    if (scope.focusedNode instanceof Blockly.Block) {
      return `Collapse ${scope.focusedNode.type} block`;
    }
    // Shouldn't be possible, as our preconditionFn only shows this item for blocks
    return '';
  },
  // ...
}

무게

weight는 컨텍스트 메뉴 항목이 표시되는 순서를 결정합니다. 긍정적인 값이 클수록 목록에서 아래에 표시됩니다. (가중치가 높은 항목은 '무거워서' 아래로 가라앉는다고 생각하면 됩니다.)

const collapseTemplate = {
  // ...
  weight: 10,
  // ...
}

기본 제공 컨텍스트 메뉴 항목의 가중치는 1부터 시작하여 1씩 증가하는 순서로 지정됩니다.

콜백 함수

callback 속성은 컨텍스트 메뉴 항목의 작업을 실행하는 함수입니다. 여러 매개변수가 전달됩니다.

scope: 메뉴가 열린 구성요소를 참조하는 Scope 객체입니다.
menuOpenEvent: 컨텍스트 메뉴를 여는 트리거가 된 Event입니다. 이는 사용자가 메뉴를 연 방식에 따라 PointerEvent 또는 KeyboardEvent일 수 있습니다.
menuSelectEvent: 메뉴에서 이 특정 컨텍스트 메뉴 항목을 선택한 Event입니다. 사용자가 항목을 선택한 방법에 따라 PointerEvent 또는 KeyboardEvent일 수 있습니다.
location: 메뉴가 열린 픽셀 좌표의 Coordinate입니다. 이를 통해 클릭 위치에 새 블록을 만드는 등의 작업을 할 수 있습니다.

const collapseTemplate = {
  // ...
  callback: (scope, menuOpenEvent, menuSelectEvent, location) => {
    if (scope.focusedNode instanceof Blockly.BlockSvg) {
      scope.focusedNode.collapse();
    }
  },
}

scope를 사용하여 열린 구성요소에 따라 다르게 작동하는 템플릿을 설계할 수 있습니다.

const collapseTemplate = {
  // ...
  callback: (scope) => {
    if (scope.focusedNode instance of Blockly.BlockSvg) {
      // On a block, collapse just the block.
      const block = scope.focusedNode;
      block.collapse();
    } else if (scope.focusedNode instanceof Blockly.WorkspaceSvg) {
      // On a workspace, collapse all the blocks.
      let workspace = scope.focusedNode;
      collapseAllBlocks(workspace);
    }
  }
}

구분자

separator 속성은 컨텍스트 메뉴에 선을 그립니다.

separator 속성이 있는 템플릿에는 preconditionFn, displayText 또는 callback 속성이 있을 수 없으며 scopeType 속성으로만 범위를 지정할 수 있습니다. 후자의 제한사항은 작업공간, 블록, 작업공간 댓글의 컨텍스트 메뉴에서만 사용할 수 있음을 의미합니다.

const separatorAfterCollapseBlockTemplate = {
  id: 'separatorAfterCollapseBlock',
  scopeType: Blockly.ContextMenuRegistry.ScopeType.BLOCK,
  weight: 11, // Between the weights of the two items you want to separate.
  separator: true,
};

컨텍스트 메뉴의 각 구분선에 대해 다른 템플릿이 필요합니다. weight 속성을 사용하여 각 구분 기호를 배치합니다.

범위 유형

scopeType 속성은 지원 중단됩니다. 이전에는 블록, 작업공간 댓글 또는 작업공간의 컨텍스트 메뉴에 메뉴 항목을 표시해야 하는지 확인하는 데 사용되었습니다. 컨텍스트 메뉴는 다른 구성요소에서 열 수 있으므로 scopeType 속성은 너무 제한적입니다. 대신 preconditionFn를 사용하여 해당 구성요소의 옵션을 표시하거나 숨겨야 합니다.

scopeType를 사용하는 기존 컨텍스트 메뉴 템플릿이 있는 경우 Blockly는 적절한 구성요소에 대해서만 항목을 계속 표시합니다.

const collapseTemplate = {
  // ...
  scopeType: Blockly.ContextMenuRegistry.ScopeType.BLOCK,
  // ...
};

레지스트리 맞춤설정

레지스트리에서 템플릿을 추가, 삭제 또는 수정할 수 있습니다. 기본 템플릿은 contextmenu_items.ts에서 확인할 수 있습니다.

템플릿 추가

템플릿을 등록하여 레지스트리에 추가할 수 있습니다. 페이지 로드 시 한 번 실행해야 합니다. 작업공간을 삽입하기 전이나 후에 발생할 수 있습니다.

const collapseTemplate = { /* properties from above */ };
Blockly.ContextMenuRegistry.registry.register(collapseTemplate);

템플릿 삭제

ID로 등록 해제하여 레지스트리에서 템플릿을 삭제할 수 있습니다.

Blockly.ContextMenuRegistry.registry.unregister('someID');

템플릿 수정

레지스트리에서 템플릿을 가져온 다음 인플레이스로 수정하여 기존 템플릿을 수정할 수 있습니다.

const template = Blockly.ContextMenuRegistry.registry.getItem('someID');
template?.displayText = 'some other display text';

차단 컨텍스트 메뉴 사용 중지

기본적으로 블록에는 사용자가 블록 댓글을 추가하거나 블록을 복제하는 등의 작업을 할 수 있는 컨텍스트 메뉴가 있습니다.

다음과 같이 하면 개별 블록의 컨텍스트 메뉴를 사용 중지할 수 있습니다.

block.contextMenu = false;

블록 유형의 JSON 정의에서 enableContextMenu 키를 사용합니다.

{
  // ...,
  "enableContextMenu": false,
}

블록 유형 또는 작업공간별로 컨텍스트 메뉴 맞춤설정

Blockly가 컨텍스트 메뉴 항목 배열을 생성한 후 개별 블록이나 작업 영역에 맞게 맞춤설정할 수 있습니다. 이렇게 하려면 BlockSvg.customContextMenu 또는 WorkspaceSvg.configureContextMenu을 배열을 제자리에서 수정하는 함수로 설정합니다.

블록에 전달된 배열의 객체는 ContextMenuOption 유형이거나 LegacyContextMenuOption 인터페이스를 구현합니다. 작업공간에 전달된 객체의 유형은 ContextMenuOption입니다. Blockly는 이러한 객체에서 다음 속성을 사용합니다.

text: 표시 텍스트입니다.
enabled: false인 경우 회색 텍스트로 항목을 표시합니다.
callback: 항목을 클릭할 때 호출할 함수입니다.
separator: 항목이 구분 기호입니다. 다른 세 속성과 상호 배타적입니다.

속성 유형 및 함수 서명에 관한 참조 문서를 참고하세요.

예를 들어 다음은 작업공간의 컨텍스트 메뉴에 Hello, World! 항목을 추가하는 함수입니다.

workspace.configureContextMenu = function (menuOptions, e) {
  const item = {
    text: 'Hello, World!',
    enabled: true,
    callback: function () {
      alert('Hello, World!');
    },
  };
  // Add the item to the end of the context menu.
  menuOptions.push(item);
}

맞춤 객체에 컨텍스트 메뉴 표시

다음 단계에 따라 맞춤 구성요소에 컨텍스트 메뉴가 표시되도록 할 수 있습니다.

IFocusableNode를 구현하거나 IFocusableNode를 구현하는 클래스를 확장합니다. 이 인터페이스는 컨텍스트 메뉴 시스템에서 구성요소를 식별하는 데 사용됩니다. 또한 사용자가 키보드 탐색 플러그인을 사용하여 구성요소로 이동할 수 있습니다.

showContextMenu 함수가 포함된 IContextMenu을 구현합니다. 이 함수는 레지스트리에서 컨텍스트 메뉴 항목을 가져오고, 메뉴를 표시할 화면의 위치를 계산하고, 표시할 항목이 있으면 메뉴를 표시합니다.

const MyBubble implements IFocusableNode, IContextMenu {
  ...
  showContextMenu(menuOpenEvent) {
    // Get the items from the context menu registry
    const scope = {focusedNode: this};
    const items = Blockly.ContextMenuRegistry.registry.getContextMenuOptions(scope, menuOpenEvent);

    // Return early if there are no items available
    if (!items.length) return;

    // Show the menu at the same location on screen as this component
    // The location is in pixel coordinates, so translate from workspace coordinates
    const location = Blockly.utils.svgMath.wsToScreenCoordinates(new Coordinate(this.x, this.y));

    // Show the context menu
    Blockly.ContextMenu.show(menuOpenEvent, items, this.workspace.RTL, this.workspace, location);
  }
}

사용자가 구성요소를 마우스 오른쪽 버튼으로 클릭할 때 showContextMenu를 호출하는 이벤트 핸들러를 추가합니다. 키보드 탐색 플러그인은 사용자가 Ctrl+Enter(Windows) 또는 Command+Enter (Mac)를 누를 때 showContextMenu를 호출하는 이벤트 핸들러를 제공합니다.
컨텍스트 메뉴 항목의 레지스트리에 템플릿을 추가합니다.