メインコンテンツへスキップ

📘 Office Scripts 基本オブジェクト・プロパティ・メソッド

🔰 はじめに

Office Scripts は、Excel を TypeScript から操作するための自動化機能です。

この記事では、Office Scripts を使って Excel を操作するときに最初に覚えておきたい、基本的なオブジェクト・プロパティ・メソッドをまとめます。

Office Scripts では、概ね次の階層をたどって Excel の各要素を操作します。

Workbook
 ├─ Worksheet
 │   ├─ Range
 │   ├─ Table
 │   ├─ Chart
 │   └─ ...
 ├─ Table
 ├─ NamedItem
 └─ ...

基本的には、

  1. Workbook からシートを取得する
  2. Worksheet からセル範囲やテーブルを取得する
  3. 取得したオブジェクトのメソッドを使って読み書きする

という流れになります。

Office Scripts の API は ExcelScript 名前空間に定義されています。たとえばブックは ExcelScript.Workbook、ワークシートは ExcelScript.Worksheet という型になります。

🏁 main関数

Office Scripts の実行開始点は main 関数です。

function main(workbook: ExcelScript.Workbook) {
}

Office Scripts を実行すると、Excel が現在のブックを workbook 引数として main() に渡します。

したがって通常は、

function main(workbook: ExcelScript.Workbook) {
    const sheet = workbook.getActiveWorksheet();
}

のように、workbook から操作対象を取得して処理を始めます。

workbook は特別な予約語ではなく引数名です。ただし、通常はテンプレートどおり workbook としておけば問題ありません。

📚 Workbook

ExcelScript.Workbook は、現在操作している Excelブック全体を表すオブジェクトです。

Office Scripts のオブジェクト階層の入口になります。

主なメソッド

メソッド 内容
getActiveWorksheet() 現在アクティブなシートを取得
getWorksheet(name) 名前を指定してシートを取得
getWorksheets() 全シートを取得
addWorksheet(name) 新しいシートを追加
getActiveCell() 現在のアクティブセルを取得
getSelectedRange() 現在選択されている範囲を取得
getTable(name) 名前を指定してテーブルを取得
getTables() ブック内のテーブルを取得
getNamedItem(name) 定義された名前を取得

アクティブシートを取得

const sheet = workbook.getActiveWorksheet();

名前を指定してシートを取得

const sheet = workbook.getWorksheet("Sheet1");

全シートを取得

const sheets = workbook.getWorksheets();

配列として返されるため、繰り返し処理もできます。

const sheets = workbook.getWorksheets();

for (const sheet of sheets) {
    console.log(sheet.getName());
}

シートを追加

const sheet = workbook.addWorksheet("集計");

処理対象のシートが決まっている場合は、アクティブシートに依存するより getWorksheet("シート名") で明示的に取得する方が安全です。

📄 Worksheet

ExcelScript.Worksheet はExcelのワークシートを表します。

Workbookから取得して使用します。

const sheet = workbook.getWorksheet("Sheet1");

主なメソッド

メソッド 内容
getName() シート名を取得
setName(name) シート名を変更
getRange(address) セル範囲を取得
getCell(row, column) 行・列番号からセルを取得
getUsedRange() 使用されている範囲を取得
getTables() シート上のテーブルを取得
getCharts() シート上のグラフを取得
activate() シートをアクティブにする
delete() シートを削除

シート名を取得

const name = sheet.getName();

シート名を変更

sheet.setName("売上データ");

セル範囲を取得

const range = sheet.getRange("A1:C10");

行・列番号でセルを取得

const cell = sheet.getCell(0, 0);

これは A1 を取得します。

getCell(row, column) の行番号・列番号は 0始まりです。getCell(0, 0) がA1、getCell(1, 0) がA2です。

🔲 Range

ExcelScript.Range は、Office Scriptsで最も頻繁に使用するオブジェクトの一つです。

Excelのセルまたはセル範囲を表します。

const range = sheet.getRange("A1:C10");

主なメソッド

メソッド 内容
getValue() 単一セルの値を取得
getValues() 範囲の値を2次元配列で取得
setValue(value) 値を設定
setValues(values) 範囲へ2次元配列を書き込む
getText() 単一セルの表示文字列を取得
getTexts() 範囲の表示文字列を取得
getFormula() 数式を取得
getFormulas() 範囲の数式を取得
setFormula() 数式を設定
setFormulas() 複数の数式を設定
clear() 内容などをクリア
getFormat() 書式オブジェクトを取得
getRowCount() 行数を取得
getColumnCount() 列数を取得
getAddress() セルアドレスを取得
getCell() 範囲内の相対位置からセルを取得

📥 セルの値を読む

単一セル

const value = sheet.getRange("A1").getValue();

複数セル

const values = sheet.getRange("A1:C3").getValues();

getValues() は2次元配列を返します。

例えば、

A   B   C
1   2   3
4   5   6

なら、概念的には、

[
    [1, 2, 3],
    [4, 5, 6]
]

となります。

したがって、

const values = sheet.getRange("A1:C2").getValues();

const value = values[0][1];

ならB1の値を取得できます。

Excelの表形式データを処理するときは、セルを1個ずつ読むより、getValues() で範囲をまとめて取得してTypeScript側で処理する方法が基本になります。

📤 セルへ値を書く

単一セル

sheet.getRange("A1").setValue("Hello");

数値もそのまま設定できます。

sheet.getRange("A1").setValue(100);

複数セル

sheet.getRange("A1:C2").setValues([
    [1, 2, 3],
    [4, 5, 6]
]);

書き込み範囲と配列の大きさを一致させます。

setValues() では、対象Rangeの行数・列数と渡す2次元配列の大きさを一致させる必要があります。

🧮 数式を扱う

数式を取得

const formula = sheet.getRange("C1").getFormula();

数式を設定

sheet.getRange("C1").setFormula("=A1+B1");

複数セルへ設定する場合は、

sheet.getRange("C1:C3").setFormulas([
    ["=A1+B1"],
    ["=A2+B2"],
    ["=A3+B3"]
]);

のように記述します。

🧹 Rangeをクリアする

sheet.getRange("A1:C10").clear();

内容や書式などを消去できます。

何を消去するか指定することもできます。

sheet.getRange("A1:C10").clear(
    ExcelScript.ClearApplyTo.contents
);

これならセルの内容を消去します。

clear() は指定方法によって書式なども消去できます。既存帳票を操作する場合は、何を消す処理なのか確認して使用してください。

🎨 RangeFormat

セルの書式は Range から RangeFormat オブジェクトを取得して操作します。

const range = sheet.getRange("A1:C3");
const format = range.getFormat();

主なメソッド

メソッド 内容
autofitColumns() 列幅を自動調整
autofitRows() 行高を自動調整
setColumnWidth() 列幅を設定
setRowHeight() 行高を設定
getFont() フォント設定を取得
getFill() 塗りつぶし設定を取得

列幅を自動調整

sheet.getUsedRange().getFormat().autofitColumns();

フォントを太字にする

sheet.getRange("A1:C1")
    .getFormat()
    .getFont()
    .setBold(true);

このように、

Range
 ↓
RangeFormat
 ↓
RangeFont

とオブジェクトをたどって操作します。

📋 Table

Excelの「テーブルとして書式設定」で作成したテーブルは ExcelScript.Table として操作できます。

テーブルを取得

const table = workbook.getTable("Table1");

主なメソッド

メソッド 内容
getName() テーブル名を取得
getRange() テーブル全体のRangeを取得
getHeaderRowRange() 見出し行を取得
getDataBodyRange() データ部分を取得
getColumns() 列を取得
getColumnByName(name) 列名から列を取得
addRow() 行を追加
addRows() 複数行を追加
delete() テーブルを削除

データ部分を取得

const table = workbook.getTable("Table1");
const values = table.getRangeBetweenHeaderAndTotal().getValues();

列名で取得

const table = workbook.getTable("Table1");
const column = table.getColumnByName("売上");

列の意味が決まっているデータ処理では、セル番地に依存するよりExcelテーブルを使用した方が、Office Scripts側のコードを読みやすくできます。

🏷️ NamedItem

Excelの「名前の定義」もOffice Scriptsから扱えます。

const item = workbook.getNamedItem("売上範囲");

Rangeを参照している名前なら、

const range = item.getRange();

としてセル範囲を取得できます。

固定されたセル番地ではなく名前を介して処理対象を指定したい場合に利用できます。

📊 Chart

グラフは ExcelScript.Chart として操作できます。

const charts = sheet.getCharts();

名前を指定する場合は、

const chart = sheet.getChart("Chart 1");

などとして取得できます。

グラフの作成、削除、位置変更、タイトル設定などをOffice Scriptsから制御できます。

🔁 オブジェクトの取得関係

Office Scriptsでは、Excelのオブジェクトを順番に取得して操作する考え方が重要です。

例えば、

const sheet = workbook.getWorksheet("Sheet1");
const range = sheet.getRange("A1:C10");
const values = range.getValues();

は、

Workbook
   ↓ getWorksheet()
Worksheet
   ↓ getRange()
Range
   ↓ getValues()
値

という処理です。

書式なら、

workbook
    .getWorksheet("Sheet1")
    .getRange("A1:C10")
    .getFormat()
    .autofitColumns();

となります。

構造としては、

Workbook
 ↓
Worksheet
 ↓
Range
 ↓
RangeFormat
 ↓
操作

です。

このオブジェクトを取得して、そのオブジェクトが持つメソッドを呼び出すという考え方を理解しておくと、Office ScriptsのAPIを調べやすくなります。

🧱 プロパティとメソッド

Office Scriptsでは、Excelの情報取得・変更の多くがメソッドとして提供されています。

例えばシート名についても、

sheet.name

ではなく、

sheet.getName();

で取得し、

sheet.setName("集計");

で変更します。

概念的には、

取得：getXXX()
設定：setXXX()

という形が非常に多くなっています。

例えば、

range.getValue();
range.setValue(100);

sheet.getName();
sheet.setName("集計");

font.getBold();
font.setBold(true);

のようになります。

VBAの Range("A1").Value = 100 のようなプロパティへの直接代入より、Office Scriptsでは get～() と set～() のメソッドを使うAPIが中心です。

🧭 IDEのコード補完を利用する

Office ScriptsのAPIをすべて暗記する必要はありません。

例えば、

const sheet = workbook.getActiveWorksheet();

sheet.

まで入力すると、コードエディターが Worksheet で使用可能なメソッドを候補として表示します。

同様に、

const range = sheet.getRange("A1");

range.

とすれば、Range に対して使用可能なメソッドを確認できます。

Office Scriptsでは、

オブジェクトを取得
    ↓
「.」を入力
    ↓
コード補完から目的のメソッドを探す

という使い方が効率的です。

最初からAPIを暗記するより、Workbook → Worksheet → Range という基本階層だけ覚え、あとはコード補完を利用する方法がおすすめです。

🧪 基本的なサンプル

A列の数値を読み取り、2倍してB列へ出力します。

function main(workbook: ExcelScript.Workbook) {

    const sheet = workbook.getActiveWorksheet();

    const sourceRange = sheet.getRange("A1:A5");
    const values = sourceRange.getValues();

    const result = values.map(row => {
        return [Number(row[0]) * 2];
    });

    sheet.getRange("B1:B5").setValues(result);
}

処理の流れは、

Workbook
 ↓
Worksheet取得
 ↓
Range取得
 ↓
getValues()
 ↓
TypeScriptで計算
 ↓
setValues()

となっています。

Office ScriptsによるExcelデータ処理の基本形は、このパターンです。

⚡ 最初に覚えるAPI

最初からすべてのAPIを覚える必要はありません。

まずは次のものを使えるようになれば、基本的なExcel処理を作成できます。

オブジェクト API 用途
Workbook getActiveWorksheet() 現在のシート取得
Workbook getWorksheet() シート名から取得
Workbook getWorksheets() 全シート取得
Worksheet getRange() セル範囲取得
Worksheet getUsedRange() 使用範囲取得
Range getValue() 1セルを読む
Range getValues() 複数セルを読む
Range setValue() 1セルへ書く
Range setValues() 複数セルへ書く
Range getFormula() 数式を読む
Range setFormula() 数式を書く
Range clear() セルをクリア
Range getFormat() 書式取得
Table getRange() テーブル範囲取得
Table getColumnByName() 列名から取得

特に、

getWorksheet()
getRange()
getUsedRange()
getValues()
setValues()

の5つは、データ処理で使用頻度の高いAPIです。

🔄 VBAとの対応

VBA経験者なら、次のように対応させると理解しやすくなります。

VBA Office Scripts
ThisWorkbook workbook
ActiveSheet workbook.getActiveWorksheet()
Worksheets("Sheet1") workbook.getWorksheet("Sheet1")
Range("A1") sheet.getRange("A1")
Range("A1").Value range.getValue()
Range("A1").Value = 10 range.setValue(10)
Range("A1:C10").Value range.getValues()
UsedRange sheet.getUsedRange()
Cells(1,1) sheet.getCell(0,0)

特に注意が必要なのが Cells 相当のインデックスです。

VBAでは、

Cells(1, 1)

がA1ですが、Office Scriptsでは、

sheet.getCell(0, 0);

がA1です。

VBAから移行するときは、getCell() が0始まりである点に注意してください。典型的な off-by-one エラーの原因になります。

🚀 基本パターン

Office Scriptsを書くときは、まず次の形から始めると分かりやすくなります。

function main(workbook: ExcelScript.Workbook) {

    // 1. シートを取得
    const sheet = workbook.getWorksheet("Sheet1");

    // 2. 範囲を取得
    const range = sheet.getRange("A1:C10");

    // 3. Excelからデータを取得
    const values = range.getValues();

    // 4. TypeScriptで処理
    // ...

    // 5. Excelへ結果を書き込む
    // range.setValues(...);
}

Office Scriptsでは、

Excelオブジェクトを取得する → データを読む → TypeScriptで処理する → Excelへ書き戻す

という流れを基本として考えると、コードの構造を整理しやすくなります。

上に戻る