管理画面とAPI

編集モード・パーツ管理・画像管理などのUIガイドと、属性・イベント・メソッド・データ構造のAPIリファレンスです。

編集モード

ZeroCode.jsでは、4つの編集モードが利用できます。

edit（編集モード）

既存のコンポーネントを編集するモードです。

add（追加モード）

新しいコンポーネントを追加するモードです。

delete（削除モード）

コンポーネントを削除するモードです。

reorder（並べ替えモード）

コンポーネントの順序を変更するモードです。

親要素選択

各編集モードで使用可能な親要素選択機能です。

パーツ管理

パーツ管理は、zcode-editorでのみ利用可能な機能です。

タイプとパーツ

共通パーツ、個別パーツ、専用パーツ

パーツ管理機能

パーツテンプレートの構造

{
  "id": "part-id",
  "title": "パーツタイトル",
  "description": "パーツの説明",
  "body": "<div>{$title:タイトル}</div>",
  "slots": {
    "slotName": {
      "allowedParts": ["part-id-1", "part-id-2"]
    }
  },
  "slotOnly": false
}

テンプレート記法の後から追加と自動初期化

パーツ管理で既存のパーツにテンプレート記法（フィールド）を後から追加した場合、既存のページデータ（page）にそのパーツを使用しているコンポーネントがあると、自動的に不足しているフィールドが初期化されます。

動作：

初期化されるデフォルト値：

使用例：

// 既存のパーツテンプレート
{
  "id": "hero-part",
  "title": "ヒーローセクション",
  "body": "<div>{$title:タイトル}</div>"
}

// 後からテンプレート記法を追加
{
  "id": "hero-part",
  "title": "ヒーローセクション",
  "body": "<div>{$title:タイトル}</div><div>{$subtitle:サブタイトル}</div>"
}

// 既存のページデータ（初期化前）
{
  "id": "hero-1",
  "part_id": "hero-part",
  "title": "既存のタイトル"
  // subtitleフィールドが存在しない
}

// データ読み込み後の自動初期化（初期化後）
{
  "id": "hero-1",
  "part_id": "hero-part",
  "title": "既存のタイトル",
  "subtitle": "サブタイトル"  // 自動的に追加・初期化される
}

オプショナルフィールドの例：

// パーツテンプレートにオプショナルフィールドを追加
{
  "id": "hero-part",
  "title": "ヒーローセクション",
  "body": "<div>{$title:タイトル}</div><div>{$subtitle?:サブタイトル}</div>"
}

// 既存のページデータ（初期化後）
{
  "id": "hero-1",
  "part_id": "hero-part",
  "title": "既存のタイトル"
  // subtitleはundefinedのまま（初期化されない）
}

オプショナルフィールドで親要素を削除したい場合：

オプショナルフィールドが空の場合、基本動作では親要素（タグ）が残ります。親要素ごと削除したい場合は、z-empty属性を使用してください。 

// パーツテンプレート（z-emptyを使用）
{
  "id": "hero-part",
  "title": "ヒーローセクション",
  "body": "<div>{$title:タイトル}</div><div z-empty=\"$subtitle\"><p>{$subtitle?:サブタイトル}</p></div>"
}

// 既存のページデータ（subtitleがundefinedの場合）
{
  "id": "hero-1",
  "part_id": "hero-part",
  "title": "既存のタイトル"
  // subtitleはundefinedのまま
}

// レンダリング結果：subtitleがundefinedの場合、<div z-empty="$subtitle">要素ごと削除される
<div>既存のタイトル</div>
<!-- subtitleのdiv要素は表示されない -->

注意: この初期化処理は、データ読み込み時（page属性が設定された時点）に自動的に実行されます。パーツテンプレートを編集した後、ページデータを再読み込みすると、新しいフィールドが自動的に初期化されます。

補足: テンプレート記法を削除した場合、ページデータにはフィールドが残りますが、パーツテンプレートには存在しないため、表示上は非表示になります。不要になったフィールドは、手動でページデータから削除するか、バックエンドで一括削除する処理を実装してください。

画像管理

画像の一覧管理（アップロード・ID 編集・削除）は zcode-editor / zcode-studio の画像管理タブで行います。ページ編集時の画像選択は zcode-cms（および Editor のページ管理）の編集パネルから行います。

画像管理機能

画像データ構造

interface ImageData {
  id: string;
  name: string;
  url: string;
  mimeType?: string;
  needsUpload?: boolean;
  scope?: 'shared' | 'page';  // 専用画像（images-special）のみ
  pageId?: string;            // scope が 'page' のとき
}

専用画像のスコープ（page-id）

ブログの記事編集など、同一ユーザーが複数ページを編集する場合、page-id 属性で専用画像をページ単位に区別できます。内部キーは従来どおり images-special です。

scope 意味 CMS 画像選択（page-id 指定時）
未指定 / shared 全ページで選択可能 表示される
page + pageId 当該 page-id の編集画面のみ 一致する pageId のみ 
<zcode-cms
  page-id="post-123"
  page="..."
  images-special="..."
></zcode-cms>

mimeType

画像のMIMEタイプ（例: image/jpeg, image/png）。base64画像の場合に設定されます。

needsUpload

trueの場合、バックエンドで画像のアップロード処理が必要です。通常、base64画像はneedsUpload: trueとして保存されます。

画像選択モーダル

編集パネルから画像を選択する際に表示されるモーダルです（zcode-cms および Editor のページ管理）。

設定オプション

ZeroCode.jsでは、config属性で初期設定を指定できます。

設定の構造

設定はcms、dev、および共通設定の3つのカテゴリに分離されています。 

{
  "cms": {
    "allowDynamicContentInteraction": false,
    "devRightPadding": false,
    "enableContextMenu": false
  },
  "dev": {
    "showDataViewer": false,
    "enableTemplateSuggestions": false
  },
  "categoryOrder": "common"
}

設定の優先順位

  1. localStorage: ユーザーが変更した設定（最優先）
  2. config属性: 初期設定として指定された値
  3. デフォルト値: 全てfalse

CMS設定（cms）

zcode-cmsとzcode-editorの両方で共有される設定です。

allowDynamicContentInteraction

デフォルト: false

アコーディオン、タブ、モーダル、リンクなどの動的コンテンツの動作を有効/無効にします。

設定パネルでは「ページの動作を有効にする」として表示されます。

devRightPadding

デフォルト: false

編集パネル表示時にコンテンツの右余白を追加します。

設定パネルでは「編集パネル分の余白をつける」として表示されます。

enableContextMenu

デフォルト: false

右クリックメニューを有効にします。

設定パネルでは「右クリックメニューを有効にする」として表示されます。

Dev設定（dev）

zcode-editor専用の設定です。

showDataViewer

デフォルト: false

データビューアを表示します。

設定パネルでは「データビューアを表示」として表示されます。

enableTemplateSuggestions

デフォルト: false

テンプレート記法の予測変換を有効にします。

パーツ管理パネルのエディタで使用されます。

共通設定

zcode-cmsとzcode-editorの両方で使用される設定です。

categoryOrder

デフォルト: "common"

パーツ管理、画像管理、データビューア、追加パネルにおける「共通」「個別」「専用」タブの表示順序と初期選択を制御します。

設定可能な値:

この設定は以下の画面に適用されます:

設定の使用例

<zcode-cms
  config='{"cms": {"allowDynamicContentInteraction": true, "devRightPadding": true, "enableContextMenu": true}, "categoryOrder": "individual"}'
></zcode-cms>

<zcode-editor
  config='{"cms": {"allowDynamicContentInteraction": true}, "dev": {"showDataViewer": true}, "categoryOrder": "individual"}'
></zcode-editor>

または、JavaScript変数で指定することもできます：

const cmsConfig = {
  cms: {
    allowDynamicContentInteraction: true,
    devRightPadding: true,
    enableContextMenu: true
  },
  categoryOrder: 'individual'
};

const cmsElement = document.getElementById('cms');
cmsElement.setAttribute('config', JSON.stringify(cmsConfig));

APIリファレンス

zcode-cms

ユーザー向け管理画面のWebコンポーネント。

属性

属性名 型 説明
page string ページデータ（JSON文字列）
page-id string 専用画像のページスコープ用 ID（記事 ID など）。指定時、画像選択モーダルでは「全ページ」(shared) と当該 page-id の「このページ」(scope: 'page') のみ表示。CMS から専用画像を追加すると scope: 'page' が付与される
parts-common string 共通パーツデータ（JSON文字列）
parts-individual string 個別パーツデータ（JSON文字列）
parts-special string 専用パーツデータ（JSON文字列）
images-common string 共通画像データ（JSON文字列）
images-individual string 個別画像データ（JSON文字列）
images-special string 専用画像データ（JSON文字列）
config string 初期設定データ（JSON文字列）
use-shadow-dom string Shadow DOMを使用するか（'true' | 'false'、デフォルト: 'true'）

スロット

zcode-editor

エンジニア・デザイナー向け管理画面のWebコンポーネント。

ZeroCodeCMSの機能に加えて、パーツ管理・画像管理・データビューアが利用できます。

属性

zcode-cmsの属性（page-id 含む）に加えて、以下の属性が利用できます：

属性名 型 説明
enable-parts-manager string パーツ管理を有効にするか（デフォルト: 'true'）
enable-images-manager string 画像管理を有効にするか（デフォルト: 'true'）

renderToHtml()

ページコンポーネントからHTML文字列を生成します。CSSは含まれません。

Node や SSR では zerocodejs/ssr から import することを推奨します（軽量エントリ。Vue / Web Components は含みません）。ブラウザ用の一括 import は zerocodejs のままでも問題ありません。 

import { renderToHtml } from 'zerocodejs/ssr';

const html = renderToHtml(data, {
  enableEditorAttributes: false
});

パラメータ

戻り値

生成されたHTML文字列

renderCssToHtml()

CSSデータから<style>タグのHTML文字列を生成します。common → individual → special の順で出力されます。 

import { renderToHtml, renderCssToHtml } from 'zerocodejs/ssr';

const content = renderToHtml(data, { enableEditorAttributes: false });
const styles = renderCssToHtml(data.css);

// content は <body> に、styles は <head> に配置

パラメータ

戻り値

<style>タグを含むHTML文字列。空やundefinedのカテゴリはスキップされます。

イベント

save-request

保存ボタンクリック時に発火します。event.detail に data は含まれません。保存対象のデータは cms.getData() で取得してください。 

cms.addEventListener('save-request', (event) => {
  const { requestId, source, targets, timestamp } = event.detail;
  const data = cms.getData();
  for (const target of targets) {
    // target ごとに data から必要な部分を切り出してサーバーへ送る
  }
});

event.detail

含まれないもの: target（単数）・data。データは cms.getData() で取得する。

zcode-dom-updated

DOMが更新されたときに発火します。動的コンテンツの初期化などに使用できます。

window.addEventListener('zcode-dom-updated', () => {
  // DOM更新後の処理
  initializeAccordion();
});

メソッド

getData(path?: string)

データを取得します。

const cms = document.getElementById('cms');

// 全体のデータを取得
const allData = cms.getData();

// 特定のパスのデータを取得
const pageData = cms.getData('page');
const firstComponent = cms.getData('page.0');
const title = cms.getData('page.0.title');

パラメータ

戻り値

指定したパスのデータ。パスが指定されていない場合は全体のデータを返します。

setData(path: string | object, value?: any)

データを設定します。

const cms = document.getElementById('cms');

// パスを指定して値を設定
cms.setData('page.0.title', '新しいタイトル');

// オブジェクト全体を設定
cms.setData({
  page: [...],
  parts: {
    common: [...],
    individual: [...]
  }
});

セキュリティ注意: このメソッドはクライアント側から任意のデータを設定できます。開発者ツールからも呼び出し可能です。サーバー側での検証を必ず実装してください。

パラメータ

allowDynamicContentInteraction（プロパティ）

動的コンテンツの動作を有効/無効にします（getter/setter）。

const cms = document.getElementById('cms');

// 値を取得
const isEnabled = cms.allowDynamicContentInteraction;

// 値を設定
cms.allowDynamicContentInteraction = true;

データ構造

ZeroCode.jsで使用するデータ構造の説明です。

ZeroCodeData

interface ZeroCodeData {
  page: ComponentData[];
  parts: {
    common: TypeData[];
    individual: TypeData[];
    special: TypeData[];
  };
  images: {
    common: ImageData[];
    individual: ImageData[];
    special: ImageData[];
  };
}

ComponentData

interface ComponentData {
  id: string;
  part_id: string;
  [key: string]: any;
  slots?: Record<string, ComponentData[] | SlotConfig>;
}

SlotConfig

interface SlotConfig {
  allowedParts?: string[];
  children?: ComponentData[];
}

TypeData

interface TypeData {
  id: string;
  type: string;
  description: string;
  parts: PartData[];
}

PartData

interface PartData {
  id: string;
  title: string;
  description: string;
  body: string;
  slots?: Record<string, { allowedParts?: string[] }>;
  slotOnly?: boolean;
}

ImageData

interface ImageData {
  id: string;
  name: string;
  url: string;
  mimeType?: string;
  needsUpload?: boolean;
}