ONLYOFFICEドキュメントをロゴとカラーでカスタマイズする方法

最も簡潔な答えは、ロゴにはDocs APIのブランディングを使用し、色にはカスタムインターフェーステーマを使用することです。

ONLYOFFICE Docs エディターを自社製品の一部のように見せたい場合は、2 段階のカスタマイズが最も効率的な方法です。まず、editorConfig.customization.logoDocs API 統合でヘッダー ロゴを設定し、次にドキュメント サーバーにエディターの色を設定するためのカスタム テーマ JSON ファイルを追加します。これらは別々の仕組みであり、それぞれ異なる利用ルールが適用されます。

2026 年 10 月 7 日の ONLYOFFICE ドキュメントで確認したところ、editor-headerlogoパラメータは ONLYOFFICE Docs Developer でのみ使用可能です。公式 API ではimage、、、imageDarkおよびに対して 300×20 ピクセルの画像が指定されておりimageLight、推奨されるロゴの高さは 20 ピクセルです。一方、カスタム インターフェイス テーマは ONLYOFFICE Docs v7.0 以降サポートされており、JSON テーマ ファイルとしてドキュメント サーバーにインストールされます。現在の公式リファレンスはONLYOFFICE Docs 標準ブランディング ドキュメントであり、テーマ ファイルのワークフローはONLYOFFICE Docs でのインターフェイス テーマの変更で説明されています。

この方法は、ONLYOFFICE Docsを独自のWebアプリケーションに組み込み、ドキュメントサーバーを管理しているチームに適しています。DocSpaceやWorkspaceポータルのテーマを変更するのとは異なります。エディター自体ではなく、周囲のポータルが対象の場合は、該当製品のブランディング設定を使用してください。

ステップ1：実際にブランディングする必要があるものを確認する

ファイルを編集する前に、ブランディングに関する事項を次の3つの質問に分けて考えてみましょう。エディターのヘッダーにロゴだけが必要ですか？ツールバー、ボタン、テキスト、境界線、パネルなど、あらゆる場所にブランドカラーを適用したいですか？それとも、インターフェースの要素をさらに変更する、より高度なホワイトラベル体験が必要ですか？

• ヘッダーロゴ:を使用しますeditorConfig.customization.logo。 ONLYOFFICE はこのパラメーターを開発者専用としてマークします。
• インターフェースの色：ドキュメントサーバーにカスタムテーマのJSONファイルをインストールしてください。これはブランドカラーを設定するための適切な方法です。
• ホワイトラベルに関するより詳細な制御については、拡張ホワイトラベルのドキュメントをご確認ください。ONLYOFFICEは、これらのパラメータにはDocs Developerの拡張ホワイトラベルライセンスが必要であると述べています。

この違いが重要なのは、テーマファイルを変更してもヘッダーのロゴが自動的に置き換えられるわけではなく、ロゴオブジェクトを設定してもエディタの他の部分の色が変更されるわけではないからです。

ステップ2：明るいヘッダーと暗いヘッダー用のロゴファイルを準備する

ヘッダーの高さが20ピクセルでも判読可能な、幅広でシンプルなロゴを用意してください。APIドキュメントでは、標準ヘッダー画像バリアントの画像サイズとして300×20ピクセルが指定されています。ブランドマークのコントラストが失われる場合は、暗い背景と明るい背景用に別々のアートワークを使用してください。たとえば、濃い紺色のワードマークは淡いヘッダーでは映えますが、暗いテーマでは見えなくなってしまいます。白または明るい色のバリアントを用意することで、この問題を解決できます。

画像は、エディターが読み込める安定したHTTPS URLでホストしてください。ロゴを常に利用可能にする必要がある場合は、有効期限の短い署名付きURLは避けてください。また、実際のユーザーが使用するのと同じネットワークパスとブラウザのセキュリティポリシーを使用して、アセットをテストしてください。

ステップ3：Docs APIの設定にロゴを追加します

const config = {
  editorConfig: {
    customization: {
      logo: {
        image: "https://app.example.com/branding/logo.png",
        imageDark: "https://app.example.com/branding/logo-dark.png",
        imageLight: "https://app.example.com/branding/logo-light.png",
        url: "https://www.example.com",
        visible: true
      }
    }
  }
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

imageは、共通の作業モードのロゴです。imageDarkは、暗いまたは色付きのヘッダー用で、 はimageLight、グレーのテーマなどの明るいヘッダー用です。 はurl、ロゴをクリックしたときの行き先を制御します。空の文字列に設定するか、nullロゴをクリックできないように設定します。はvisible、ロゴを表示するかどうかを制御します。

ステップ4：明るい場所と暗い場所の両方でロゴを確認する

統合機能を使って実際のドキュメントを開き、通常のブラウザズームでヘッダーを確認してください。「ファイルが読み込まれた」だけでは成功とは言えません。ロゴは鮮明で、垂直方向に中央揃えされ、コンパクトなヘッダーの高さでも読みやすく、予期しない背景ボックスが表示されないことを確認してください。また、クリックが意図どおりに動作するかどうかも確認してください。

次に、インターフェースを暗い状態に切り替えて、再度チェックを行います。ロゴのコントラストが低下する場合は、imageDark1つのグラフィックを無理やりあらゆる環境で機能させようとするのではなく、専用のアセットを使用してください。

ステップ5：カスタムカラーテーマJSONを作成する

idインターフェイスの色については、.で始まるテーマ ファイルを作成しますtheme-。有効なテーマ タイプは ONLYOFFICE ドキュメントlightとdarkで、色は 16 進数または RGBA 表記でサポートされます。これはドキュメントのカラー スキームとは異なります。この JSON は、DOCX、XLSX、または PPTX ファイル内に保存されているテーマの色ではなく、エディターのクローム自体を変更します。

{
  "name": "Northstar Light",
  "id": "theme-northstar-light",
  "type": "light",
  "colors": {
    "toolbar-header-document": "#1E3A8A",
    "toolbar-header-spreadsheet": "#166534",
    "toolbar-header-presentation": "#B45309",
    "background-normal": "#FFFFFF",
    "background-accent-button": "#1E3A8A",
    "text-normal": "#1F2937",
    "icon-normal": "#374151"
  }
}

上記の値はサンプルパレットであり、規定のONLYOFFICEテーマではありません。パラメータ名は、ドキュメントに記載されているテーマ変数です。本番環境では、まずインパクトの大きい少数の値から始め、結果をプレビューしてから、必要に応じて拡張してください。こうすることで、コントラストの低さや状態の不整合を容易に発見できます。

ステップ6：テーマファイルをドキュメントサーバーのテーマディレクトリに配置します。

ONLYOFFICEは、カスタムテーマファイルの保存場所を以下のように文書化しています。

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Dockerの場合： JSONファイルをDocsコンテナ内の同じパスにコピーします。

sudo docker cp northstar-theme.json onlyoffice:/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes/

実際のコンテナ名またはIDに置き換えてくださいonlyoffice。デプロイメントが頻繁に再構築される場合は、一度限りのコピーを唯一の信頼できる情報源として頼らないでください。テーマをデプロイメントプロセス、イメージのカスタマイズ、または環境に適したその他の永続的なメカニズムに組み込むことで、アップグレードやコンテナの置き換えによってテーマが意図せず削除されるのを防いでください。

ステップ7：ページを更新し、キャッシュが完了するまで待ち、カスタムテーマを選択します。

公式ガイドによると、テーマリクエストのサーバーキャッシュの有効期間は5分です。ファイルを配置した後、その時間待ってからエディターを更新してください。場合によっては、ONLYOFFICEは、テーマが表示されない場合はサービスを再起動し、キャッシュをクリアすることを推奨しています。

テーマが読み込まれると、詳細設定のインターフェーステーマ一覧に表示されます。テーマを選択し、ヘッダーだけでなく、メニュー、ダイアログ、選択されたタブ、ホバー状態、無効化されたコントロール、アイコン、通知バッジ、テキストのコントラストなどを確認してください。

ステップ8：完成したブランドを単なるスクリーンショットではなく、システムとして検証する

優れたカスタムブランドは、通常の編集作業に耐えうるものでなければなりません。ドキュメント、スプレッドシート、プレゼンテーション、PDF エディタが対象範囲に含まれている場合は、それらを開いてください。一般的なダイアログやコラボレーションコントロールを試してみてください。明るい表示と暗い表示の両方を提供している場合は、両方を確認してください。キーボードフォーカス、無効状態、ホバー時のコントラスト、長いファイル名も確認してください。ヘッダーでは魅力的に見える色でも、選択したタブや二次テキストが読みにくくなる場合があります。

カスタマイズが正しく機能しているかどうかを確認する方法

設定したロゴが常に表示され、正しいロゴのバリエーションがアクティブなヘッダー上で判読可能であり、カスタムテーマがテーマ選択画面に表示され、ブランドカラーがテキストやアイコンのコントラストを損なうことなくレンダリングされ、ユーザーが実際に開くエディターの種類に関わらず、使い勝手が維持されている場合、実装は成功したとみなすことができます。

設定オブジェクトが正しく渡されているにもかかわらずロゴが変更されない場合は、まずエディションとライセンスを確認してください。API リファレンスでは、ロゴ パラメータが Docs Developer 専用とマークされているためです。カラーテーマが表示されない場合は、JSON ID と構文、ファイルの場所、コンテナの永続性、キャッシュのタイミング、およびサービスの状態を確認してください。テーマが読み込まれるものの見た目が正しくない場合は、カスタマイズをドキュメントに記載されている変数のより小さなセットに絞り込み、色を段階的に追加してください。

よくある境界線と間違い

エディターのブランディングは、DocSpaceやWorkspaceのブランディングとは異なります。

ONLYOFFICEには、カスタマイズ用のインターフェースが複数用意されています。このガイドは、ONLYOFFICE Docsエディターのブランディングに特化したものです。ポータルのブランディングコントロール、テナント名、ポータルのファビコン、および周辺のナビゲーションは、Docs APIのヘッダーロゴオブジェクトではなく、DocSpaceまたはWorkspaceの設定に属します。

ドキュメントの配色設定はインターフェースのテーマではありません

ドキュメントの配色設定は、テキスト、表、グラフ、図形などのコンテンツに影響を与えます。カスタムインターフェイステーマは、ツールバー、パネル、ボタン、アイコン、境界線、ラベルなどのエディターUI要素を制御します。変更したいサーフェスに合った設定方法を選択してください。

すべてのホワイトラベル制御機能が標準ブランディングに含まれているとは限らないことに注意してください。

ONLYOFFICEは、標準ブランディングと拡張ホワイトラベルパラメータを分離しています。インターフェースフォント、レイアウトの表示設定、または「バージョン情報」関連要素など、より詳細な制御が必要な場合は、実装を計画する前に、公式ホワイトラベルリファレンスで現在のライセンス要件を確認してください。

実用的展開チェックリスト

• ここに記載されているヘッダーロゴのカスタマイズが必要な場合は、ONLYOFFICE Docsの開発者に確認してください。
• コントラストが必要な場合は、明るいバージョンと暗いバージョンを含め、300×20ピクセルのロゴ素材を作成してください。
• editorConfig.customization.logo統合レイヤーで設定します。
• で始まるIDを持つ有効なカスタムテーマJSONを作成しますtheme-。
• テーマファイルを、ドキュメントに記載されているドキュメントサーバーのテーマディレクトリに配置してください。
• Dockerやイミュータブルなデプロイメントの場合、テーマのインストールを再現可能かつ永続的にしてください。
• 記載されているキャッシュ遅延時間を待ってから、ページを更新し、テーマを選択してください。
• 広範囲に展開する前に、コントラスト、状態、エディターの種類、明るい条件と暗い条件の両方をテストしてください。

ロゴのブランディング、インターフェースのテーマ設定、拡張ホワイトラベルコントロールを概念的に分離することで、ONLYOFFICE Docsははるかに簡単に、そして予測可能な形でカスタマイズできるようになります。まずは、望ましいブランドイメージに合致する最小限の変更から始め、実際の編集環境で検証し、それからテーマを拡張していくのが良いでしょう。

公式資料

• ONLYOFFICE Docs API：カスタマイズ – 標準ブランディング
• ONLYOFFICEヘルプセンター：ONLYOFFICE Docsでインターフェーステーマを変更する方法
• ONLYOFFICE Docs API：カスタマイズ – ホワイトラベル