플러그인과 Facade 확장

필요한 기능을 조합하고 공개 API로 콘텐츠와 업무 UI를 확장합니다.

Univer는 플러그인에서 제품 및 기능을 구축하고 Facade API를 통해 콘텐츠 작업을 노출합니다. 응용 프로그램은 콘텐츠 엔진, 기능 및 UI를 선택하여 필요한 경우 플러그인으로 자체 비즈니스 로직을 패키지하고 애플리케이션 및 에이전트 도구에 대한 유형 방법을 제공합니다.

필요한 콘텐츠 기능 조합하기

Preset는 빠른 시작을 위해 예정된 플러그인의 preassembled 컬렉션입니다. 플러그인 모드에서 호스트는 제품, 기능 및 구성을 명시적으로 선택합니다. 두 모드 모두 동일한 플러그인 메커니즘을 사용합니다.

계층역할주요 구성 요소
제품과 콘텐츠 모델Unit, 콘텐츠 구조, 기본 작업을 관리합니다.Sheet, Doc, Slide, Relational Table, Canvases, PDF 제품 플러그인.
기능 플러그인특정 분야의 기능을 추가합니다.수식, 필터, 차트, 댓글 등.
UI와 렌더링 플러그인화면과 상호작용 진입점을 제공합니다.Canvas 렌더링, 메뉴, 도구 모음, 단축키, 컴포넌트.
Facade 확장설치된 기능의 공개 호출 인터페이스를 제공합니다.통합 문서, 범위, 문서, 객체 작업과 의미 기반 이벤트.

UI에서 제품 로직을 분리하는 것은 Node.js에서 실행할 수 있는 적절한 콘텐츠 기능을 허용하거나 브라우저에서 사용할 수 있습니다. 헤드리스 호스트는 메뉴, DOM 및 상호 작용 API가 여전히 UI 환경을 필요로 하는 동안 콘텐츠 플러그인에만 등록합니다.

의존성, 생명 주기, 리소스 소유권

플러그인은 @DependentOn(...)와 직접적인 의존성을 선언하고, 런타임은 그(것)들을 해결하고 건설 순서를 결정합니다. 의존성 플러그인이 누락될 때, 런 타임은 기본 구성으로 등록합니다. 의존도가 사용자 정의 구성을 필요로 할 때, 등록하고 먼저 구성합니다. 이 메커니즘은 패키지를 설치하지 않으며, 스타일 가져 오기, 로컬, Facade 항목 또는 노동자가 아닙니다.

플러그인 내에서, 의존성 주입 (DI)는 공공 서비스 식별자를 통해 서비스, 컨트롤러 및 모델을 연결합니다. 플랫폼 구현은 지원된 구성 또는 주입 경계로 대체 될 수 있으므로 비즈니스 논리는 모든 의존성 자체를 구성하고 관리 할 필요가 없습니다.

생명 주기적합한 작업
onStarting()의존성, 명령, 컨트롤러를 등록합니다. 아직 생성되지 않은 Unit이나 DOM을 읽지 않습니다.
onReady()해당 콘텐츠가 준비되면 모델에 따라 달라지는 논리를 초기화합니다.
onRendered()렌더러, Canvas, DOM이 필요한 확장을 초기화합니다.
onSteady()초기 렌더링이 필요하지 않는 Defer 작업.

소유자는 명령 등록, 이벤트 구독, 단축키 및 렌더링 모듈을 관리합니다. 등록이 플러그인 또는 컨트롤러와 함께 출시되는 disposeWithMe()를 호출 할 때 mergeMenu()는 현재 void을 반환하고 일회용이 아닙니다.

서로 다른 진입점에서 콘텐츠 변경 메커니즘 공유하기

도구 모음, 단축키 및 비즈니스 API는 동일한 비즈니스 명령을 호출 할 수 있습니다. 에이전트 호스트는 필요한 기능을 설치 한 후 입력 지점을 재사용 할 수 있습니다. 명령 시스템은 비즈니스 의도, 지속적 변경 및 일시적 상호 작용을 분리합니다.

유형역할예시
COMMAND대상을 검증하고 업무 단계, Mutation, Operation을 구성합니다.매출 보고서 작성, 행 삭제.
MUTATION명시적, serializable 매개 변수를 통해 콘텐츠 모델을 변경하여 변경을 재생하고 협업하여 처리 할 수 있습니다.셀 내용 변경, 행 삽입.
OPERATION일시적인 상호작용 상태를 변경합니다.선택 범위, 스크롤 위치, 패널 변경.
100%

예를 들어 FRange.setValues()는 SetRangeValuesCommand를 호출하고 SetRangeValuesMutation을 생산하고 undo 데이터를 준비합니다. 모든 콘텐츠 변경은 동일한 실행 경로에 따라 기존 검증, 상호 수용 및 변경 처리에 대한 다른 항목 포인트를 재사용합니다. 도, 협업 및 다이어그램의 역사는 여전히 해당 메커니즘에 달려 있습니다. 혼자 모멘트를 등록하지 않습니다.

플러그인 기능을 Facade API로 공개하기

Facade는 콘텐츠 객체에 중점을 둔 공공 인터페이스를 제공하며 내부 서비스 검색 및 명령 매개 변수 어셈블리를 숨깁니다. 확장은 기존 Facade 메소드를 구성하거나 플러그인 자체 비즈니스 명령을 호출 할 수 있습니다.

다음 확장은 generateSalesReport()를 FUniver로 추가합니다. 이 비즈니스 명령은 다음 섹션에서 구현됩니다. 이 파일에는 실행 방법, 실행 시간 등록 및 TypeScript 유형이 있습니다.

sales-report.facade.ts

TypeScript
import { FUniver } from '@univerjs/core/facade';import type { ISalesReportParams } from './sales-report.plugin';import { GenerateSalesReportCommand } from './sales-report.plugin';export interface IFUniverSalesReport {  generateSalesReport(params: ISalesReportParams): Promise<boolean>;}export class FUniverSalesReport extends FUniver implements IFUniverSalesReport {  override generateSalesReport(params: ISalesReportParams): Promise<boolean> {    return this._commandService.executeCommand(GenerateSalesReportCommand.id, params);  }}FUniver.extend(FUniverSalesReport);declare module '@univerjs/core/facade' {  interface FUniver extends IFUniverSalesReport {}}

FUniver.extend()는 런타임에 메서드를 설치하고, 모듈 augmentation 만 공급 유형. 소비자는 부작용 수입을 통해 확장 파일을 실행해야합니다; 클래스를 내보내거나 플러그인을 등록하지 않는 별도의 Facade 항목을 실행하지 않습니다. 게시 된 패키지는 전용 /facade 서브 경로를 노출하고 package.json#sideEffects를 통해 등록 부작용을 보존 할 수 있습니다.

이 패턴은 extend()를 명시적으로 지원하는 Facade 클래스에만 적용됩니다. Facade 등급이 섞인 대상으로 제공 될 수 없다는 사실. 방법 이름은 명확하고 기존 방법 또는 기타 확장과 충돌하지 않아야한다.

예제: 앱과 Agent가 같은 매출 보고서 생성하기

이 최소 비즈니스 플러그인은 영어 판매 데이터, 요약 수식 및 지정된 시트의 A1:D5로 헤드러 스타일을 작성하고 그 범위를 대체합니다. 워크북 ID 및 워크 시트 ID는 현재 선택 또는 초점에서 가져온 것보다 콜러에 의해 명시적으로 전달됩니다.

명령은 먼저 대상과 범위 크기를 확인합니다. 그런 다음 기존 SetRangeValuesCommand를 호출하여 콘텐츠 교환 및 undo/redo logic이 재사용됩니다. 플러그인은 onStarting()의 명령을 등록하고 일회용을 소유합니다. 데이터는 고정되어 일러스트로만 봉사합니다. 응용 프로그램은 검증 된 비즈니스 입력으로 교체해야합니다.

예제 출력. 프리젠 테이션 색상, 번호 포맷 및 행 및 열 치수는 읽기성에 맞게 조정되었습니다.

sales-report.plugin.ts

TypeScript
import type { ICellData, ICommand, Workbook } from '@univerjs/core';import {  CommandType, DependentOn, ICommandService, Inject, Injector,  IUniverInstanceService, Plugin, UniverInstanceType,} from '@univerjs/core';import { SetRangeValuesCommand, UniverSheetsPlugin } from '@univerjs/sheets';export interface ISalesReportParams {  unitId: string;  subUnitId: string;}export const GenerateSalesReportCommand: ICommand<ISalesReportParams> = {  id: 'sales-report.command.generate',  type: CommandType.COMMAND,  handler: (accessor, params) => {    if (!params) return false;    const sheet = accessor.get(IUniverInstanceService)      .getUnit<Workbook>(params.unitId, UniverInstanceType.UNIVER_SHEET)      ?.getSheetBySheetId(params.subUnitId);    if (!sheet || sheet.getRowCount() < 5 || sheet.getColumnCount() < 4) return false;    const value: ICellData[][] = [      ['Region', 'Q1', 'Q2', 'H1 Total'].map((v) => ({        v, t: 1, s: { bg: { rgb: '#17324D' }, cl: { rgb: '#FFFFFF' }, bl: 1 },      })),      [{ v: 'East', t: 1 }, { v: 128000, t: 2 }, { v: 142000, t: 2 }, { f: '=SUM(B2:C2)' }],      [{ v: 'West', t: 1 }, { v: 96000, t: 2 }, { v: 118000, t: 2 }, { f: '=SUM(B3:C3)' }],      [{ v: 'North', t: 1 }, { v: 110000, t: 2 }, { v: 125000, t: 2 }, { f: '=SUM(B4:C4)' }],      [{ v: 'Total', t: 1 }, { f: '=SUM(B2:B4)' }, { f: '=SUM(C2:C4)' }, { f: '=SUM(D2:D4)' }],    ];    return accessor.get(ICommandService).executeCommand(SetRangeValuesCommand.id, {      ...params,      range: { startRow: 0, endRow: 4, startColumn: 0, endColumn: 3 },      value,    });  },};@DependentOn(UniverSheetsPlugin)export class SalesReportPlugin extends Plugin {  static override pluginName = 'SALES_REPORT_PLUGIN';  static override type = UniverInstanceType.UNIVER_SHEET;  constructor(    _config: undefined,    @Inject(Injector) protected override readonly _injector: Injector,    @ICommandService private readonly _commands: ICommandService,  ) { super(); }  override onStarting(): void {    this.disposeWithMe(this._commands.registerCommand(GenerateSalesReportCommand));  }}

시트 설치 가이드를 사용하여 제품 및 공식 기능을 구성하고, 비즈니스 플러그인을 등록하고 Facade 확장을 가져 와서 호출합니다. 이 예에서 univer는 그 구성이 이미 완료된 인스턴스입니다. Node.js 구성의 경우 headless Univer 를 참조하십시오.

TypeScript
import { FUniver } from '@univerjs/core/facade';import '@univerjs/sheets/facade';import '@univerjs/engine-formula/facade';import { SalesReportPlugin } from './sales-report.plugin';import './sales-report.facade';univer.registerPlugin(SalesReportPlugin);const univerAPI = FUniver.newAPI(univer);const workbook = univerAPI.createWorkbook({ name: 'Quarterly Sales' });const worksheet = workbook.getActiveSheet();const target = { unitId: workbook.getId(), subUnitId: worksheet.getSheetId() };const generated = await univerAPI.generateSalesReport(target);if (!generated) throw new Error('Sales report could not be generated');await univerAPI.getFormula().onCalculationResultApplied();console.log(worksheet.getRange('D5').getValue()); // 719000

성공적인 명령 결과는 내용 작성이 완료되었는지 나타냅니다. 계산 결과가 공식 값을 읽기 전에 적용됩니다. 이 예에서 D5는 719000입니다.

애플리케이션 버튼은 클릭 핸들러에서 generateSalesReport(target)를 호출 할 수 있습니다. 에이전트 도구 핸들러는 헤드리스 호스트가 동일한 플러그인과 Facade 확장을 설치 한 후 동일한 방법을 호출 할 수 있으며 비즈니스 액션과 대상은 동일하게 유지됩니다. UI는 항목 포인트와 피드백을 제공합니다. 사용자 정의 플러그인을 설치하면 에이전트 도구로 메소드를 자동으로 노출하지 않습니다. 도구 등록 및 Unit 권한은 응용 프로그램의 책임에 남아 있습니다.

구현 경계와 관련 문서

  • 이 예제는 SetRangeValuesCommand를 재사용합니다. 새로운 Mutation은 역동적 인 운영과 해당 협업 통합을 요구합니다. 새로운 지속 가능한 리소스는 일련화가 필요하므로 아래 모델에 직접 쓸 수 없습니다.
  • 실행, 계산, 및 제출은 별도의 단계이며, 여러 Facade 호출은 자동 원자 트랜잭션을 형성하지 않습니다. 이 예제는 단일 범위 쓰기를 수행; 공동 호스트는 여전히 제출하고 Runtime 계약에 따라 변경을 확인합니다.
  • 실행중인 환경에 따라 플러그인을 컴파일합니다. 콘텐츠 플러그인 및 UI 플러그인을 별도로 설치하고 같은 버전에서 Univer 릴리스 트레인 패키지를 유지하고 UI 복사에 대한 Locale 리소스를 사용합니다. 에이전트 항목은 여전히 응용 프로그램에 의해 소유 된 권한 및 매개 변수 검증이 필요합니다.

관련 문서: Univer 아키텍처 · Facade 설정 · Facade API 참조 · UI 사용자 지정 · Agent와 자동화

기능 개요로 돌아가기

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.