# $ref 系タグで添付ファイルの参照と表示を使いこなす
GROWI の $ref 系タグを使うと、添付ファイルへのリンク埋め込みや画像のギャラリー表示まで、さまざまな方法でページに組み込めます。
ファイル名でも添付 ID でも参照でき、別ページの添付ファイルも横断して参照・集約できます。
# こんな柔軟な運用ができます
$ref 系タグは「添付ファイルを貼る」だけのものではありません。オプションを組み合わせることで、次のような運用が可能になります。
- ファイル名で参照すれば、ファイルを差し替えても記述を変えなくてよい
同じファイル名で添付し直すだけで、ページ側の
$ref(設計書.pdf)のような記述はそのままに、最新のファイルを指し示せます。版管理されたマニュアルや定例資料の置き場として便利です。 - 別ページの添付ファイルを横断して参照・集約できる
pageやprefixを指定すると、別ページや配下のページツリーに添付されたファイルをまとめて一覧表示できます。資料を 1 か所に集約しつつ、目次ページから串刺しで見せる、といった使い方ができます。 - 複数画像をグリッド・ギャラリー形式で並べられる
$refsimgのgridオプションや$galleryを使えば、複数の画像を整列したグリッドやギャラリーとして表示できます。スクリーンショット集や写真台帳の見せ方に向いています。 - 正規表現でファイルを絞り込める
regexpを指定すると、特定の拡張子や命名規則のファイルだけを一覧・表示の対象にできます。
各タグの詳細とオプションは以下のとおりです。
# $ref タグ — 添付ファイルへのリンクを表示する
添付ファイルへのリンクを埋め込みます。
# 構文
$ref(file.txt)
$ref(file.txt, page=/somewhere/page)
$ref(5f17286fd7fbb1104fdbd111, page=/somewhere/page)
# オプション
| オプション | 必須 | 説明 |
|---|---|---|
file | どちらか一方 | 参照するファイルのファイル名（第 1 引数のデフォルト） |
id | どちらか一方 | 参照するファイルの添付 ID（第 1 引数のデフォルト） |
page | 省略可 | ファイルを検索するページパス（省略時は現在のページ） |
# 活用例
- 差し替え運用:
$ref(料金表.xlsx)と記述しておけば、毎月同じファイル名で添付し直すだけで、つねに最新版へのリンクを保てます。 - 別ページのファイルを参照:
$ref(規約.pdf, page=/legal/policies)のようにpageを指定すると、添付の実体は 1 ページに集約したまま、複数のページから同じファイルへリンクできます。
# $refs タグ — 添付ファイルの一覧を表示する
指定したページやページ群に含まれる添付ファイルの一覧を表示します。
# 構文
$refs(/somewhere/page, regexp=/^file.*\.txt$/)
# オプション
| オプション | 省略可否 | 説明 |
|---|---|---|
page | 省略可 | 検索対象のページパス（省略時は第 1 引数または現在のページ） |
prefix | 省略可 | 検索対象のページパスのプレフィックス |
depth | 省略可 | 検索するページの階層の深さ |
regexp | 省略可 | 一覧に含めるファイル名を絞り込む正規表現 |
# 活用例
- 配下ページの添付を集約:
$refs(prefix=/project/minutes)のようにprefixを指定すると、議事録ページツリー配下に散らばった添付ファイルを 1 つの目次ページにまとめて一覧できます。 - 拡張子で絞り込み:
$refs(/reports, regexp=/\.pdf$/)とすれば、対象ページの添付のうち PDF だけを一覧表示できます。
# $refimg タグ — 添付画像を表示する
添付された画像ファイルを表示します。表示サイズや代替テキストを指定できます。
# 構文
$refimg(pict.png, width=50%, alt=Pic)
$refimg(5f17286fd7fbb1104fdbd111, width=50%, alt=Pic)
# オプション
| オプション | 必須 | 説明 |
|---|---|---|
file | どちらか一方 | 参照するファイルのファイル名（第 1 引数のデフォルト） |
id | どちらか一方 | 参照するファイルの添付 ID（第 1 引数のデフォルト） |
width | 省略可 | 横幅（例: width=200px、width=50%） |
height | 省略可 | 高さ（例: height=100px） |
max-width | 省略可 | 最大横幅（例: max-width=200px、max-width=50%） |
max-height | 省略可 | 最大高さ（例: max-height=100px） |
alt | 省略可 | 代替テキスト |
# 活用例
- 差し替えできる図版:
$refimg(構成図.png, max-width=600px)と記述しておけば、構成図を更新するたびに同じファイル名で添付し直すだけで、本文中の図版も最新になります。 - 別ページのロゴやバナーを再利用:
$refimg(logo.png, page=/assets)のように共有ページの画像を参照すれば、複数ページで同じ画像を使い回せます。
# $refsimg タグ — 添付画像の一覧を表示する
指定したページやページ群に含まれる添付画像をまとめて表示します。グリッドレイアウトにも対応しています。
# 構文
$refsimg(/somewhere/page, regexp=/^.*\.png$/, max-width=200)
$refsimg(prefix=/somewhere, grid=autofill, grid-gap=1px)
# オプション
| オプション | 省略可否 | 説明 |
|---|---|---|
page | 省略可 | 検索対象のページパス（省略時は第 1 引数または現在のページ） |
prefix | 省略可 | 検索対象のページパスのプレフィックス |
depth | 省略可 | 検索するページの階層の深さ |
regexp | 省略可 | 表示対象のファイル名を絞り込む正規表現 |
width | 省略可 | 横幅（例: width=200px、width=50%） |
height | 省略可 | 高さ（例: height=100px） |
max-width | 省略可 | 最大横幅（例: max-width=200px、max-width=50%） |
max-height | 省略可 | 最大高さ（例: max-height=100px） |
display | 省略可 | 各画像の display プロパティ（grid 指定時は無効。省略時は block） |
grid | 省略可 | グリッドレイアウトの設定（下表参照） |
grid-gap | 省略可 | グリッドの間隔（例: grid-gap=1px） |
# grid オプションの値
| 値 | 説明 |
|---|---|
autofill | 64px トラックで自動埋め（autofill-md と同等） |
autofill-xs | 32px トラックで自動埋め |
autofill-sm | 48px トラックで自動埋め |
autofill-md | 64px トラックで自動埋め |
autofill-lg | 128px トラックで自動埋め |
autofill-xl | 192px トラックで自動埋め |
col-2 ～ col-6 | 2〜6 列の固定列数グリッド |
# 活用例
- スクリーンショット集をグリッド表示:
$refsimg(prefix=/manual/screens, grid=col-3, grid-gap=4px)とすれば、マニュアル配下のスクリーンショットを 3 列のグリッドで整列表示できます。 - サムネイル一覧:
$refsimg(/gallery, grid=autofill-sm)のようにautofill系を使うと、画像点数が変わってもトラック幅に合わせて自動で折り返すサムネイル一覧を作れます。
# $gallery タグ — ギャラリー形式で画像一覧を表示する
$refsimg(grid=col-4, grid-gap=1px) のショートハンドです。
指定したページ群の添付画像をギャラリー形式（4 列グリッド）で一覧表示します。
# 構文
$gallery(prefix=/somewhere/page)
# オプション
$refsimg と同じオプションが使用できます。
# 活用例
- 写真台帳・ギャラリーページ:
$gallery(prefix=/events/2026)とすれば、イベント配下のページに添付された写真を 4 列ギャラリーで手早くまとめられます。細かいレイアウト調整が必要なら$refsimgに切り替えてください。
# Tips: アクセスコントロールとライフサイクルは「添付元のページ」と一体
$ref 系タグで他ページの添付ファイルを参照する場合は、次の点に注意して運用してください。
添付ファイルの権限・ライフサイクルは添付元ページに従います
添付ファイルのアクセス権限（閲覧範囲）と削除などのライフサイクルは、ファイルが添付されている元のページに紐づいています。$ref 系タグはあくまで参照を表示するだけで、参照先の権限を上書きすることはなく、独立した権限を持たせることもありません。
そのため、次のような挙動になります。これは GROWI の基本ルール（添付ファイルは添付元ページの権限に従う）どおりの動作です。
- 閲覧範囲は添付元ページに従う: 添付元ページの閲覧権限がないユーザーには、
$ref系タグで参照しても、その添付ファイルは表示されません。参照しているページ自体が公開されていても、添付元ページが限定公開なら、権限のないユーザーには見えない場合があります。 - 削除・移動の影響を受ける: 添付元ページや添付ファイルが削除されると、それを参照しているタグの表示も無効になります。
横断参照を運用に組み込むときは、参照先ページの公開範囲をそろえておく（または全員が閲覧できるページに添付を集約する）と、ユーザーによって表示の有無が変わるトラブルを防げます。