Google 편집기 인터페이스 빌드

Google Workspace 부가기능을 사용하면 편집기 내에서 Google Docs, Sheets, Slides를 비롯한 맞춤설정된 인터페이스를 제공할 수 있습니다. 이를 통해 사용자에게 관련 정보를 제공하고, 작업을 자동화하고, 타사 시스템을 편집기에 연결할 수 있습니다.

부가기능 UI에 액세스

Docs, Sheets, Slides 사용자 인터페이스 오른쪽에 있는 Google Workspace 빠른 액세스 측면 패널에 아이콘이 표시되면 편집기에서 Google Workspace 부가기능을 열 수 있습니다.

Google Workspace 부가기능은 다음 인터페이스를 표시할 수 있습니다.

  • 홈페이지 인터페이스: 부가기능의 매니페스트에 편집기의 트리거 EDITOR_NAME.homepageTrigger가 포함된 경우 사용자가 부가기능을 열면 부가기능이 빌드하여 해당 에디터 전용 홈페이지 카드를 반환합니다. 부가기능의 매니페스트에 사용자가 부가기능을 여는 편집기의 EDITOR_NAME.homepageTrigger가 포함되어 있지 않으면 대신 일반 홈페이지 카드가 표시됩니다.

  • REST API 인터페이스: 부가기능에서 REST API를 사용하는 경우 drive.file 범위를 사용하여 문서에 대한 파일별 액세스를 요청하는 트리거를 포함할 수 있습니다. 부여되면 EDITOR_NAME.onFileScopeGrantedTrigger라는 또 다른 트리거가 실행되고 파일과 관련된 인터페이스를 표시합니다.

  • 미리보기 인터페이스 연결: 부가기능이 서드 파티 서비스와 통합되는 경우 서비스 URL의 콘텐츠를 미리 보는 카드를 빌드할 수 있습니다.

편집기 부가기능용 인터페이스 빌드

다음 단계에 따라 편집기용 편집기 부가기능 인터페이스를 빌드합니다.

  1. 부가기능 스크립트 프로젝트 매니페스트에 적절한 addOns.common, addOns.docs, addOns.sheets, addOns.slides 필드를 추가합니다.
  2. 필요한 편집기 범위를 스크립트 프로젝트 매니페스트에 추가합니다.
  3. 에디터별 홈페이지를 제공하는 경우 EDITOR_NAME.homepageTrigger 함수를 구현하여 인터페이스를 빌드합니다. 그렇지 않은 경우 common.homepageTrigger 인터페이스를 사용하여 호스트 앱의 공통 홈페이지를 빌드합니다.
  4. REST API를 사용하는 경우 drive.file 범위 승인 흐름과 EDITOR_NAME.onFileScopeGrantedTrigger 트리거 함수를 구현하여 열려 있는 파일과 관련된 인터페이스를 표시합니다. 자세한 내용은 REST API 인터페이스를 참조하세요.
  5. 서드 파티 서비스에서 링크 미리보기를 구성하는 경우 https://www.googleapis.com/auth/workspace.linkpreview 범위 승인 흐름과 linkPreviewTriggers 함수를 구현합니다. 자세한 내용은 링크 미리보기 인터페이스를 참고하세요.
  6. 버튼 클릭과 같은 사용자의 UI 상호작용에 응답하는 데 필요한 연결된 콜백 함수를 구현합니다.

편집기 홈페이지

부가기능의 스크립트 프로젝트에 부가기능의 홈페이지를 구성하는 단일 Card 또는 Card 객체의 배열을 빌드하고 반환하는 홈페이지 트리거 함수를 제공해야 합니다.

홈페이지 트리거 함수에는 클라이언트의 플랫폼과 같은 정보가 포함된 매개변수로 이벤트 객체가 전달됩니다. 이벤트 객체 데이터를 사용하여 홈페이지 구성을 조정할 수 있습니다.

일반적인 홈페이지나 사용자가 부가기능을 여는 편집기와 관련된 홈페이지를 표시할 수 있습니다.

공통 홈페이지 표시

편집기에 부가기능의 일반 홈페이지를 표시하려면 addOns.docs, addOns.sheets 또는 addOns.slides와 같은 적절한 편집기 필드를 부가기능의 매니페스트에 포함합니다.

다음 예에서는 Google Workspace 부가기능 매니페스트의 addons 부분을 보여줍니다. 이 부가기능은 Docs, Sheets, Slides를 확장하고 각 호스트 앱의 일반적인 홈페이지를 표시합니다.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

편집자별 홈페이지 표시

편집자와 관련된 홈페이지를 표시하려면 부가기능 매니페스트에 EDITOR_NAME.homepageTrigger를 추가합니다.

다음 예는 Google Workspace 부가기능 매니페스트의 addons 부분을 보여줍니다. Docs, Sheets, Slides에 부가기능이 사용 설정되어 있습니다. Docs 및 Slides에서는 공통 홈페이지, Sheets에는 고유한 홈페이지가 표시됩니다. 콜백 함수 onSheetsHomepage는 Sheets 전용 홈페이지 카드를 빌드합니다.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

REST API 인터페이스

부가기능에서 Google Sheets API와 같은 REST API를 사용하는 경우 onFileScopeGrantedTrigger 함수를 사용하여 편집기 호스트 앱에 열려 있는 파일과 관련된 새 인터페이스를 표시할 수 있습니다.

onFileScopeGrantedTrigger 함수를 사용하려면 drive.file 범위 승인 흐름을 포함해야 합니다. drive.file 범위를 요청하는 방법을 알아보려면 현재 문서의 파일 액세스 요청을 참고하세요.

사용자가 drive.file 범위를 부여하면 EDITOR_NAME.onFileScopeGrantedTrigger.runFunction가 실행됩니다. 트리거가 실행되면 부가기능 매니페스트의 EDITOR_NAME.onFileScopeGrantedTrigger.runFunction 필드에 지정된 컨텍스트 트리거 함수가 실행됩니다.

편집기 중 하나에 사용할 REST API 인터페이스를 만들려면 아래 단계를 따르세요. EDITOR_NAME를 사용하려는 편집기 호스트 앱으로 바꿉니다(예: sheets.onFileScopeGrantedTrigger).

  1. 매니페스트의 해당 편집기 섹션에 EDITOR_NAME.onFileScopeGrantedTrigger를 포함합니다. 예를 들어 Google Sheets에서 이 인터페이스를 만들려면 트리거를 "sheets" 섹션에 추가합니다.
  2. EDITOR_NAME.onFileScopeGrantedTrigger 섹션에 이름이 지정된 함수를 구현합니다. 이 함수는 이벤트 객체를 인수로 허용하며 단일 Card 객체 또는 Card 객체의 배열을 반환해야 합니다.
  3. 다른 카드에서와 마찬가지로 인터페이스에 위젯 상호작용을 제공하는 데 사용되는 콜백 함수를 구현해야 합니다. 예를 들어 인터페이스에 버튼을 포함하는 경우 연결된 Action과 버튼을 클릭할 때 실행되는 구현된 콜백 함수가 있어야 합니다.

다음 예는 Google Workspace 부가기능 매니페스트의 addons 부분을 보여줍니다. 이 부가기능은 REST API를 사용하므로 onFileScopeGrantedTrigger는 Google Sheets에 포함됩니다. 사용자가 drive.file 범위를 부여하면 콜백 함수 onFileScopeGrantedSheets가 파일별 인터페이스를 빌드합니다.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

서드 파티 서비스의 링크 미리보기를 사용 설정하려면 부가기능의 매니페스트에서 링크 미리보기를 구성하고 미리보기 카드를 반환하는 함수를 만들어야 합니다. 사용자 승인이 필요한 서비스의 경우 함수는 승인 흐름도 호출해야 합니다.

링크 미리보기를 사용 설정하는 단계는 스마트 칩으로 링크 미리보기를 참고하세요.

이벤트 객체

EDITOR_NAME.homepageTrigger 또는 EDITOR_NAME.onFileScopeGrantedTrigger와 같은 함수를 트리거하기 위해 이벤트 객체가 생성되고 전달됩니다. 트리거 함수는 이벤트 객체의 정보를 사용하여 부가기능 카드를 구성하는 방법 또는 부가기능 동작을 제어하는 방법을 결정합니다.

이벤트 객체의 전체 구조는 이벤트 객체에 설명되어 있습니다.

편집자가 부가기능의 호스트 앱인 경우 이벤트 객체에는 클라이언트 정보를 전달하는 Docs, Sheets 또는 Slides 이벤트 객체 필드가 포함됩니다.

부가기능에 현재 사용자 또는 문서에 대한 drive.file 범위 승인이 없는 경우 이벤트 객체에는 docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission 또는 slides.addonHasFileScopePermission 필드만 포함됩니다. 부가기능에 승인이 있으면 이벤트 객체에 모든 편집기 이벤트 객체 필드가 포함됩니다.

다음 예는 sheets.onFileScopeGrantedTrigger 함수에 전달되는 편집기 이벤트 객체를 보여줍니다. 여기서 부가기능에는 현재 문서에 대한 drive.file 범위 승인이 있습니다.

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }