Figma REST APIでコンポーネントを取得したとき、childrenが空配列でも「削除済み」とは断定できません。空の有効なコンポーネント、取得深度不足、取得できないノードを分けて確認します。この記事では元データを残したまま確認候補を抽出します。
空・未取得・取得不可を分ける
| 取得状態 | 記録先 | 判断 |
|---|---|---|
| COMPONENTでchildrenが空配列 | reviewIds | 空の確認候補。削除の証拠ではない |
| COMPONENTでchildrenがない | childrenUnknownIds | 子要素の取得条件を確認する |
| nodes内の値がnull、documentがない | unavailableIds | 対象ファイル・ID・アクセスを確認する |
| 子要素がある | namesに保持 | 今回の空候補には含めない |
「幽霊コンポーネント」は本サイトで使っていた便宜的な呼び方で、公式の削除状態ではありません。キャッシュが原因と決めつけず、同じファイル、ノードID、ファイル版を照合します。
nodesエンドポイントをdepth=1で取得する
GET /v1/files/:key/nodesではdepth=1が指定ノードの直下の子要素を返します。ファイル全体のGET /v1/files/:keyではdepth=1がPagesを返すため、同じ数字でも取得範囲が異なります。depthは正の整数で指定し、0は使いません。
対象のノードIDをidsで指定し、取得結果のnodesを次の関数へ渡します。URL生成と分類の関数であり、認証・HTTPリクエストは含みません。既存の取得処理に組み込み、file_content:readのスコープとファイルの閲覧権限を確認します。
code.js
function buildNodesUrl(fileKey, nodeIds) {
if (!fileKey || !Array.isArray(nodeIds) || nodeIds.length === 0)
throw new Error("ファイルキーとノードIDが必要です");
return "https://api.figma.com/v1/files/" + encodeURIComponent(fileKey) +
"/nodes?depth=1&ids=" + encodeURIComponent(nodeIds.join(","));
}
function buildNodeMap(nodes) {
const names = Object.create(null);
const reviewIds = [], unavailableIds = [], childrenUnknownIds = [];
for (const id of Object.keys(nodes || {})) {
const entry = nodes[id];
const doc = entry && entry.document;
if (!doc) { unavailableIds.push(id); continue; }
names[id] = doc.name;
if (doc.type !== "COMPONENT") continue;
if (!Array.isArray(doc.children)) childrenUnknownIds.push(id);
else if (doc.children.length === 0) reviewIds.push(id);
}
return { names, reviewIds, unavailableIds, childrenUnknownIds };
}判定結果を使うときの手順
- 成功したHTTPレスポンスのnodesを分類します。HTTP失敗を空データとして扱いません。
- reviewIdsのノードを元ファイルで開き、空の部品として必要か確認します。
- childrenUnknownIdsは取得深度とレスポンスを確認します。
- unavailableIdsは存在しないIDと決めつけず、ファイル・版・権限を確認します。
- 除外が必要と確定したIDだけ、連携先の一覧に反映します。
このコードに削除処理はありません。namesに空の候補も残し、取得した情報と判断後の情報を分けます。名前だけで除外すると、同名の別コンポーネントを落とす可能性があります。
コンポーネントの参照元を調べる場合は、APIとPlugin APIの比較で処理場所を選びます。
検証範囲と関連ガイド
今回確認したのは掲載コードの構文と、該当する入力・例外処理のローカル模擬検証です。Figmaデスクトップアプリ上での動作確認とは区別しています。改稿後のコードと、元記事が参照していたGitHub上の版が一致するとは限りません。
開発環境と登録手順はFigmaプラグイン開発入門、公開はCommunityへの申請を参照してください。