OneNote.Paragraph class
A container for the visible content on a page. A Paragraph can contain any one ParagraphType type of content.
- Extends
Remarks
Properties
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| id | Gets the ID of the Paragraph object. Read-only. |
| image | Gets the Image object in the Paragraph. Throws an exception if ParagraphType is not Image. Read-only. |
| ink |
Gets the Ink collection in the Paragraph. Throws an exception if ParagraphType is not Ink. Read-only. |
| outline | Gets the Outline object that contains the Paragraph. Read-only. |
| paragraphs | The collection of paragraphs under this paragraph. Read only |
| parent |
Gets the parent paragraph object. Throws if a parent paragraph does not exist. Read-only. |
| parent |
Gets the parent paragraph object. Returns null if a parent paragraph does not exist. Read-only. |
| parent |
Gets the TableCell object that contains the Paragraph if one exists. If parent is not a TableCell, throws ItemNotFound. Read-only. |
| parent |
Gets the TableCell object that contains the Paragraph if one exists. If parent is not a TableCell, returns null. Read-only. |
| rich |
Gets the RichText object in the Paragraph. Throws an exception if ParagraphType is not RichText. Read-only |
| table | Gets the Table object in the Paragraph. Throws an exception if ParagraphType is not Table. Read-only. |
| type | Gets the type of the Paragraph object. Read-only. |
Methods
| add |
Add NoteTag to the paragraph. |
| add |
Add NoteTag to the paragraph. |
| delete() | Deletes the paragraph |
| get |
Get list information of paragraph |
| insert |
Inserts the specified HTML content |
| insert |
Inserts the specified HTML content |
| insert |
Inserts the image at the specified insert location.. |
| insert |
Inserts the image at the specified insert location.. |
| insert |
Inserts the paragraph text at the specifiec insert location. |
| insert |
Inserts the paragraph text at the specifiec insert location. |
| insert |
Adds a table with the specified number of rows and columns before or after the current paragraph. |
| insert |
Adds a table with the specified number of rows and columns before or after the current paragraph. |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| set(properties, options) | Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type. |
| set(properties) | Sets multiple properties on the object at the same time, based on an existing loaded object. |
| toJSON() | Overrides the JavaScript |
| track() | Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for |
| untrack() | Release the memory associated with this object, if it has previously been tracked. This call is shorthand for |
Property Details
context
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;Property Value
id
Gets the ID of the Paragraph object. Read-only.
readonly id: string;Property Value
string
Remarks
image
Gets the Image object in the Paragraph. Throws an exception if ParagraphType is not Image. Read-only.
readonly image: OneNote.Image;Property Value
Remarks
inkWords
Gets the Ink collection in the Paragraph. Throws an exception if ParagraphType is not Ink. Read-only.
readonly inkWords: OneNote.InkWordCollection;Property Value
Remarks
outline
Gets the Outline object that contains the Paragraph. Read-only.
readonly outline: OneNote.Outline;Property Value
Remarks
paragraphs
The collection of paragraphs under this paragraph. Read only
readonly paragraphs: OneNote.ParagraphCollection;Property Value
Remarks
parentParagraph
Gets the parent paragraph object. Throws if a parent paragraph does not exist. Read-only.
readonly parentParagraph: OneNote.Paragraph;Property Value
Remarks
parentParagraphOrNull
Gets the parent paragraph object. Returns null if a parent paragraph does not exist. Read-only.
readonly parentParagraphOrNull: OneNote.Paragraph;Property Value
Remarks
parentTableCell
Gets the TableCell object that contains the Paragraph if one exists. If parent is not a TableCell, throws ItemNotFound. Read-only.
readonly parentTableCell: OneNote.TableCell;Property Value
Remarks
parentTableCellOrNull
Gets the TableCell object that contains the Paragraph if one exists. If parent is not a TableCell, returns null. Read-only.
readonly parentTableCellOrNull: OneNote.TableCell;Property Value
Remarks
richText
Gets the RichText object in the Paragraph. Throws an exception if ParagraphType is not RichText. Read-only
readonly richText: OneNote.RichText;Property Value
Remarks
table
Gets the Table object in the Paragraph. Throws an exception if ParagraphType is not Table. Read-only.
readonly table: OneNote.Table;Property Value
Remarks
type
Gets the type of the Paragraph object. Read-only.
readonly type: OneNote.ParagraphType | "RichText" | "Image" | "Table" | "Ink" | "Other";Property Value
OneNote.ParagraphType | "RichText" | "Image" | "Table" | "Ink" | "Other"
Remarks
Method Details
addNoteTag(type, status)
Add NoteTag to the paragraph.
addNoteTag(type: OneNote.NoteTagType, status: OneNote.NoteTagStatus): OneNote.NoteTag;Parameters
- type
- OneNote.NoteTagType
The type of the NoteTag.
- status
- OneNote.NoteTagStatus
The status of the NoteTag.
Returns
Remarks
addNoteTag(typeString, statusString)
Add NoteTag to the paragraph.
addNoteTag(typeString: "Unknown" | "ToDo" | "Important" | "Question" | "Contact" | "Address" | "PhoneNumber" | "Website" | "Idea" | "Critical" | "ToDoPriority1" | "ToDoPriority2", statusString: "Unknown" | "Normal" | "Completed" | "Disabled" | "OutlookTask" | "TaskNotSyncedYet" | "TaskRemoved"): OneNote.NoteTag;Parameters
- typeString
-
"Unknown" | "ToDo" | "Important" | "Question" | "Contact" | "Address" | "PhoneNumber" | "Website" | "Idea" | "Critical" | "ToDoPriority1" | "ToDoPriority2"
The type of the NoteTag.
- statusString
-
"Unknown" | "Normal" | "Completed" | "Disabled" | "OutlookTask" | "TaskNotSyncedYet" | "TaskRemoved"
The status of the NoteTag.
Returns
Remarks
delete()
Deletes the paragraph
delete(): void;Returns
void
Remarks
Examples
await OneNote.run(async (context) => {
// Get the collection of pageContent items from the page.
const pageContents = context.application.getActivePage().contents;
// Get the first PageContent on the page assuming its an outline, get the outline's paragraphs.
const pageContent = pageContents.getItemAt(0);
const paragraphs = pageContent.outline.paragraphs;
const firstParagraph = paragraphs.getItemAt(0);
// Queue a command to load the id and type of the first paragraph.
firstParagraph.load("id,type");
// Run the queued commands, and return a promise to indicate task completion.
await context.sync();
// Queue a command to delete the first paragraph.
firstParagraph.delete();
// Run the command to delete it.
await context.sync();
});
getParagraphInfo()
Get list information of paragraph
getParagraphInfo(): OfficeExtension.ClientResult<OneNote.ParagraphInfo>;Returns
Remarks
insertHtmlAsSibling(insertLocation, html)
Inserts the specified HTML content
insertHtmlAsSibling(insertLocation: OneNote.InsertLocation, html: string): void;Parameters
- insertLocation
- OneNote.InsertLocation
The location of new contents relative to the current Paragraph.
- html
-
string
An HTML string that describes the visual presentation of the content. See Supported HTML for the OneNote add-ins JavaScript API.
Returns
void
Remarks
Examples
await OneNote.run(async (context) => {
// Get the collection of pageContent items from the page.
const pageContents = context.application.getActivePage().contents;
// Get the first PageContent on the page.
// Assuming its an outline, get the outline's paragraphs.
const pageContent = pageContents.getItemAt(0);
const paragraphs = pageContent.outline.paragraphs;
const firstParagraph = paragraphs.getItemAt(0);
// Queue a command to load the id and type of the first paragraph.
firstParagraph.load("id,type");
// Run the queued commands, and return a promise to indicate task completion.
await context.sync();
// Queue commands to insert before and after the first paragraph.
firstParagraph.insertHtmlAsSibling("Before", "<p>ContentBeforeFirstParagraph</p>");
firstParagraph.insertHtmlAsSibling("After", "<p>ContentAfterFirstParagraph</p>");
// Run the command to run inserts.
await context.sync();
});
insertHtmlAsSibling(insertLocationString, html)
Inserts the specified HTML content
insertHtmlAsSibling(insertLocationString: "Before" | "After", html: string): void;Parameters
- insertLocationString
-
"Before" | "After"
The location of new contents relative to the current Paragraph.
- html
-
string
An HTML string that describes the visual presentation of the content. See Supported HTML for the OneNote add-ins JavaScript API.
Returns
void
Remarks
insertImageAsSibling(insertLocation, base64EncodedImage, width, height)
Inserts the image at the specified insert location..
insertImageAsSibling(insertLocation: OneNote.InsertLocation, base64EncodedImage: string, width: number, height: number): OneNote.Image;Parameters
- insertLocation
- OneNote.InsertLocation
The location of the table relative to the current Paragraph.
- base64EncodedImage
-
string
HTML string to append.
- width
-
number
Optional. Width in the unit of Points. The default value is null and image width will be respected.
- height
-
number
Optional. Height in the unit of Points. The default value is null and image height will be respected.
Returns
Remarks
Examples
await OneNote.run(async (context) => {
// Get the collection of pageContent items from the page.
const pageContents = context.application.getActivePage().contents;
// Get the first PageContent on the page.
// Assuming its an outline, get the outline's paragraphs.
const pageContent = pageContents.getItemAt(0);
const paragraphs = pageContent.outline.paragraphs;
const firstParagraph = paragraphs.getItemAt(0);
// Queue a command to load the id and type of the first paragraph.
firstParagraph.load("id,type");
// Run the queued commands, and return a promise to indicate task completion.
await context.sync();
// Queue commands to insert before and after the first paragraph.
firstParagraph.insertImageAsSibling("Before", "R0lGODlhDwAPAKECAAAAzMzM/////wAAACwAAAAADwAPAAACIISPeQHsrZ5ModrLlN48CXF8m2iQ3YmmKqVlRtW4MLwWACH+H09wdGltaXplZCBieSBVbGVhZCBTbWFydFNhdmVyIQAAOw==");
firstParagraph.insertImageAsSibling("After", "R0lGODlhDwAPAKECAAAAzMzM/////wAAACwAAAAADwAPAAACIISPeQHsrZ5ModrLlN48CXF8m2iQ3YmmKqVlRtW4MLwWACH+H09wdGltaXplZCBieSBVbGVhZCBTbWFydFNhdmVyIQAAOw==");
// Run the command to insert images.
await context.sync();
});
insertImageAsSibling(insertLocationString, base64EncodedImage, width, height)
Inserts the image at the specified insert location..
insertImageAsSibling(insertLocationString: "Before" | "After", base64EncodedImage: string, width: number, height: number): OneNote.Image;Parameters
- insertLocationString
-
"Before" | "After"
The location of the table relative to the current Paragraph.
- base64EncodedImage
-
string
HTML string to append.
- width
-
number
Optional. Width in the unit of Points. The default value is null and image width will be respected.
- height
-
number
Optional. Height in the unit of Points. The default value is null and image height will be respected.
Returns
Remarks
insertRichTextAsSibling(insertLocation, paragraphText)
Inserts the paragraph text at the specifiec insert location.
insertRichTextAsSibling(insertLocation: OneNote.InsertLocation, paragraphText: string): OneNote.RichText;Parameters
- insertLocation
- OneNote.InsertLocation
The location of the table relative to the current Paragraph.
- paragraphText
-
string
HTML string to append.
Returns
Remarks
Examples
await OneNote.run(async (context) => {
// Get the collection of pageContent items from the page.
const pageContents = context.application.getActivePage().contents;
// Get the first PageContent on the page assuming its an outline, get the outline's paragraphs.
const pageContent = pageContents.getItemAt(0);
const paragraphs = pageContent.outline.paragraphs;
const firstParagraph = paragraphs.getItemAt(0);
// Queue a command to load the id and type of the first paragraph.
firstParagraph.load("id,type");
// Run the queued commands, and return a promise to indicate task completion.
await context.sync();
// Queue commands to insert before and after the first paragraph.
firstParagraph.insertRichTextAsSibling("Before", "Text Appears Before Paragraph");
firstParagraph.insertRichTextAsSibling("After", "Text Appears After Paragraph");
// Run the command to insert text contents.
await context.sync();
});
insertRichTextAsSibling(insertLocationString, paragraphText)
Inserts the paragraph text at the specifiec insert location.
insertRichTextAsSibling(insertLocationString: "Before" | "After", paragraphText: string): OneNote.RichText;Parameters
- insertLocationString
-
"Before" | "After"
The location of the table relative to the current Paragraph.
- paragraphText
-
string
HTML string to append.
Returns
Remarks
insertTableAsSibling(insertLocation, rowCount, columnCount, values)
Adds a table with the specified number of rows and columns before or after the current paragraph.
insertTableAsSibling(insertLocation: OneNote.InsertLocation, rowCount: number, columnCount: number, values?: string[][]): OneNote.Table;Parameters
- insertLocation
- OneNote.InsertLocation
The location of the table relative to the current Paragraph.
- rowCount
-
number
The number of rows in the table.
- columnCount
-
number
The number of columns in the table.
- values
-
string[][]
Optional 2D array. Cells are filled if the corresponding strings are specified in the array.
Returns
Remarks
insertTableAsSibling(insertLocationString, rowCount, columnCount, values)
Adds a table with the specified number of rows and columns before or after the current paragraph.
insertTableAsSibling(insertLocationString: "Before" | "After", rowCount: number, columnCount: number, values?: string[][]): OneNote.Table;Parameters
- insertLocationString
-
"Before" | "After"
The location of the table relative to the current Paragraph.
- rowCount
-
number
The number of rows in the table.
- columnCount
-
number
The number of columns in the table.
- values
-
string[][]
Optional 2D array. Cells are filled if the corresponding strings are specified in the array.
Returns
Remarks
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: OneNote.Interfaces.ParagraphLoadOptions): OneNote.Paragraph;Parameters
Provides options for which properties of the object to load.
Returns
load(propertyNames)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): OneNote.Paragraph;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
Examples
await OneNote.run(async (context) => {
// Get the collection of pageContent items from the page.
const pageContents = context.application.getActivePage().contents;
// Queue a command to load the outline property of each pageContent.
pageContents.load("outline");
// Get the first PageContent on the page, and then get its Outline.
const pageContent = pageContents._GetItem(0);
const paragraphs = pageContent.outline.paragraphs;
// Queue a command to load the id and type of each paragraph.
paragraphs.load("id,type");
// Run the queued commands, and return a promise to indicate task completion.
await context.sync();
// Write the text.
$.each(paragraphs.items, function(index, paragraph) {
console.log("Paragraph type: " + paragraph.type);
console.log("Paragraph ID: " + paragraph.id);
});
});
load(propertyNamesAndPaths)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): OneNote.Paragraph;Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
set(properties, options)
Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties: Interfaces.ParagraphUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- OneNote.Interfaces.ParagraphUpdateData
A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.
- options
- OfficeExtension.UpdateOptions
Provides an option to suppress errors if the properties object tries to set any read-only properties.
Returns
void
set(properties)
Sets multiple properties on the object at the same time, based on an existing loaded object.
set(properties: OneNote.Paragraph): void;Parameters
- properties
- OneNote.Paragraph
Returns
void
toJSON()
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original OneNote.Paragraph object is an API object, the toJSON method returns a plain JavaScript object (typed as OneNote.Interfaces.ParagraphData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): OneNote.Interfaces.ParagraphData;Returns
track()
Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you are using this object across .sync calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you needed to have added the object to the tracked object collection when the object was first created.
track(): OneNote.Paragraph;Returns
untrack()
Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You will need to call context.sync() before the memory release takes effect.
untrack(): OneNote.Paragraph;Returns
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for