Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Dịch vụ Properties cho phép bạn lưu trữ dữ liệu đơn giản dưới dạng các cặp khoá-giá trị được giới hạn trong một tập lệnh, một người dùng tập lệnh hoặc một tài liệu mà tiện ích bổ sung được dùng. Thường được dùng để lưu trữ cấu hình của nhà phát triển hoặc lựa chọn ưu tiên của người dùng. Các thuộc tính không bao giờ được chia sẻ giữa các tập lệnh.
Đối tượng chung PropertiesService cung cấp 3 phương thức, mỗi phương thức trả về một đối tượng Properties tương tự nhưng có các quyền truy cập khác nhau, như minh hoạ trong bảng sau:
Tất cả người dùng của một tập lệnh, tiện ích bổ sung hoặc ứng dụng web
Người dùng hiện tại của một tập lệnh, tiện ích bổ sung hoặc ứng dụng web
Tất cả người dùng của một tiện ích bổ sung trong tài liệu đang mở
Thường dùng cho
Dữ liệu cấu hình trên toàn ứng dụng, chẳng hạn như tên người dùng và mật khẩu cho cơ sở dữ liệu bên ngoài của nhà phát triển
Chế độ cài đặt dành riêng cho người dùng, chẳng hạn như đơn vị đo lường theo hệ đo lường Anh hoặc hệ đo lường quốc tế
Dữ liệu dành riêng cho tài liệu, chẳng hạn như URL nguồn cho biểu đồ được nhúng
Định dạng dữ liệu
Dịch vụ Properties lưu trữ tất cả dữ liệu dưới dạng chuỗi trong các cặp khoá-giá trị. Các loại dữ liệu chưa phải là chuỗi sẽ tự động được chuyển đổi thành chuỗi, bao gồm cả các phương thức có trong các đối tượng đã lưu.
try{// Set a property in each of the three property stores.constscriptProperties=PropertiesService.getScriptProperties();constuserProperties=PropertiesService.getUserProperties();constdocumentProperties=PropertiesService.getDocumentProperties();scriptProperties.setProperty('SERVER_URL','http://www.example.com/');userProperties.setProperty('DISPLAY_UNITS','metric');documentProperties.setProperty('SOURCE_DATA_ID','1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
Để lưu dữ liệu hàng loạt, hãy truyền một bản đồ gồm các cặp khoá-giá trị đến Properties.setProperties(properties).
Mỗi cặp khoá-giá trị của đối tượng trong tham số được lưu trữ dưới dạng một thuộc tính riêng biệt:
try{// Set multiple script properties in one call.constscriptProperties=PropertiesService.getScriptProperties();scriptProperties.setProperties({'cow':'moo','sheep':'baa','chicken':'cluck'});}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
try{// Get the value for the user property 'DISPLAY_UNITS'.constuserProperties=PropertiesService.getUserProperties();constunits=userProperties.getProperty('DISPLAY_UNITS');console.log('values of units %s',units);}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
try{// Get multiple script properties in one call, then log them all.constscriptProperties=PropertiesService.getScriptProperties();constdata=scriptProperties.getProperties();for(constkeyindata){console.log('Key: %s, Value: %s',key,data[key]);}}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
Sửa đổi dữ liệu
Các phương thức getProperty() và getProperties() trả về bản sao của dữ liệu được lưu trữ, chứ không phải khung hiển thị trực tiếp, vì vậy, việc thay đổi đối tượng được trả về sẽ không cập nhật giá trị trong kho lưu trữ thuộc tính. Để cập nhật dữ liệu trong kho lưu trữ, bạn chỉ cần lưu lại dữ liệu đó:
try{// Change the unit type in the user property 'DISPLAY_UNITS'.constuserProperties=PropertiesService.getUserProperties();letunits=userProperties.getProperty('DISPLAY_UNITS');units='imperial';// Only changes local value, not stored value.userProperties.setProperty('DISPLAY_UNITS',units);// Updates stored value.}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
try{// Delete the user property 'DISPLAY_UNITS'.constuserProperties=PropertiesService.getUserProperties();userProperties.deleteProperty('DISPLAY_UNITS');}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
try{// Get user properties in the current script.constuserProperties=PropertiesService.getUserProperties();// Delete all user properties in the current script.userProperties.deleteAllProperties();}catch(err){// TODO (developer) - Handle exceptionconsole.log('Failed with error %s',err.message);}
Quản lý thuộc tính của tập lệnh theo cách thủ công
Bạn có thể thêm tối đa 50 thuộc tính tuỳ chỉnh theo cách thủ công dưới dạng các chuỗi trong các cặp khoá-giá trị trên trang cài đặt dự án. Để thêm nhiều hơn 50 thuộc tính, bạn cần thêm các thuộc tính đó theo cách có lập trình bằng cách sử dụng các phương thức được mô tả ở trên trong phần Lưu dữ liệu.
Khi đặt các thuộc tính tập lệnh trên trang cài đặt dự án, bạn không thể tham chiếu các biến tập lệnh.
Thêm thuộc tính của tập lệnh
Mở dự án Apps Script của bạn.
Ở bên trái, hãy nhấp vào Cài đặt dự án.
Để thêm tài sản đầu tiên, trong phần Script Properties (Thuộc tính tập lệnh), hãy nhấp vào Add script property (Thêm thuộc tính tập lệnh).
Để thêm thuộc tính thứ hai và các thuộc tính tiếp theo, trong phần Thuộc tính của tập lệnh, hãy nhấp vào Chỉnh sửa thuộc tính của tập lệnh>Thêm thuộc tính của tập lệnh.
Đối với Thuộc tính, hãy nhập tên khoá.
Đối với Giá trị, hãy nhập giá trị cho khoá.
(Không bắt buộc) Để thêm các thuộc tính khác, hãy nhấp vào Thêm thuộc tính của tập lệnh.
Nhấp vào Lưu thuộc tính của tập lệnh.
Chỉnh sửa thuộc tính của tập lệnh
Mở dự án Apps Script của bạn.
Ở bên trái, hãy nhấp vào Cài đặt dự án.
Trong phần Thuộc tính của tập lệnh, hãy nhấp vào Chỉnh sửa thuộc tính của tập lệnh.
Thay đổi tên khoá và giá trị khoá cho từng thuộc tính mà bạn muốn thay đổi.
Nhấp vào Lưu thuộc tính của tập lệnh.
Xoá thuộc tính của tập lệnh
Mở dự án Apps Script của bạn.
Ở bên trái, hãy nhấp vào Cài đặt dự án.
Trong phần Thuộc tính của tập lệnh, hãy nhấp vào Chỉnh sửa thuộc tính của tập lệnh.
Bên cạnh tài sản mà bạn muốn xoá, hãy nhấp vào biểu tượng Xoá close.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-08-31 UTC."],[[["\u003cp\u003eThe Properties service allows you to store simple data as key-value pairs, with separate stores for script, user, and document properties.\u003c/p\u003e\n"],["\u003cp\u003eData is stored as strings and automatically converted if it's a different data type, with access varying depending on the chosen property store.\u003c/p\u003e\n"],["\u003cp\u003eYou can save, read, modify, and delete data within these property stores using specific methods provided by the Properties service.\u003c/p\u003e\n"],["\u003cp\u003eScript properties can also be managed manually through the project settings page for a limited number of custom properties.\u003c/p\u003e\n"]]],[],null,["# Properties Service\n\nThe [Properties service](/apps-script/reference/properties) lets you store\nsimple data in key-value pairs scoped to one script, one user of a script, or\none document in which an [add-on](/workspace/add-ons/overview) is used. It is\ntypically used to store developer configuration or user preferences. Properties\nare never shared between scripts.\n\nTo view the daily quotas and storage limits for the Properties service, see\n[Quotas for Google Services](/apps-script/guides/services/quotas).\n\nComparison of property stores\n-----------------------------\n\nThe\n[`PropertiesService`](/apps-script/reference/properties/properties-service)\nglobal object offers three methods, each of which returns a similar\n[`Properties`](/apps-script/reference/properties/properties)\nobject but with different access rights, as shown in the following table:\n\n| | Script Properties | User Properties | Document Properties |\n|--------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|\n| Method to access | [getScriptProperties()](/apps-script/reference/properties/properties-service#getScriptProperties()) | [getUserProperties()](/apps-script/reference/properties/properties-service#getUserProperties()) | [getDocumentProperties()](/apps-script/reference/properties/properties-service#getDocumentProperties()) |\n| Data shared among | All users of a script, add-on, or web app | The current user of a script, add-on, or web app | All users of an add-on in the open document |\n| Typically used for | App-wide configuration data, like the username and password for the developer's external database | User-specific settings, like metric or imperial units | Document-specific data, like the source URL for an embedded chart |\n\nData format\n-----------\n\nThe Properties service stores all data as strings in key-value pairs. Data types\nthat are not already strings are automatically converted to strings, including\nmethods contained within saved objects.\n\nSaving data\n-----------\n\nTo save a single value, call the method [`Properties.setProperty(key,\nvalue)`](/apps-script/reference/properties/properties#setProperty(String,String))\nof the appropriate store, as shown in the following example: \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Set a property in each of the three property stores.\n const scriptProperties = PropertiesService.getScriptProperties();\n const userProperties = PropertiesService.getUserProperties();\n const documentProperties = PropertiesService.getDocumentProperties();\n\n scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');\n userProperties.setProperty('DISPLAY_UNITS', 'metric');\n documentProperties.setProperty('SOURCE_DATA_ID',\n '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nTo save data in bulk, pass a map of key-value pairs to\n[`Properties.setProperties(properties)`](/apps-script/reference/properties/properties#setProperties(Object)).\nEach key-value pair of the object in the parameter is stored as a separate\nproperty: \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Set multiple script properties in one call.\n const scriptProperties = PropertiesService.getScriptProperties();\n scriptProperties.setProperties({\n 'cow': 'moo',\n 'sheep': 'baa',\n 'chicken': 'cluck'\n });\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nReading data\n------------\n\nTo retrieve a single value that you have previously saved, call\n[`Properties.getProperty(key)`](/apps-script/reference/properties/properties#getProperty(String)): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Get the value for the user property 'DISPLAY_UNITS'.\n const userProperties = PropertiesService.getUserProperties();\n const units = userProperties.getProperty('DISPLAY_UNITS');\n console.log('values of units %s', units);\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nTo retrieve all values in the current property store, call\n[`Properties.getProperties()`](/apps-script/reference/properties/properties#getProperties()): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Get multiple script properties in one call, then log them all.\n const scriptProperties = PropertiesService.getScriptProperties();\n const data = scriptProperties.getProperties();\n for (const key in data) {\n console.log('Key: %s, Value: %s', key, data[key]);\n }\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nModifying data\n--------------\n\nThe methods `getProperty()` and `getProperties()` return a copy of the stored\ndata, not a live view, so changing the returned object will not update the value\nin the property store. To update the data in the store, simply save it again: \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Change the unit type in the user property 'DISPLAY_UNITS'.\n const userProperties = PropertiesService.getUserProperties();\n let units = userProperties.getProperty('DISPLAY_UNITS');\n units = 'imperial'; // Only changes local value, not stored value.\n userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nDeleting data\n-------------\n\nTo delete a single value, call\n[`Properties.deleteProperty(key)`](/apps-script/reference/properties/properties#deleteProperty(String)): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Delete the user property 'DISPLAY_UNITS'.\n const userProperties = PropertiesService.getUserProperties();\n userProperties.deleteProperty('DISPLAY_UNITS');\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nTo delete all properties in the current store, call\n[`Properties.deleteAllProperties()`](/apps-script/reference/properties/properties#deleteAllProperties()): \nservice/propertyService.gs \n[View on GitHub](https://github.com/googleworkspace/apps-script-samples/blob/main/service/propertyService.gs) \n\n```javascript\ntry {\n // Get user properties in the current script.\n const userProperties = PropertiesService.getUserProperties();\n // Delete all user properties in the current script.\n userProperties.deleteAllProperties();\n} catch (err) {\n // TODO (developer) - Handle exception\n console.log('Failed with error %s', err.message);\n}\n```\n\nManage script properties manually\n---------------------------------\n\nYou can manually add up to fifty custom properties, as strings in key-value\npairs, from the project settings page. To add more than fifty properties, you\nneed to add them programmatically using the methods described above in\n[Saving data](#saving-data).\nWhen you set script properties from the project settings page, you can't\nreference script variables.\n\n### Add script properties\n\n1. Open your Apps Script project.\n2. At the left, click **Project Settings** .\n3. To add the first property, under **Script Properties** click **Add script property**.\n4. To add second and subsequent properties, under **Script Properties** click **Edit script properties** \\\u003e **Add script property**.\n5. For **Property**, enter the key name.\n6. For **Value**, enter the value for the key.\n7. (Optional) To add more properties, click **Add script property**.\n8. Click **Save script properties**.\n\n### Edit script properties\n\n1. Open your Apps Script project.\n2. At the left, click **Project Settings** .\n3. Under **Script Properties** , click **Edit script properties**.\n4. Make changes to the key name and key value for each property you want to change.\n5. Click **Save script properties**.\n\n### Delete script properties\n\n1. Open your Apps Script project.\n2. At the left, click **Project Settings** .\n3. Under **Script Properties** , click **Edit script properties**.\n4. Next to the property that you want to delete, click Remove close.\n5. Click **Save script properties**."]]
.