플러그인과 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 | 일시적인 상호작용 상태를 변경합니다. | 선택 범위, 스크롤 위치, 패널 변경. |
예를 들어 FRange.setValues()는 SetRangeValuesCommand를 호출하고 SetRangeValuesMutation을 생산하고 undo 데이터를 준비합니다. 모든 콘텐츠 변경은 동일한 실행 경로에 따라 기존 검증, 상호 수용 및 변경 처리에 대한 다른 항목 포인트를 재사용합니다. 도, 협업 및 다이어그램의 역사는 여전히 해당 메커니즘에 달려 있습니다. 혼자 모멘트를 등록하지 않습니다.
플러그인 기능을 Facade API로 공개하기
Facade는 콘텐츠 객체에 중점을 둔 공공 인터페이스를 제공하며 내부 서비스 검색 및 명령 매개 변수 어셈블리를 숨깁니다. 확장은 기존 Facade 메소드를 구성하거나 플러그인 자체 비즈니스 명령을 호출 할 수 있습니다.
다음 확장은 generateSalesReport()를 FUniver로 추가합니다. 이 비즈니스 명령은 다음 섹션에서 구현됩니다. 이 파일에는 실행 방법, 실행 시간 등록 및 TypeScript 유형이 있습니다.
sales-report.facade.ts
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
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 를 참조하십시오.
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와 자동화
이 가이드는 어떠셨나요?