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

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에서 콘텐츠를 미리 볼 수 있는 카드를 빌드할 수 있습니다.

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

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

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

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

다음 예는 Google Workspace 부가기능 매니페스트의 addons 부분을 보여줍니다. 부가기능은 REST API를 사용하므로 Google Sheets용으로 onFileScopeGrantedTrigger가 포함됩니다. 사용자가 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"
          },
          ...
        }