Excel.WorksheetChangedEventArgs interface

  • 参考
包:
excel

提供有关引发已更改事件的工作表的信息。

注解

[ API 集：ExcelApi 1.7 ]

属性

address

获取区域地址，该地址表示特定工作表上的更改区域。
changeDirectionState

表示对删除或插入单元格时工作表中的单元格将移动的方向的更改。 这包括以下两种方案。 1. (方向，例如向下或向右) ，当新单元格或单元格插入工作表时，现有单元格将移动。 2. (方向（如向上或向左）) 从工作表中删除单元格时，剩余单元格将移动。
changeType

获取表示更改事件的触发方式的更改类型。 有关详细信息，请参阅 Excel.DataChangeType。
details

表示有关更改详细信息的信息。 在单个单元格上触发更改事件时，可以检索此属性。 如果在多个单元格上触发了已更改的事件，则无法检索此属性。
source

获取事件源。 有关详细信息，请参阅 Excel.EventSource。
triggerSource

表示事件的触发器源。 例如， 标识此本地加载项是否触发事件。
type

获取事件的类型。 有关详细信息，请参阅 Excel.EventType。
worksheetId

获取数据更改的工作表的 ID。

方法

getRange(ctx)

获取区域，该区域表示特定工作表上的更改区域。

[ API 集：ExcelApi 1.8 ]
getRangeOrNullObject(ctx)

获取区域，该区域表示特定工作表上的更改区域。 它可能会返回 null 对象。

[ API 集：ExcelApi 1.8 ]

属性详细信息

address

获取区域地址，该地址表示特定工作表上的更改区域。

address: string;

属性值

string

注解

[ API 集：ExcelApi 1.7 ]

changeDirectionState

表示对删除或插入单元格时工作表中的单元格将移动的方向的更改。 这包括以下两种方案。 1. (方向，例如向下或向右) ，当新单元格或单元格插入工作表时，现有单元格将移动。 2. (方向（如向上或向左）) 从工作表中删除单元格时，剩余单元格将移动。

changeDirectionState: Excel.ChangeDirectionState;

属性值

Excel.ChangeDirectionState

注解

[ API 集：ExcelApi 1.14 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml

async function onChange(event: Excel.WorksheetChangedEventArgs) {
    // This function is an event handler that returns the address, trigger source, 
    // and insert or delete shift directions of the change.
    await Excel.run(async (context) => {
        // Return the address where change occurred.
        console.log(`Handler for worksheet onChanged event has been triggered.`);
        console.log(`    Data changed address: ` + event.address);

        // Return the source of the event that triggered the change.
        console.log(`    Data change trigger source: ` + event.triggerSource);

        // Note：insertShiftDirection and deleteShiftDirection are exclusive and both enums can't have a value at the same time. 
        // If one has a value, then the other will return undefined.

        // If the insert shift direction is defined, return it.
        if (event.changeDirectionState.insertShiftDirection) {
            console.log(`    Cells inserted shift direction: ` + event.changeDirectionState.insertShiftDirection);
        }

        // If the delete shift direction is defined, return it.
        if (event.changeDirectionState.deleteShiftDirection) {
            console.log(`    Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
        }
    });
}  

...

// This function deletes data from a range and sets the delete shift direction to "up".
await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("A5:F5");
    range.delete(Excel.DeleteShiftDirection.up);
});

changeType

获取表示更改事件的触发方式的更改类型。 有关详细信息，请参阅 Excel.DataChangeType。

changeType: Excel.DataChangeType | "Unknown" | "RangeEdited" | "RowInserted" | "RowDeleted" | "ColumnInserted" | "ColumnDeleted" | "CellInserted" | "CellDeleted";

属性值

Excel.DataChangeType | "Unknown" | "RangeEdited" | "RowInserted" | "RowDeleted" | "ColumnInserted" | "ColumnDeleted" | "CellInserted" | "CellDeleted"

注解

[ API 集：ExcelApi 1.7 ]

details

表示有关更改详细信息的信息。 在单个单元格上触发更改事件时，可以检索此属性。 如果在多个单元格上触发了已更改的事件，则无法检索此属性。

details: Excel.ChangedEventDetail;

属性值

Excel.ChangedEventDetail

注解

[ API 集：ExcelApi 1.9 ]

示例

// This function would be used as an event handler for the Worksheet.onChanged event.
async function onWorksheetChanged(eventArgs) {
    await Excel.run(async (context) => {
        const details = eventArgs.details;
        const address = eventArgs.address;

        // Print the before and after types and values to the console.
        console.log(`Change at ${address}: was ${details.valueBefore}(${details.valueTypeBefore}),`
            + ` now is ${details.valueAfter}(${details.valueTypeAfter})`);
        await context.sync();
    });
}

source

获取事件源。 有关详细信息，请参阅 Excel.EventSource。

source: Excel.EventSource | "Local" | "Remote";

属性值

Excel.EventSource | "Local" | "Remote"

注解

[ API 集：ExcelApi 1.7 ]

triggerSource

表示事件的触发器源。 例如， 标识此本地加载项是否触发事件。

triggerSource: Excel.EventTriggerSource | "Unknown" | "ThisLocalAddin";

属性值

Excel.EventTriggerSource | "Unknown" | "ThisLocalAddin"

注解

[ API 集：ExcelApi 1.14 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml

async function onChange(event: Excel.WorksheetChangedEventArgs) {
    // This function is an event handler that returns the address, trigger source, 
    // and insert or delete shift directions of the change.
    await Excel.run(async (context) => {
        // Return the address where change occurred.
        console.log(`Handler for worksheet onChanged event has been triggered.`);
        console.log(`    Data changed address: ` + event.address);

        // Return the source of the event that triggered the change.
        console.log(`    Data change trigger source: ` + event.triggerSource);

        // Note：insertShiftDirection and deleteShiftDirection are exclusive and both enums can't have a value at the same time. 
        // If one has a value, then the other will return undefined.

        // If the insert shift direction is defined, return it.
        if (event.changeDirectionState.insertShiftDirection) {
            console.log(`    Cells inserted shift direction: ` + event.changeDirectionState.insertShiftDirection);
        }

        // If the delete shift direction is defined, return it.
        if (event.changeDirectionState.deleteShiftDirection) {
            console.log(`    Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
        }
    });
}

type

获取事件的类型。 有关详细信息，请参阅 Excel.EventType。

type: "WorksheetChanged";

属性值

"WorksheetChanged"

注解

[ API 集：ExcelApi 1.7 ]

worksheetId

获取数据更改的工作表的 ID。

worksheetId: string;

属性值

string

注解

[ API 集：ExcelApi 1.7 ]

方法详细信息

getRange(ctx)

获取区域，该区域表示特定工作表上的更改区域。

[ API 集：ExcelApi 1.8 ]

getRange(ctx: Excel.RequestContext): Excel.Range;

参数

ctx
Excel.RequestContext

返回

Excel.Range

getRangeOrNullObject(ctx)

获取区域，该区域表示特定工作表上的更改区域。 它可能会返回 null 对象。

[ API 集：ExcelApi 1.8 ]

getRangeOrNullObject(ctx: Excel.RequestContext): Excel.Range;

参数

ctx
Excel.RequestContext

返回

Excel.Range