GASドキュメント対訳: Serve HTML as a Google Docs, Sheets, or Forms user interface / Scripts Bound to Google Sheets, Docs, or Forms

developersドキュメントの対訳です。

• 用途
  • google apps scriptでウェブアプリケーションを作成する際に、
    • 単独アプリケーションではなく、ファイル(docs,sheets,forms)に固有の(=bound)scriptとして実装する場合
    • ダイアログboxや、サイドバーとしての実装をする場合

Serve HTML as a Google Docs, Sheets, or Forms user interface - google docs, sheets, forms のUIとしてhtmlを吐く

• https://developers.google.com/apps-script/guides/html/?hl=ja#serve_html_as_a_google_docs_sheets_or_forms_user_interface
• の下半分。

The HTML service can display a dialog or sidebar in Google Docs, Sheets, or Forms if your script is container-bound to the file. (In Google Forms, custom user interfaces are only visible to an editor who opens the form to modify it, not to a user who opens the form to respond.)

HTML service は、あなたのscriptが、そのファイルに対して、container固有のものであれば、google docs, sheets, forms において、ダイアログまたは、サイドバーを表示できる。
(forms では、カスタムUIは、回答のためにフォームを見ている人ではなく、フォームの編集モードを開いている編集者にのみ見せれる)

• (補足)container-bound
  • (bound はbindの過去分詞)
  • https://developers.google.com/apps-script/guides/bound?hl=ja#containerBound
    • 下に対訳
  • コンテナとは、sheetsとかdocsとかといった入れ物＝ファイルのこと。
    • つまり、scriptのプロジェクトをdriveで直接管理するのではなく、ファイルに固有のscriptとして作る場合のこと。
  • https://developers.google.com/apps-script/collaborating
    • にもあるので(複数人での開発)、別途対訳予定

Unlike a web app, a script that creates a user interface for a document, spreadsheet, or form does not need a doGet() function specifically, and you do not need to save a version of your script or deploy it. Instead, the function that opens the user interface must pass your HTML file as an HtmlOutput object to the showModalDialog()) or showSidebar() methods of the Ui object for the active document, form, or spreadsheet (if you're using the new version of Sheets), or to the show() method of the active Spreadsheet object (if you're using the older version of Sheets).

webappと違って、docs,sheets,forms のためのUIを作るscriptは、特段doGet()methodは必要とせず、versionを保存する必要はないし、deployする必要もない。
代わりに、UIを開く関数は、HTMLファイルを、HtmlOutput オブジェクトとして、
現在activeなdocument, form, sheetに対して、UI objectのshowModalDialog())または、showSidebar()methodに渡す必要がある。
＊古いspreadsheetを使っている場合は、Spreadsheetオブジェクトのshow()methodに渡す

These examples include a few extra features for convenience: the onOpen() function creates a custom menu that makes it easy to open the interface, and the button in the HTML file invokes a special close() method of the google.script.host API to close the interface.

これらの例は、より便利な追加の機能を含んんでいる。onOpen()関数は、UIを開くのに簡単なカスタムメニューを作る。HTMLファイルのボタンは、UIを閉じるために、google.script.host APIの特別なclose()methodを起動する。

Note that the first time you want to display this user interface, you must either run the onOpen() function manually in the script editor or reload the window for the Docs, Sheets, or Forms editor (which will close the script editor). After that, the custom menu should appear within a few seconds every time you open the file. Choose Dialog > Open to see the interface.

初めて、このUIを表示させたい時に、onOpen()関数をscript editorで手動で実行するか、docs,sheets,またはforms自体をreload(こうすると、script editorは閉じられる)する必要がある。その後、ファイルを開くたびに数秒後に、カスタムメニューが現れる。UIを開くために、Dialog > Open を選択してください。

Scripts Bound to Google Sheets, Docs, or Forms - sheets, docs, formsに紐づけられたscript

• https://developers.google.com/apps-script/guides/bound?hl=ja#containerBound

A script is bound to a Google Sheets, Docs, or Forms file if it was created from that document rather than as a standalone script. Bound scripts generally behave like standalone scripts except that they do not appear in Google Drive, they cannot be detached from the file they are bound to, and they gain a few special privileges over the parent file.

standaloneなscriptとしてではなく、そのdocumentから作成されたのなら、scriptは、Google Sheets, Docs, or Formsのファイルに紐づいている。紐づけられたscripts(以下、bound script)は、概してstandaloneのscriptsと同じように振る舞うが、google driveには現れず、紐づけられたファイルから切り離すことはできず、親の(紐づけられた)ファイル上でいくつかの特別な権限を得る

Note that scripts can also be bound to Google Sites, but these scripts are almost always deployed as web apps. Scripts bound to Sheets, Docs, or Forms can also become web apps, although this is uncommon.

google sites にもscriptsを紐づけることはできるが、その場合は、scriptsは、たいていwebappsとしてdeployされる。sheets, docs, forms に紐づけられたscriptも、webappsにできるけれども、あんま一般的じゃない。

Creating a bound script - bound scriptを作成する

To create a bound script, open a Google Sheets, Docs, or Forms file, then select Tools > Script editor. To reopen the script in the future, do the same thing. Because bound scripts do not appear in Google Drive, that menu is the only way to find or open the script.

bound scriptを作るために、sheets,docs,formsのファイルを開き、Tools > script editor を選択する。scriptを再度開く際は同様に。なぜなら、dound scirptsは、google drive には現れず、このメニューが、唯一そのscriptを見つけて開く手段だから。

Special methods - 特別なmethod

Bound scripts can call a few methods that standalone scripts cannot:

bound scriptsは、standaloneのscriptsにできないいくつかのmethodを呼べる

・getActiveSpreadsheet(), getActiveDocument(), and getActiveForm() allow bound scripts to refer to their parent file without referring to the file's ID.

getActiveSpreadsheet(), getActiveDocument(), and getActiveForm()は、参照先のファイルのIDがなくても、親のファイルを参照できる

・getUi lets bound scripts access the user interface for their parent file to add custom menus, dialogs, and sidebars.

getUiを用いて、カスタムメニューやダイアログやサイドバーを足すために、親のファイルにアクセスできる

・In Google Sheets, getActiveSheet(), getActiveRange(), and getActiveCell() let the script determine the user's current sheet, selected range of cells, or selected individual cell. setActiveSheet(sheet) and setActiveRange(range) let the script change those selections.

google sheets では、 getActiveSheet(), getActiveRange(), and getActiveCell()を用いて、ユーザーの現在のシート、選択したセルの範囲、選択した個別のセルを特定することができる。
setActiveSheet(sheet) and setActiveRange(range)を用いてこれらの選択を変更することができる

・In Google Docs, getCursor() and getSelection() let the script determine the position of the user's cursor or selected text. setCursor(position) and setSelection(range) let the script change those locations.

google docs では、getCursor() and getSelection()を用いて、ユーザーのカーソルや、選択したtextを特定することができ、setSelection(range)を用いて、その位置を変更することができる

For more information, see the guide to extending Google Sheets or the guide to extending Google Docs.

さらなる情報は、ガイド見てね

Custom menus, dialogs, and sidebars - カスタムメニュー、ダイアログ、サイドバー

Bound scripts can customize Google Sheets, Docs, and Forms by adding custom menus and dialog boxes or sidebars. Keep in mind, however, that a script can only interact with the user interface for the current instance of an open file. That is, a script bound to one document cannot affect the user interface of another document.

bound scriptsは、sheets,docs,formsに、カスタムメニューやダイアログboxやサイドバーを追加することができる。しかし、開かれたファイルの今のinstanceのみに影響するインターフェースであることを忘れないで。つまり、1つのdocumentに紐づけられたscriptは、他のdocumentのUIに影響を与えることはできない。

Add-ons

Add-ons run inside Google Sheets, Docs, and Forms. If you've developed a bound script and want to share it with the world, Apps Script lets you publish your script as an add-on so other users can install it from the add-on store.

add-onはsheets,docs,formsの内部で実行される。もし、bound scriptを開発していて、そのscriptを世界に共有したいなら、Apps scriptを用いて、add-onとして公開することができ、他のユーザーはadd-onストアからインストールできる。

Triggers

Bound scripts can use simple triggers like the special onOpen() function, which runs automatically whenever a file is opened by a user who has edit access. Like all types of scripts, they can also use installable triggers.

bound scriptsは、onOpen()関数(編集権限を持ったユーザーによってファイルが開かれた際に自動で実行される)のような、簡単なトリガーを利用できる。あらゆる種類のscriptsのように、インストール可能なtriggerも利用できる

Custom functions

A custom function is a function in a script bound to Google Sheets that you call directly from a cell using the syntax =myFunctionName(). Custom functions are thus similar to the hundreds of built-in functions in Sheets like AVERAGE or SUM except that you define the custom function's behavior.

カスタム関数は、=myFunctioName()という文法を使っているセルから直接呼ばれる sheets固有のscriptの中の関数である。カスタム関数は、したがって、built-inの関数と同様(以下略)。

Access to bound scripts

Only users who have permission to edit a spreadsheet, document, or form can run its bound script. Collaborators who have only view access cannot open the script editor, although if they make a copy of the parent file, they become the owner of the copy and will be able to see and run a copy of the script.

sheet, document,formに対して編集権限を持っているユーザーのみが、そのファイルのbound scriptを実行できる。閲覧権限のみを持っている人は、script editorを開けない。しかしながら、親のファイルのコピーを作成することはでき、コピーの所有者になって、scriptのコピーを見たり、実行したりできる。