canvas-component-utils

プロジェクトの種類

このスキルを適用する前に、package.json に @drupal-canvas/headless または @drupal-canvas/headless- で始まる依存関係があるか確認してください。存在する場合は、 Canvas Headless のコードベースです。まず canvas-headless を読んでください。ポータブルな React コンポーネントでは、既存の公開インポートパスで FormattedText と Image を使用できます。 FormattedText には、信頼できる HTML またはサニタイズ済みの HTML が必要です。ネイティブの Vue、Astro、Angular コンポーネントでは、React ユーティリティの代わりに各フレームワーク標準の代替機能を使用します。 該当する依存関係がない場合は、Canvas でレンダリングされる React コードベースです。 コンポーネントは React（index.jsx／.tsx）であり、このスキルの内容はすべて記載どおりに適用されます。 プロジェクトの種類はこの 2 種類のみです。

drupal-canvas パッケージからユーティリティをインポートします。

import { FormattedText, Image } from 'drupal-canvas';

FormattedText

props の HTML コンテンツをレンダリングするには、FormattedText を使用します。 component.yml で contentMediaType: text/html が指定されている prop には、必ず使用してください。

# component.yml
props:
  properties:
    text:
      title: Text
      type: string
      contentMediaType: text/html
      x-formatting-context: block
      examples:
        - <p>This is <strong>formatted</strong> text.</p>

import { FormattedText } from 'drupal-canvas';

const Text = ({ text, className }) => (
  <FormattedText className={className}>{text}</FormattedText>
);

FormattedText を使用する場面：

• リッチテキスト／HTML コンテンツを受け取る props
• contentMediaType: text/html が指定されている prop
• <p>、<strong>、<em>、<a> などの HTML タグを含む可能性があるコンテンツ

FormattedText を使用しない場面：

• プレーンテキストの props（contentMediaType のない type: string）
• 見出しやタイトル（通常の要素を使用してください）

Image

レスポンシブな画像をレンダリングするには、Image を使用します。レスポンシブ対応と 最適化を自動的に処理します。コンポーネントのコントラクトでは、 $ref: json-schema-definitions://canvas.module/image に一致する単一の画像オブジェクト prop を受け取るようにしてください。 そのデータを個別の imageUrl／imageAlt props に分割しないでください。

# component.yml
props:
  properties:
    image:
      title: Image
      type: object
      $ref: json-schema-definitions://canvas.module/image
      examples:
        - src: https://example.com/photo.jpg
          alt: Description of image
          width: 800
          height: 600

import { Image } from 'drupal-canvas';

const Card = ({ image }) => {
  if (!image?.src) return null;

  const { src, alt, width, height } = image;
  return (
    <Image
      src={src}
      alt={alt}
      width={width}
      height={height}
      className="w-full rounded-lg object-cover"
    />
  );
};

Image の props：

• src - 画像 URL（必須）
• alt - アクセシビリティ用の代替テキスト（必須）
• width - 元の画像の幅
• height - 元の画像の高さ
• className - スタイル設定用の Tailwind クラス