Class CellImageBuilder
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
أداةإنشاءالصورفي الخلايا
"البنّاء" في CellImage ينشئ هذا المُنشئ قيمة الصورة المطلوبة لإضافة
صورة إلى خلية.
الخصائص
| الموقع | النوع | الوصف |
valueType | ValueType | نوع قيمة صورة الخلية، وهي ValueType.IMAGE. |
الطرق المتوقّفة
| الطريقة | نوع القيمة التي يتم عرضها | وصف قصير |
getUrl() | String | تحصل على عنوان URL لمصدر الصورة. |
مستندات تفصيلية
build()
تُنشئ نوع قيمة الصورة المطلوب لإضافة صورة إلى خلية. يتم إنشاء قيمة الصورة من
سمات الصورة التي تمت إضافتها إلى أداة الإنشاء، مثل عنوان URL المصدر.
الإرجاع
CellImage - رمز يمثّل الصورة المطلوب إضافتها إلى خلية.
getAltTextDescription()
تعرِض هذه السمة وصف النص البديل لهذه الصورة.
الإرجاع
String: وصف النص البديل
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getAltTextTitle()
تعرِض هذه السمة عنوان النص البديل لهذه الصورة.
الإرجاع
String: عنوان النص البديل
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getContentUrl()
تعرِض هذه السمة عنوان URL للصورة مستضافًا على Google. يتم وضع علامة على عنوان URL هذا بالحساب الذي يخصّ مقدّم الطلب،
وبذلك يمكن لأي مستخدم لديه عنوان URL الوصول إلى الصورة بفعالية بصفته مقدّم الطلب الأصلي. قد لا تتمكّن من الوصول إلى
الصورة في حال تغيير إعدادات مشاركة جدول البيانات. ينتهي صلاحية عنوان URL المعروض بعد فترة زمنية قصيرة.
const range = SpreadsheetApp.getActiveSpreadsheet().getRange("Sheet1!A1");
const value = range.getValue();
if (value.valueType == SpreadsheetApp.ValueType.IMAGE) {
console.log(value.getContentUrl());
}
الإرجاع
String: عنوان URL للصورة المستضافة على Google
setAltTextDescription(description)
لضبط وصف النص البديل لهذه الصورة.
المعلمات
| الاسم | النوع | الوصف |
description | String | وصف النص البديل الجديد للصورة |
الإرجاع
CellImage — هذه الصورة، لربط العناصر.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
setAltTextTitle(title)
لضبط عنوان النص البديل لهذه الصورة.
المعلمات
| الاسم | النوع | الوصف |
title | String | عنوان النص البديل الجديد للصورة. |
الإرجاع
CellImage — هذه الصورة، لإنشاء سلسلة.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
setSourceUrl(url)
تُستخدَم لضبط عنوان URL لمصدر الصورة.
المعلمات
| الاسم | النوع | الوصف |
url | String | عنوان URL للصورة |
الإرجاع
CellImageBuilder - هذا المُنشئ، لتسلسل العناصر.
toBuilder()
تُنشئ أداة إنشاء صور الخلايا استنادًا إلى خصائص الصورة الحالية. استخدِم setSourceUrl(url) لضبط عنوان URL لمصدر الصورة الجديدة. بعد ذلك، يمكنك إضافته إلىخلية باستخدام Range.setValue(value) أو Range.setValues(values).
const ss = SpreadsheetApp.getActiveSpreadsheet();
const range = ss.getRange("Sheet1!A1");
const value = range.getValue();
if (value.valueType == SpreadsheetApp.ValueType.IMAGE) {
const newImage =
value.toBuilder()
.setSourceUrl(
'https://www.gstatic.com/images/branding/productlogos/apps_script/v10/web-64dp/logo_apps_script_color_1x_web_64dp.png',
)
.build();
const newRange = ss.getRange("Sheet1!A2");
newRange.setValue(newImage);
}
الإرجاع
CellImageBuilder: أداة إنشاء تنشئ نوع قيمة صورة استنادًا إلى سمات الصورة المحدّدة.
الطرق المتوقّفة
getUrl()
تمّ إيقاف هذا العمود نهائيًا. لا يتوفّر عنوان URL المصدر لمعظم الصور التي تم إدراجها حديثًا.
تحصل على عنوان URL لمصدر الصورة. تعرِض سلسلة فارغة إذا لم يكن عنوان URL متوفّرًا. بالنسبة إلى معظم الصور التي تم إدراجها حديثًا، لا يتوفّر عنوان URL المصدر بغض النظر عن كيفية إدراج الصورة.
الإرجاع
String: عنوان URL لمصدر الصورة، إذا كان متاحًا، وتعرض سلسلة فارغة في حال عدم توفّره.
التفويض
تتطلّب النصوص البرمجية التي تستخدِم هذه الطريقة الحصول على إذن واحد أو أكثر من النطاقات التالية:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003e\u003ccode\u003eCellImageBuilder\u003c/code\u003e facilitates the creation and manipulation of images within Google Sheets cells.\u003c/p\u003e\n"],["\u003cp\u003eIt provides methods for setting the image source, alt text, and retrieving a Google-hosted URL.\u003c/p\u003e\n"],["\u003cp\u003eYou can build a \u003ccode\u003eCellImage\u003c/code\u003e to insert into a cell using the \u003ccode\u003ebuild()\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003etoBuilder()\u003c/code\u003e method enables modification of existing cell images and insertion into new cells.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003egetUrl()\u003c/code\u003e method is deprecated as it often returns an empty string for newly inserted images.\u003c/p\u003e\n"]]],["The `CellImageBuilder` facilitates adding images to spreadsheet cells. It constructs image values with `build()`, which requires a source URL set via `setSourceUrl()`. Alt text can be managed using `setAltTextDescription()` and `setAltTextTitle()`, and information can be retrieved by using `getAltTextDescription()` ,`getAltTextTitle()` and `getContentUrl()`. `toBuilder()` creates a new builder from an existing image. The value type for cell images is `ValueType.IMAGE`. A deprecated method, `getUrl()`, was used to retrieve source URLs.\n"],null,["# Class CellImageBuilder\n\nCellImageBuilder\n\nBuilder for [CellImage](#). This builder creates the image value needed to add an\nimage to a cell. \n\n### Properties\n\n| Property | Type | Description |\n|---------------|------------------------------------------------------------|-----------------------------------------------------------------|\n| `value``Type` | [ValueType](/apps-script/reference/spreadsheet/value-type) | The value type of the cell image, which is `Value``Type.IMAGE`. |\n\n### Methods\n\n| Method | Return type | Brief description |\n|----------------------------------------------------------------------|------------------------------------------------------------|---------------------------------------------------------------------|\n| [build()](#build()) | [CellImage](/apps-script/reference/spreadsheet/cell-image) | Creates the image value type needed to add an image to a cell. |\n| [getAltTextDescription()](#getAltTextDescription()) | `String` | Returns the alt text description for this image. |\n| [getAltTextTitle()](#getAltTextTitle()) | `String` | Returns the alt text title for this image. |\n| [getContentUrl()](#getContentUrl()) | `String` | Returns a Google-hosted URL to the image. |\n| [setAltTextDescription(description)](#setAltTextDescription(String)) | [CellImage](/apps-script/reference/spreadsheet/cell-image) | Sets the alt-text description for this image. |\n| [setAltTextTitle(title)](#setAltTextTitle(String)) | [CellImage](/apps-script/reference/spreadsheet/cell-image) | Sets the alt text title for this image. |\n| [setSourceUrl(url)](#setSourceUrl(String)) | [CellImageBuilder](#) | Sets the image source URL. |\n| [toBuilder()](#toBuilder()) | [CellImageBuilder](#) | Creates a cell image builder based on the current image properties. |\n\n### Deprecated methods\n\n| Method | Return type | Brief description |\n|-----------------------|-------------|------------------------------|\n| [getUrl()](#getUrl()) | `String` | Gets the image's source URL. |\n\nDetailed documentation\n----------------------\n\n### `build()`\n\nCreates the image value type needed to add an image to a cell. The image value is built from\nthe image properties added to the builder, such as the source URL.\n\n#### Return\n\n\n[CellImage](/apps-script/reference/spreadsheet/cell-image) --- A representation of the image to add to a cell.\n\n*** ** * ** ***\n\n### `get``Alt``Text``Description()`\n\nReturns the alt text description for this image.\n\n#### Return\n\n\n`String` --- The alt text description.\n\n#### Authorization\n\nScripts that use this method require authorization with one or more of the following [scopes](/apps-script/concepts/scopes#setting_explicit_scopes):\n\n- `https://www.googleapis.com/auth/spreadsheets.currentonly`\n- `https://www.googleapis.com/auth/spreadsheets`\n\n*** ** * ** ***\n\n### `get``Alt``Text``Title()`\n\nReturns the alt text title for this image.\n\n#### Return\n\n\n`String` --- The alt text title.\n\n#### Authorization\n\nScripts that use this method require authorization with one or more of the following [scopes](/apps-script/concepts/scopes#setting_explicit_scopes):\n\n- `https://www.googleapis.com/auth/spreadsheets.currentonly`\n- `https://www.googleapis.com/auth/spreadsheets`\n\n*** ** * ** ***\n\n### `get``Content``Url()`\n\nReturns a Google-hosted URL to the image. This URL is tagged with the account of the requester,\nso anyone with the URL effectively accesses the image as the original requester. Access to the\nimage might be lost if the spreadsheet's sharing settings change. The returned URL expires\nafter a short period of time.\n\n```javascript\nconst range = SpreadsheetApp.getActiveSpreadsheet().getRange(\"Sheet1!A1\");\nconst value = range.getValue();\nif (value.valueType == SpreadsheetApp.ValueType.IMAGE) {\n console.log(value.getContentUrl());\n}\n```\n\n#### Return\n\n\n`String` --- The Google-hosted URL of the image.\n\n*** ** * ** ***\n\n### `set``Alt``Text``Description(description)`\n\nSets the alt-text description for this image.\n\n#### Parameters\n\n| Name | Type | Description |\n|---------------|----------|---------------------------------------------|\n| `description` | `String` | The new alt text description for the image. |\n\n#### Return\n\n\n[CellImage](/apps-script/reference/spreadsheet/cell-image) --- This image, for chaining.\n\n#### Authorization\n\nScripts that use this method require authorization with one or more of the following [scopes](/apps-script/concepts/scopes#setting_explicit_scopes):\n\n- `https://www.googleapis.com/auth/spreadsheets.currentonly`\n- `https://www.googleapis.com/auth/spreadsheets`\n\n*** ** * ** ***\n\n### `set``Alt``Text``Title(title)`\n\nSets the alt text title for this image.\n\n#### Parameters\n\n| Name | Type | Description |\n|---------|----------|---------------------------------------|\n| `title` | `String` | The new alt text title for the image. |\n\n#### Return\n\n\n[CellImage](/apps-script/reference/spreadsheet/cell-image) --- This image, for chaining.\n\n#### Authorization\n\nScripts that use this method require authorization with one or more of the following [scopes](/apps-script/concepts/scopes#setting_explicit_scopes):\n\n- `https://www.googleapis.com/auth/spreadsheets.currentonly`\n- `https://www.googleapis.com/auth/spreadsheets`\n\n*** ** * ** ***\n\n### `set``Source``Url(url)`\n\nSets the image source URL.\n\n#### Parameters\n\n| Name | Type | Description |\n|-------|----------|------------------------|\n| `url` | `String` | The URL for the image. |\n\n#### Return\n\n\n[CellImageBuilder](#) --- This builder, for chaining.\n\n*** ** * ** ***\n\n### `to``Builder()`\n\nCreates a cell image builder based on the current image properties. Use [setSourceUrl(url)](#setSourceUrl(String)) to set the source URL of the new image. Then you can add it to a\ncell using [Range.setValue(value)](/apps-script/reference/spreadsheet/range#setValue(Object)) or [Range.setValues(values)](/apps-script/reference/spreadsheet/range#setValues(Object)).\n\n```javascript\nconst ss = SpreadsheetApp.getActiveSpreadsheet();\nconst range = ss.getRange(\"Sheet1!A1\");\nconst value = range.getValue();\nif (value.valueType == SpreadsheetApp.ValueType.IMAGE) {\n const newImage =\n value.toBuilder()\n .setSourceUrl(\n 'https://www.gstatic.com/images/branding/productlogos/apps_script/v10/web-64dp/logo_apps_script_color_1x_web_64dp.png',\n )\n .build();\n const newRange = ss.getRange(\"Sheet1!A2\");\n newRange.setValue(newImage);\n}\n```\n\n#### Return\n\n\n[CellImageBuilder](#) --- A builder that creates an image value type based on the given image properties.\n\nDeprecated methods\n------------------\n\n### `get``Url()`\n\n\n**Deprecated.** For most newly inserted images, the source URL is unavailable.\n\nGets the image's source URL. Returns an empty string if the URL is unavailable. For most newly\ninserted images, the source URL is unavailable regardless how the image is inserted.\n\n#### Return\n\n\n`String` --- The image's source URL if available; returns an empty string otherwise.\n\n#### Authorization\n\nScripts that use this method require authorization with one or more of the following [scopes](/apps-script/concepts/scopes#setting_explicit_scopes):\n\n- `https://www.googleapis.com/auth/spreadsheets.currentonly`\n- `https://www.googleapis.com/auth/spreadsheets`"]]
