Portable Text 렌더링 컴포넌트

플러그인은 Portable Text 에디터에 커스텀 블록 타입을 추가할 수 있습니다 — YouTube 임베드, 코드 스니펫, 이미지 갤러리 등 기본 블록 세트에 포함되지 않은 모든 것. 샌드박스 플러그인은 이러한 블록의 편집 UI를 선언할 수 있지만(Block Kit 필드 사용), 공개 사이트에서 이를 렌더링하는 Astro 컴포넌트는 빌드 시점에 npm에서 로드되어야 합니다. 이것이 네이티브 플러그인이 필요한 부분입니다.

플러그인이 편집 측 필드만 필요하고 다른 누군가가 렌더링 컴포넌트를 제공하는 경우(또는 사이트가 로컬로 제공하는 경우) 샌드박스 상태를 유지할 수 있습니다. 플러그인이 렌더링 컴포넌트도 함께 제공해야 한다면 네이티브여야 합니다.

블록 타입 선언

샌드박스 및 네이티브 플러그인 모두 블록 타입을 선언할 수 있습니다. 네이티브 플러그인은 definePlugin() 내부의 admin.portableTextBlocks 아래에서 이를 수행합니다:

admin: {
	portableTextBlocks: [
		{
			type: "youtube",
			label: "YouTube Video",
			icon: "video",                       // video, code, link, link-external
			placeholder: "Paste YouTube URL...",
			fields: [                            // Block Kit fields for the editing UI
				{ type: "text_input", action_id: "id", label: "YouTube URL" },
				{ type: "text_input", action_id: "title", label: "Title" },
				{ type: "text_input", action_id: "poster", label: "Poster Image URL" },
			],
		},
	],
},

각 블록 타입은 다음을 정의합니다:

type — 블록 타입 이름 (Portable Text _type에서 사용됨).
label — 에디터의 슬래시 명령 메뉴에 표시되는 이름.
icon — video, code, link 또는 link-external. 기본적으로 일반 큐브로 폴백됩니다.
placeholder — 입력 플레이스홀더 텍스트.
fields — 편집을 위한 Block Kit 폼 필드. 생략하면 간단한 URL 입력이 표시됩니다.

공개 사이트에서 렌더링

공개 사이트에서 블록 타입을 렌더링하려면 componentsEntry에서 Astro 컴포넌트를 내보냅니다. 내보내기 이름은 blockComponents여야 합니다:

import YouTube from "./YouTube.astro";
import CodePen from "./CodePen.astro";

export const blockComponents = {
	youtube: YouTube,
	codepen: CodePen,
};

디스크립터에 componentsEntry를 설정합니다:

export function myPlugin(): PluginDescriptor {
	return {
		id: "embeds",
		version: "1.0.0",
		format: "native",
		entrypoint: "@my-org/embeds",
		componentsEntry: "@my-org/embeds/astro",
	};
}

EmDash는 플러그인 블록 컴포넌트를 <PortableText>에 자동으로 병합합니다 — 사이트 작성자는 아무것도 가져올 필요가 없습니다. 사용자가 제공한 컴포넌트(사이트의 <PortableText>의 components prop에 선언됨)가 플러그인 기본값보다 우선합니다.

패키지 내보내기

package.json에 ./astro 내보내기를 추가합니다:

{
	"exports": {
		".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
		"./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.js" },
		"./astro": { "types": "./dist/astro/index.d.ts", "import": "./dist/astro/index.js" }
	}
}

./astro 내보내기는 서버 측(Astro SSR), ./admin 내보내기는 브라우저 측(React), "." 내보내기는 디스크립터 + createPlugin입니다. 서로 다른 환경을 위해 번들링되므로 별도의 파일로 유지하십시오.

샌드박스 친화적 변형

플러그인을 샌드박스로 유지하면서도 기본 렌더링 경험을 제공하려는 경우 일반적인 패턴은:

마켓플레이스에 샌드박스 플러그인(편집 필드만)을 배포합니다.
Astro 렌더링 컴포넌트를 제공하는 별도의 네이티브 동반 패키지를 npm에 배포합니다.
둘 다 문서화합니다: 최종 사용자는 마켓플레이스에서 샌드박스 플러그인을 설치하고 렌더링을 위한 동반 패키지는 npm install로 설치합니다.

이는 원스텝 설치를 에디터 측을 샌드박스로 유지하는 것과 교환합니다. 블록 렌더링이 관련된 경우 대부분의 플러그인 작성자는 그냥 네이티브로 가는 것을 선호하지만 옵션은 존재합니다.