다음을 통해 공유

런타임 시 Office 문서에 컨트롤 추가

  • 아티클

런타임에 Microsoft Office Word 문서 및 Microsoft Office Excel 통합 문서에 컨트롤을 추가할 수 있습니다. 런타임에 제거할 수도 있습니다. 런타임에 추가하거나 제거하는 컨트롤을 동적 컨트롤이라고 합니다.

적용 대상: 이 항목의 정보는 Excel 및 Word의 문서 수준 프로젝트 및 VSTO 추가 기능 프로젝트에 적용됩니다. 자세한 내용은 Office 애플리케이션 및 프로젝트 형식에 따라 사용 가능한 기능을 참조하세요.

이 항목에서는 다음을 설명합니다.

컨트롤 컬렉션을 사용하여 런타임 시 컨트롤 관리

런타임에 컨트롤을 추가하거나, 가져오거나, 제거하려면 ControlCollection 및 ControlCollection 개체의 도우미 메서드를 사용합니다.

이러한 개체에 액세스하는 방법은 개발 중인 프로젝트의 유형에 따라 달라집니다.

컨트롤 추가

ControlCollection 및 ControlCollection 형식에는 문서 및 워크시트에 호스트 컨트롤 및 공용 Windows Forms 컨트롤을 추가하는 데 사용할 수 있는 도우미 메서드가 포함되어 있습니다. Each method name has the format Addcontrol class, where control class is the class name of the control that you want to add. 예를 들어 NamedRange 컨트롤을 문서에 추가하려면 AddNamedRange 메서드를 사용합니다.

다음 코드 예제에서는 Excel용 문서 수준 프로젝트의 NamedRange 에 Sheet1 를 추가합니다.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

액세스 및 삭제 컨트롤

Worksheet 또는 Document의 Controls 속성을 사용하여 디자인 타임에 추가한 컨트롤을 비롯한 문서의 모든 컨트롤을 반복할 수 있습니다. 디자인 타임에 추가된 컨트롤을 정적 컨트롤이라고 합니다.

컨트롤의 Delete 메서드를 호출하거나 각 컨트롤 컬렉션의 Remove 메서드를 호출하여 동적 컨트롤을 제거할 수 있습니다. 다음 코드 예제에서는 Remove 메서드를 사용하여 Excel용 문서 수준 프로젝트의 NamedRange 에서 Sheet1 를 제거합니다.

Globals.Sheet1.Controls.Remove("ChartSource");

런타임에 정적 컨트롤을 제거할 수는 없습니다. Delete 또는 Remove 메서드를 사용하여 정적 컨트롤을 제거하려고 하면 CannotRemoveControlException이 발생합니다.

참고 항목

문서의 Shutdown 이벤트 처리기에서 프로그래밍 방식으로 컨트롤을 제거하지 마세요. Shutdown 이벤트가 발생하면 문서의 UI 요소를 더 이상 사용할 수 없습니다. 문서가 닫히기 전에 컨트롤을 제거하려면 BeforeClose 또는 BeforeSave (Word), BeforeClose또는 BeforeSave (Excel)와 같은 다른 이벤트의 이벤트 처리기에 코드를 추가합니다.

문서에 호스트 컨트롤 추가

프로그래밍 방식으로 문서에 호스트 컨트롤을 추가하는 경우 컨트롤을 고유하게 식별하는 이름을 제공해야 하며 문서에서 컨트롤을 추가할 위치를 지정해야 합니다. 구체적인 지침은 다음 항목을 참조하세요.

호스트 컨트롤에 대한 자세한 내용은 호스트 항목 및 호스트 컨트롤 개요를 참조하세요.

문서를 저장하고 닫으면 동적으로 생성된 모든 호스트 컨트롤이 해당 이벤트에서 연결 해제되며 데이터 바인딩 기능이 손실됩니다. 문서를 다시 열 때 호스트 컨트롤을 다시 만드는 코드를 솔루션에 추가할 수 있습니다. 자세한 내용은 Office 문서에서 동적 컨트롤 유지를 참조하세요.

참고 항목

XmlMappedRange, XMLNode및 XMLNodes호스트 컨트롤은 프로그래밍 방식으로 문서에 추가할 수 없으므로 해당 컨트롤에 대한 도우미 메서드는 제공되지 않습니다.

문서에 Windows Forms 컨트롤 추가

프로그래밍 방식으로 문서에 Windows Forms 컨트롤을 추가하는 경우 컨트롤을 고유하게 식별하는 이름 및 컨트롤의 위치를 제공해야 합니다. Visual Studio Tools for Office Runtime은 각 컨트롤에 대한 도우미 메서드를 제공합니다. 컨트롤 위치에 대해 범위 또는 특정 좌표를 전달할 수 있도록 이러한 메서드는 오버로드됩니다.

문서를 저장하고 닫으면 동적으로 생성된 모든 Windows Forms 컨트롤이 문서에서 제거됩니다. 문서를 다시 열 때 컨트롤을 다시 만드는 코드를 솔루션에 추가할 수 있습니다. VSTO 추가 기능을 사용하여 동적 Windows Forms 컨트롤을 만드는 경우 컨트롤의 ActiveX 래퍼가 문서에 남아 있습니다. 자세한 내용은 Office 문서에서 동적 컨트롤 유지를 참조하세요.

참고 항목

프로그래밍 방식으로 Windows Forms 컨트롤을 보호된 문서에 추가할 수는 없습니다. 프로그래밍 방식으로 Word 문서 또는 Excel 워크시트의 보호를 해제하여 컨트롤을 추가하는 경우 문서를 닫을 때 컨트롤의 ActiveX 래퍼를 제거하는 추가 코드를 작성해야 합니다. 컨트롤의 ActiveX 래퍼는 보호된 문서에서 자동으로 삭제되지 않습니다.

사용자 지정 컨트롤 추가

사용자 지정 사용자 정의 컨트롤과 같은, 사용 가능한 도우미 메서드에서 지원되지 않는 Control 을 추가하려면 다음 메서드를 사용합니다.

  • Excel의 경우 AddControl 개체의 ControlCollection 메서드 중 하나를 사용합니다.

  • Word의 경우 AddControl 개체의 ControlCollection 메서드 중 하나를 사용합니다.

    컨트롤을 추가하려면 Control, 컨트롤의 위치 및 컨트롤을 고유하게 식별하는 이름을 AddControl 메서드에 전달합니다. AddControl 메서드는 컨트롤이 워크시트 또는 문서와 상호 작용하는 방법을 정의하는 개체를 반환합니다. AddControl 메서드는 ControlSite(Excel) 또는 ControlSite(Word) 개체를 반환합니다.

    다음 코드 예제에서는 AddControl 메서드를 사용하여 문서 수준 Excel 프로젝트의 워크시트에 사용자 지정 사용자 정의 컨트롤을 동적으로 추가하는 방법을 보여 줍니다. 이 예제에서 사용자 정의 컨트롤의 이름은 UserControl1이고, Range 의 이름은 range1입니다. 이 예제를 사용하려면 프로젝트의 Sheetn 클래스에서 실행합니다.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

사용자 지정 컨트롤의 멤버 사용

AddControl 메서드 중 하나를 사용하여 워크시트 또는 문서에 컨트롤을 추가한 후에는 이제 다음 두 가지 컨트롤 개체가 있습니다.

  • 사용자 지정 컨트롤을 나타내는 Control

  • 워크시트 또는 문서에 추가된 후의 컨트롤을 나타내는 ControlSite, OLEObject 또는 OLEControl 개체

    많은 속성과 메서드가 이러한 컨트롤 간에 공유됩니다. 적절한 컨트롤을 통해 이러한 멤버에 액세스하는 것이 중요합니다.

  • 사용자 지정 컨트롤에만 속하는 멤버에 액세스하려면 Control을 사용합니다.

  • 컨트롤에서 공유되는 멤버에 액세스하려면 ControlSite, OLEObject 또는 OLEControl 개체를 사용합니다.

    Control에서 공유 멤버에 액세스하는 경우 경고 또는 알림 없이 작업이 실패하거나 잘못된 결과를 생성할 수 있습니다. 필요한 메서드 또는 속성을 사용할 수 없는 경우가 아니면 항상 ControlSite, OLEObject 또는 OLEControl 개체의 메서드 또는 속성을 사용합니다. 그런 후에만 Control을 참조해야 합니다.

    예를 들어 ControlSite 클래스와 Control 클래스 둘 다에 Top 속성이 있습니다. 컨트롤 위쪽과 문서 위쪽 간의 거리를 가져오거나 설정하려면 Top 의 ControlSite속성이 아니라 Top 의 Control속성을 사용합니다.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

관련 콘텐츠